17.4.10.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 (see Table 17.2).

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 (see section Namespaces in gawk), function and variable names must be simple identifiers.¹⁰⁶ In addition, namespace names and variable and function names must follow the rules given in Namespace and Component Naming Rules.