focal (3) libmawk_initialize_stage.3libmawk.gz

NAME

       libmawk_initialize_stage* - create a new libmawk context in 3 stages

SYNOPSIS

       #include <libmawk.h>

       mawk_state_t *libmawk_initialize_stage1(void);

       mawk_state_t *libmawk_initialize_stage2(mawk_state_t * m,int s ,char*"argv[]);

       mawk_state_t *libmawk_initialize_stage3(mawk_state_t * m);

DESCRIPTION

       The  libmawk_initialize_stage*()  functions  together  do the same as libmawk_initialize() but allows the
       application to take actions between different stages.  libmawk_initialize_stage1() returns a pointer to a
       newly created libmawk context. Any amount of libmawk contexts can live in parallel in an application.

       libmawk_initialize_stage2() can be called after a succesful stage1 call.
        Stage2 is responsible for processing the command line arguments and loading any script.

       Arguments  are  the same as for a command line mawk session. Scripts are loaded (either from command line
       or from files using -f), variables are set (with -v), special options are set (with -W), etc. Unlike with
       libmawk_initialize(),  the  application  may  decide not to provide any script at this stage. All command
       line arguments are processed.

       The most common case is that the application calls stage1 with no script, then already having  a  context
       makes  some  manipulations  on it (for example registers some C functions that would be already called in
       the BEGIN part of the script that will be later loaded). Optionally before calling stage2 the application
       loads the actual script(s) using mawk_append_input_file().

       libmawk_initialize_stage3()  is  called as a final step of the three-stage initialization process. Stage3
       is responsible for running all the BEGIN parts of all scripts loaded at stage1 or stage2. It is useful to
       have  stage3 in a separate call to allow applications to manipulate the context right before initializing
       the scripts.

       Stage2 gets the pointer returned by stage1 and stage3 gets the pointer  returned  by  stage2.  Subsequent
       calls to libmawk functions should get the pointer returned by stage3.

RETURN VALUE

       At  stage  1  a pointer to a new libmawk context or NULL on error. Subsequent stages will return the same
       pointer or NULL on error.

SEE ALSO

       libmawk_initialize_stage(3libmawk), libmawk_uninitialize(3libmawk), mawk_append_input_file(3libmawk).