TE_find_text

Example: TE_find_textText Retrieval Functions

Searches for text in the designated area of the terminal emulator screen.

int TE_find_text( const char *pattern, int col1, int row1, int col2, int row2, int *retcol, int *retrow, char *match );

Inputs

pattern The string to search for. The string may include a Regular Expressions. Indicate the start of a regular expression with an exclamation point (!).
col1, row1 The column and row coordinates of the top left corner of the area of the search for the string.
col2, row2 The column and row coordinates of the lower right corner of the area of the search for the string.

Outputs

retcol, retrow A pointer to the column and row coordinates at which the string actually appeared.
match A pointer to the matched string. The string is null-terminated. Be careful to allocate a large enough buffer to accommodate the match.

Note that for any of the output parameters, you can specify NULL if you do not need the value.

TE_find_text searches for text matching the pattern within the rectangle defined by col1, row1, col2, row2. Text that matches the pattern will be returned to match, and the actual row and column position will be returned to retcol and retrow. The search begins in the top-left corner of the rectangle.

The terminal emulator screen is measured in characters. The character with position 1,1 is in the top left corner of the screen. If you specify illegal values for col2 or row2 (meaning that the values are smaller than those specified for col1, row1), the function assumes the last row and column on the screen.

Note: You must allocate space for output parameters if you want to retrieve their value. Otherwise, pass NULL as the actual value of the arguments.

Return Values

This function returns 0 if it succeeds, and a negative error code if it fails. It also sets the global variable TE_errno. TE_find_text does not print an error message when it fails.

Parameterization

The following argument can be parameterized using standard parameterization: pattern