File: gawk.info,  Node: Extension API Functions Introduction,  Next: General Data Types,  Up: Extension API Description

17.4.1 Introduction
-------------------

Access to facilities within 'gawk' is achieved by calling through
function pointers passed into your extension.

   API function pointers are provided for the following kinds of
operations:

   * Allocating, reallocating, and releasing memory.

   * Registration functions.  You may register:

        - Extension functions
        - Exit callbacks
        - A version string
        - Input parsers
        - Output wrappers
        - Two-way processors

     All of these are discussed in detail later in this major node.

   * Printing fatal, warning, and "lint" warning messages.

   * Updating 'ERRNO', or unsetting it.

   * Accessing parameters, including converting an undefined parameter
     into an array.

   * Symbol table access: retrieving a global variable, creating one, or
     changing one.

   * Creating and releasing cached values; this provides an efficient
     way to use values for multiple variables and can be a big
     performance win.

   * Manipulating arrays:

        - Retrieving, adding, deleting, and modifying elements

        - Getting the count of elements in an array

        - Creating a new array

        - Clearing an array

        - Flattening an array for easy C-style looping over all its
          indices and elements

   * Accessing and manipulating redirections.

   Some points about using the API:

   * The following types, macros, and/or functions are referenced in
     'gawkapi.h'.  For correct use, you must therefore include the
     corresponding standard header file _before_ including 'gawkapi.h'.
     The list of macros and related header files is shown in *note Table
     17.1: table-api-std-headers.


     C entity                 Header file
     -------------------------------------------
     'EOF'                    ''
     Values for 'errno'       ''
     'FILE'                   ''
     'NULL'                   ''
     'memcpy()'               ''
     'memset()'               ''
     'size_t'                 ''
     'struct stat'            ''

     Table 17.1: Standard header files needed by API

     Due to portability concerns, especially to systems that are not
     fully standards-compliant, it is your responsibility to include the
     correct files in the correct way.  This requirement is necessary in
     order to keep 'gawkapi.h' clean, instead of becoming a portability
     hodge-podge as can be seen in some parts of the 'gawk' source code.

   * If your extension uses MPFR facilities, and you wish to receive
     such values from 'gawk' and/or pass such values to it, you must
     include the '' header before including ''.

   * The 'gawkapi.h' file may be included more than once without ill
     effect.  Doing so, however, is poor coding practice.

   * Although the API only uses ISO C 90 features, there is an
     exception; the "constructor" functions use the 'inline' keyword.
     If your compiler does not support this keyword, you should either
     place '-Dinline=''' on your command line or use the GNU Autotools
     and include a 'config.h' file in your extensions.

   * All pointers filled in by 'gawk' point to memory managed by 'gawk'
     and should be treated by the extension as read-only.

     Memory for _all_ strings passed into 'gawk' from the extension
     _must_ come from calling one of 'gawk_malloc()', 'gawk_calloc()',
     or 'gawk_realloc()', and is managed by 'gawk' from then on.

     Memory for MPFR/GMP values that come from 'gawk' should also be
     treated as read-only.  However, unlike strings, memory for MPFR/GMP
     values allocated by an extension and passed into 'gawk' is _copied_
     by 'gawk'; the extension should then free the values itself to
     avoid memory leaks.  This is discussed further in *API Ownership of
     MPFR and GMP Values*.

   * The API defines several simple 'struct's that map values as seen
     from 'awk'.  A value can be a 'double', a string, or an array (as
     in multidimensional arrays, or when creating a new array).

     String values maintain both pointer and length, because embedded
     NUL characters are allowed.

          NOTE: By intent, 'gawk' maintains strings using the current
          multibyte encoding (as defined by 'LC_XXX' environment
          variables) and not using wide characters.  This matches how
          'gawk' stores strings internally and also how characters are
          likely to be input into and output from files.

          NOTE: String values passed to an extension by 'gawk' are
          always NUL-terminated.  Thus it is safe to pass such string
          values to standard library and system routines.  However,
          because 'gawk' allows embedded NUL characters in string data,
          before using the data as a regular C string, you should check
          that the length for that string passed to the extension
          matches the return value of 'strlen()' for it.

   * When retrieving a value (such as a parameter or that of a global
     variable or array element), the extension requests a specific type
     (number, string, scalar, value cookie, array, or "undefined").
     When the request is "undefined," the returned value will have the
     real underlying type.

     However, if the request and actual type don't match, the access
     function returns "false" and fills in the type of the actual value
     that is there, so that the extension can, e.g., print an error
     message (such as "scalar passed where array expected").

   You may call the API functions by using the function pointers
directly, but the interface is not so pretty.  To make extension code
look more like regular code, the 'gawkapi.h' header file defines several
macros that you should use in your code.  This minor node presents the
macros as if they were functions.