.\" 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_CALL_FUNCTION 3libmawk  2009-08-10 "libmawk" "libmawk manual"
.SH NAME
libmawk_call_function \- call an user defined (script) function
.SH SYNOPSIS
.nf
.B #include <libmawk.h>
.sp
.BI "int libmawk_call_function(mawk_state_t *" MAWK ", const char *" fname ", CELL *" res ", const char *" argtpes ", ...);"
.fi
.BI "int libmawk_call_functionp(mawk_state_t *" MAWK ", const char *" fname ", CELL *" res ", const char *" argtpes ", void **args);"
.fi
.sp
.SH DESCRIPTION
The
.BR libmawk_call_function ()
function looks up an user defined awk function called
.I fname
, fills the stack with arguments converted from the varargs and calls
the function.
The
.BR libmawk_call_functionp ()
performs the same action but avoids using vararg by requiring an array of
generic pointers to the function arguments.
.sp
Argtype is a zero terminated string for both functions, each character corresponding
to an argument. Type characters are described in libmawk_set_cell() manual page.
.sp
If res is non-NULL, it is cell_destroyed (regardless of errors) and the
return value of the user function is copied into it. The caller shall
run libmawk_cell_destroy on it.
.sp
Argument m is a libmawk context previously returned by libmawk_initialize()
or libmawk_initialize_stage3().

.SH "RETURN VALUE"
A pointer to the cell returned by the user function. The cell returned\
must be destroyed by the application using libmawk_cell_destroy.
.SH "SEE ALSO"
.BR libmawk_initialize_stage (3libmawk),
.BR libmawk_initialize (3libmawk),
.BR libmawk_cell_destroy (3libmawk),
.BR libmawk_set_cell (3libmawk),