19.4.4 Init and Destroy Functions

yylex_init and yylex_destroy must be called before and after yylex, respectively.

         int yylex_init ( yyscan_t * ptr_yy_globals ) ;
         int yylex_init_extra ( YY_EXTRA_TYPE user_defined, yyscan_t * ptr_yy_globals ) ;
         int yylex ( yyscan_t yyscanner ) ;
         int yylex_destroy ( yyscan_t yyscanner ) ;

The function yylex_init must be called before calling any other function. The argument to yylex_init is the address of an uninitialized pointer to be filled in by yylex_init, overwriting any previous contents. The function yylex_init_extra may be used instead, taking as its first argument a variable of type YY_EXTRA_TYPE. See the section on yyextra, below, for more details.

The value stored in ptr_yy_globals should thereafter be passed to yylex and yylex_destroy. Flex does not save the argument passed to yylex_init, so it is safe to pass the address of a local pointer to yylex_init so long as it remains in scope for the duration of all calls to the scanner, up to and including the call to yylex_destroy.

The function yylex should be familiar to you by now. The reentrant version takes one argument, which is the value returned (via an argument) by yylex_init. Otherwise, it behaves the same as the non-reentrant version of yylex.

Both yylex_init and yylex_init_extra returns 0 (zero) on success, or non-zero on failure, in which case errno is set to one of the following values:

• ENOMEM Memory allocation error. See memory-management.
• EINVAL Invalid argument.

The function yylex_destroy should be called to free resources used by the scanner. After yylex_destroy is called, the contents of yyscanner should not be used. Of course, there is no need to destroy a scanner if you plan to reuse it. A flex scanner (both reentrant and non-reentrant) may be restarted by calling yyrestart.

Below is an example of a program that creates a scanner, uses it, then destroys it when done:

         int main ()
         {
             yyscan_t scanner;
             int tok;
     
             yylex_init(&scanner);
     
             while ((tok=yylex(scanner)) > 0)
                 printf("tok=%d  yytext=%s\n", tok, yyget_text(scanner));
     
             yylex_destroy(scanner);
             return 0;
         }