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

gawk: Extension Versioning

 
 16.4.13.1 API Version Constants and Variables
 .............................................
 
 The API provides both a "major" and a "minor" version number.  The API
 versions are available at compile time as C preprocessor defines to
 support conditional compilation, and as enum constants to facilitate
 debugging:
 
 API Version   C Preprocessor Define      enum constant
 --------------------------------------------------------------------
 Major         'gawk_api_major_version'   'GAWK_API_MAJOR_VERSION'
 Minor         'gawk_api_minor_version'   'GAWK_API_MINOR_VERSION'
 
 Table 16.2: gawk API version constants
 
    The minor version increases when new functions are added to the API.
 Such new functions are always added to the end of the API 'struct'.
 
    The major version increases (and the minor version is reset to zero)
 if any of the data types change size or member order, or if any of the
 existing functions change signature.
 
    It could happen that an extension may be compiled against one version
 of the API but loaded by a version of 'gawk' using a different version.
 For this reason, the major and minor API versions of the running 'gawk'
 are included in the API 'struct' as read-only constant integers:
 
 'api->major_version'
      The major version of the running 'gawk'.
 
 'api->minor_version'
      The minor version of the running 'gawk'.
 
    It is up to the extension to decide if there are API
 incompatibilities.  Typically, a check like this is enough:
 
      if (api->major_version != GAWK_API_MAJOR_VERSION
          || api->minor_version < GAWK_API_MINOR_VERSION) {
              fprintf(stderr, "foo_extension: version mismatch with gawk!\n");
              fprintf(stderr, "\tmy version (%d, %d), gawk version (%d, %d)\n",
                      GAWK_API_MAJOR_VERSION, GAWK_API_MINOR_VERSION,
                      api->major_version, api->minor_version);
              exit(1);
      }
 
    Such code is included in the boilerplate 'dl_load_func()' macro
 provided in 'gawkapi.h' (discussed in ⇒Extension API
 Boilerplate).
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.