.\" Copyright 2009..2014 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_GET_VAR 3libmawk  2009-08-12 "libmawk" "libmawk manual"
.SH NAME
libmawk_get_var \- returns a pointer to a mawk variable
.SH SYNOPSIS
.nf
.B #include <libmawk.h>
.sp
.BI "const CELL *libmawk_get_var(mawk_state_t *" m ", const char *" vname ");"
.BI "int libmawk_get_array_at(mawk_state_t *" m ", const char *" arr_name ",
.BI "            const char *" idx ", const char *" res ", int " alloc ");"
.fi
.sp
.SH DESCRIPTION
The
.BR libmawk_get_var ()
function returns a pointer to a mawk cell that represents the global variable
with name passed in
.I vname
in the given context. The returned CELL should never be free'd or destroyed
or modified.
Function libmawk_print_cell may be used for converting the cell to string.
.sp
Function
.BR libmawk_get_array_at ()
performs the same operation for an element of an array. -1 is returned if
.I arr_name
is not an array or upon an error. If
.I idx
is not an existing index in the array it is allocated if
.I alloc
is non-zero. If
.I res
is not NULL, it is destroyed (regardless of the return value) and if
the index exists (or is created by the call), is loaded with the value.
The caller needs to destroy
.I res
after use. Since
.I res
is destroyed when non-NULL, it must be a valid cell with valid type.
.sp
Argument m is a libmawk context previously returned by libmawk_initialize()
or libmawk_initialize_stage3().

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