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).