File: gawk.info,  Node: Symbol table by name,  Next: Symbol table by cookie,  Up: Symbol Table Access

17.4.11.1 Variable Access and Update by Name
............................................

The following routines provide the ability to access and update global
'awk'-level variables by name.  In compiler terminology, identifiers of
different kinds are termed "symbols", thus the "sym" in the routines'
names.  The data structure that stores information about symbols is
termed a "symbol table".  The functions are as follows:

'awk_bool_t sym_lookup(const char *name,'
'                      awk_valtype_t wanted,'
'                      awk_value_t *result);'
     Fill in the 'awk_value_t' structure pointed to by 'result' with the
     value of the variable named by the string 'name', which is a
     regular C string.  'wanted' indicates the type of value expected.
     Return true if the actual type matches 'wanted', and false
     otherwise.  In the latter case, 'result->val_type' indicates the
     actual type (*note Table 17.2: table-value-types-returned.).

'awk_bool_t sym_lookup_ns(const char *name,'
'                         const char *name_space,'
'                         awk_valtype_t wanted,'
'                         awk_value_t *result);'
     This is like 'sym_lookup()', but the 'name_space' parameter allows
     you to specify which namespace 'name' is part of.  'name_space'
     cannot be 'NULL'.  If it is '""' or '"awk"', then 'name' is
     searched for in the default 'awk' namespace.

     Note that 'namespace' is a C++ keyword.  For interoperability with
     C++, you should avoid using that identifier in C code.

'awk_bool_t sym_update(const char *name, awk_value_t *value);'
     Update the variable named by the string 'name', which is a regular
     C string.  The variable is added to 'gawk''s symbol table if it is
     not there.  Return true if everything worked, and false otherwise.

     Changing types (scalar to array or vice versa) of an existing
     variable is _not_ allowed, nor may this routine be used to update
     an array.  This routine cannot be used to update any of the
     predefined variables (such as 'ARGC' or 'NF').

'awk_bool_t sym_update_ns(const char *name_space, const char *name, awk_value_t *value);'
     This is like 'sym_update()', but the 'name_space' parameter allows
     you to specify which namespace 'name' is part of.  'name_space'
     cannot be 'NULL'.  If it is '""' or '"awk"', then 'name' is
     searched for in the default 'awk' namespace.

   An extension can look up the value of 'gawk''s special variables.
However, with the exception of the 'PROCINFO' array, an extension cannot
change any of those variables.

   When searching for or updating variables outside the 'awk' namespace
(*note Namespaces::), function and variable names must be simple
identifiers.(1)  In addition, namespace names and variable and function
names must follow the rules given in *note Naming Rules::.

   ---------- Footnotes ----------

   (1) Allowing both namespace plus identifier and 'foo::bar' would have
been too confusing to document, and to code and test.