.\" Copyright 2009 Tibor Palinkas (mawk@inno.bme.hu)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.TH LIBMAWK_REGISTER_FUNCTION 3libmawk  2009-08-12 "libmawk" "libmawk manual"
.SH NAME
libmawk_register_function \- registers a C function with a callback
.SH SYNOPSIS
.nf
.B #include <libmawk.h>
.sp
.BI "typedef CELL *libmawk_c_function(mawk_state_t *" m ", CELL *" sp ", int " a_args ");"
.fi
.BI "int libmawk_register_function(mawk_state_t *" MAWK ", const char *" fname ", libmawk_c_function *" callback ");"
.fi
.BI "CELL *libmawk_stackret(CELL *" original_sp ");"
.fi
.sp
.SH DESCRIPTION
The
.BR 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
.I fname
and should not match any of the user defined function names in the awk
script.
.sp
When the user function is called back, argument
.I sp
is the stack pointer and
.I a_args
holds the number of arguments. The user function is responsible for managing
the stack: it should pop all arguments before returning.
.sp
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
.I sp
after popping all arguments.
.sp
Argument m is a libmawk context previously returned by libmawk_initialize()
or libmawk_initialize_stage3().
.sp
For more information about user function callbacks, especially on stack handling,
see manual page example(3libmawk).
.SH "RETURN VALUE"
The user function should return the stack pointer after popping all arguments.
.sp
The libmawk_register_function call returns 0 on success.
.sp
Call libmawk_stackret returns a stack pointer to the slot where the user function should store its return value.

.SH "SEE ALSO"
.BR libmawk_initialize_stage (3libmawk),
.BR libmawk_initialize (3libmawk),
.BR libmawk_set_cell (3libmawk),
.BR libmawk_print_cell (3libmawk).