NAME

       libmawk_register_function - registers a C function with a callback

SYNOPSIS

       #include <libmawk.h>

       typedef CELL *libmawk_c_function(mawk_state_t *m, CELL *sp, int a_args);
       int libmawk_register_function(mawk_state_t *MAWK, const char *fname, libmawk_c_function *callback);
       CELL *libmawk_stackret(CELL *original_sp);

DESCRIPTION

       The  libmawk_register_function()  call registers an user defined function donated by the host application
       in a mawk context so that it acts exactly like user defined functions in written in awk. The name of  the
       new  function  is  given  in fname and should not match any of the user defined function names in the awk
       script.

       When the user function is called back, argument sp is the stack pointer and a_args holds  the  number  of
       arguments.  The  user  function is responsible for managing the stack: it should pop all arguments before
       returning.

       The user function should also generate a return value, which is done by calling libmawk_set_cell() on the
       stack slot returned by libmawk_stackret.  Libmawk_stackret should be called with the  modified  sp  after
       popping all arguments.

       Argument    m    is    a    libmawk    context    previously    returned   by   libmawk_initialize()   or
       libmawk_initialize_stage3().

       For more information about user function  callbacks,  especially  on  stack  handling,  see  manual  page
       example(3libmawk).

RETURN VALUE

       The user function should return the stack pointer after popping all arguments.

       The libmawk_register_function call returns 0 on success.

       Call libmawk_stackret returns a stack pointer to the slot where the user function should store its return
       value.

SEE ALSO

       libmawk_initialize_stage(3libmawk),       libmawk_initialize(3libmawk),       libmawk_set_cell(3libmawk),
       libmawk_print_cell(3libmawk).

libmawk                                            2009-08-12                LIBMAWK_REGISTER_FUNCTION(3libmawk)