manpagez: man pages & more
info gawk
Home | html | info | man

gawk: Extension API Functions Introduction

 
 16.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':
 
      C entity                 Header file
      -------------------------------------------
      'EOF'                    '<stdio.h>'
      Values for 'errno'       '<errno.h>'
      'FILE'                   '<stdio.h>'
      'NULL'                   '<stddef.h>'
      'memcpy()'               '<string.h>'
      'memset()'               '<string.h>'
      'size_t'                 '<sys/types.h>'
      'struct stat'            '<sys/stat.h>'
 
      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 '<mpfr.h>' header before including '<gawkapi.h>'.
 
    * 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.
 
    * 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.
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.