Share this page

# TE_find_text

Text 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

## Example

In the following example, after logging in as root to the machine "stimpy", TE_find_text searches for the string "UNIX*" in the terminal. The test run searches for text anywhere in the first row, without knowing the precise length of the row. Since the col2 parameter is set to -1, the function will search for text until the last column in the first line.

    int col, row;
    char match [100];

    TE_wait_text("login: ", 90);
    TE_wait_cursor(8, 5, 100, 90);
    TE_type("root<kReturn>");
    TE_wait_text("Password: ", 90);
    TE_type("qwerty<kReturn>"); /* Password is qwerty */
    TE_wait_text("stimpy:{/}# ", 90); /* Machine name is stimpy */
    TE_find_text ("*UNIX*", -1,-1,-1,1, &col, &row, match);

Tips to improve your search results... VuGen Function Reference Version 26.1 Function Reference 26.1 All View Local Help Center View Online Help Center Version: