gawk: Memory Allocation Functions

1 
1 16.4.3 Memory Allocation Functions and Convenience Macros
1 ---------------------------------------------------------
1 
1 The API provides a number of "memory allocation" functions for
1 allocating memory that can be passed to 'gawk', as well as a number of
1 convenience macros.  This node presents them all as function prototypes,
1 in the way that extension code would use them:
1 
1 'void *gawk_malloc(size_t size);'
1      Call the correct version of 'malloc()' to allocate storage that may
1      be passed to 'gawk'.
1 
1 'void *gawk_calloc(size_t nmemb, size_t size);'
1      Call the correct version of 'calloc()' to allocate storage that may
1      be passed to 'gawk'.
1 
1 'void *gawk_realloc(void *ptr, size_t size);'
1      Call the correct version of 'realloc()' to allocate storage that
1      may be passed to 'gawk'.
1 
1 'void gawk_free(void *ptr);'
1      Call the correct version of 'free()' to release storage that was
1      allocated with 'gawk_malloc()', 'gawk_calloc()', or
1      'gawk_realloc()'.
1 
1    The API has to provide these functions because it is possible for an
1 extension to be compiled and linked against a different version of the C
1 library than was used for the 'gawk' executable.(1)  If 'gawk' were to
1 use its version of 'free()' when the memory came from an unrelated
1 version of 'malloc()', unexpected behavior would likely result.
1 
1    Three convenience macros may be used for allocating storage from
1 'gawk_malloc()', 'gawk_calloc', and 'gawk_realloc()'.  If the allocation
1 fails, they cause 'gawk' to exit with a fatal error message.  They
1 should be used as if they were procedure calls that do not return a
1 value:
1 
1 '#define emalloc(pointer, type, size, message) ...'
1      The arguments to this macro are as follows:
1 
1      'pointer'
1           The pointer variable to point at the allocated storage.
1 
1      'type'
1           The type of the pointer variable.  This is used to create a
1           cast for the call to 'gawk_malloc()'.
1 
1      'size'
1           The total number of bytes to be allocated.
1 
1      'message'
1           A message to be prefixed to the fatal error message.
1           Typically this is the name of the function using the macro.
1 
1      For example, you might allocate a string value like so:
1 
1           awk_value_t result;
1           char *message;
1           const char greet[] = "Don't Panic!";
1 
1           emalloc(message, char *, sizeof(greet), "myfunc");
1           strcpy(message, greet);
1           make_malloced_string(message, strlen(message), & result);
1 
1 
1 
1 '#define ezalloc(pointer, type, size, message) ...'
1      This is like 'emalloc()', but it calls 'gawk_calloc()' instead of
1      'gawk_malloc()'.  The arguments are the same as for the 'emalloc()'
1      macro, but this macro guarantees that the memory returned is
1      initialized to zero.
1 
1 '#define erealloc(pointer, type, size, message) ...'
1      This is like 'emalloc()', but it calls 'gawk_realloc()' instead of
1      'gawk_malloc()'.  The arguments are the same as for the 'emalloc()'
1      macro.
1 
1    Two additional functions allocate MPFR and GMP objects for use by
1 extension functions that need to create and then return such values:
1 
1 'void *get_mpfr_ptr();'
1      Allocate and initialize an MPFR object and return a pointer to it.
1      If the allocation fails, 'gawk' exits with a fatal "out of memory"
1      error.  If 'gawk' was compiled without MPFR support, calling this
1      function causes a fatal error.
1 
1 'void *get_mpz_ptr();'
1      Allocate and initialize a GMP object and return a pointer to it.
1      If the allocation fails, 'gawk' exits with a fatal "out of memory"
1      error.  If 'gawk' was compiled without MPFR support, calling this
1      function causes a fatal error.
1 
1    Both of these functions return 'void *', since the 'gawkapi.h' header
1 file should not have dependency upon '<mpfr.h>' (and '<gmp.h>', which is
1 included from '<mpfr.h>').  The actual return values are of types
1 'mpfr_ptr' and 'mpz_ptr' respectively, and you should cast the return
1 values appropriately before assigning the results to variables of the
1 correct types.
1 
1    ---------- Footnotes ----------
1 
1    (1) This is more common on MS-Windows systems, but it can happen on
1 Unix-like systems as well.
1