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