16.4.5.1 Registering An Extension Function

Extension functions are described by the following record:

typedef struct awk_ext_func {
    const char *name;
    awk_value_t *(*function)(int num_actual_args, awk_value_t *result);
    size_t num_expected_args;
} awk_ext_func_t;

The fields are:

const char *name;

The name of the new function. awk-level code calls the function by this name. This is a regular C string.

Function names must obey the rules for awk identifiers. That is, they must begin with either an English letter or an underscore, which may be followed by any number of letters, digits, and underscores. Letter case in function names is significant.

awk_value_t *(*function)(int num_actual_args, awk_value_t *result);

This is a pointer to the C function that provides the extension’s functionality. The function must fill in *result with either a number or a string. gawk takes ownership of any string memory. As mentioned earlier, string memory must come from one of gawk_malloc(), gawk_calloc(), or gawk_realloc().

The num_actual_args argument tells the C function how many actual parameters were passed from the calling awk code.

The function must return the value of result. This is for the convenience of the calling code inside gawk.

size_t num_expected_args;

This is the number of arguments the function expects to receive. Each extension function may decide what to do if the number of arguments isn’t what it expected. As with real awk functions, it is likely OK to ignore extra arguments.

Once you have a record representing your extension function, you register it with gawk using this API function:

awk_bool_t add_ext_func(const char *namespace, const awk_ext_func_t *func);

This function returns true upon success, false otherwise. The namespace parameter is currently not used; you should pass in an empty string (""). The func pointer is the address of a struct representing your function, as just described.