Add memory allocation functions to gawk API.

1 files changed, 65 insertions, 40 deletions

diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index dd3d1409..3720a0dc 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -737,6 +737,7 @@ particular records in a file and perform operations upon them.
 * Extension API Functions Introduction:: Introduction to the API functions.
 * General Data Types::                  The data types.
 * Requesting Values::                   How to get a value.
+* Memory Allocation Functions::         Functions for allocating memory.
 * Constructor Functions::               Functions for creating values.
 * Registration Functions::              Functions to register things with
                                         @command{gawk}.
@@ -28716,6 +28717,7 @@ This (rather large) @value{SECTION} describes the API in detail.
 * Extension API Functions Introduction:: Introduction to the API functions.
 * General Data Types::                   The data types.
 * Requesting Values::                    How to get a value.
+* Memory Allocation Functions::          Functions for allocating memory.
 * Constructor Functions::                Functions for creating values.
 * Registration Functions::               Functions to register things with
                                          @command{gawk}.
@@ -28809,10 +28811,8 @@ corresponding standard header file @emph{before} including @file{gawkapi.h}:
 @item @code{EOF} @tab @code{<stdio.h>}
 @item @code{FILE} @tab @code{<stdio.h>}
 @item @code{NULL} @tab @code{<stddef.h>}
-@item @code{malloc()} @tab @code{<stdlib.h>}
 @item @code{memcpy()} @tab @code{<string.h>}
 @item @code{memset()} @tab @code{<string.h>}
-@item @code{realloc()} @tab @code{<stdlib.h>}
 @item @code{size_t} @tab @code{<sys/types.h>}
 @item @code{struct stat} @tab @code{<sys/stat.h>}
 @end multitable 
@@ -28842,7 +28842,7 @@ does not support this keyword, you should either place
 All pointers filled in by @command{gawk} are to memory
 managed by @command{gawk} and should be treated by the extension as
 read-only.  Memory for @emph{all} strings passed into @command{gawk}
-from the extension @emph{must} come from @code{malloc()} and is managed
+from the extension @emph{must} come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and is managed
 by @command{gawk} from then on.
 
 @item
@@ -28925,7 +28925,7 @@ A simple boolean type.
 This represents a mutable string. @command{gawk}
 owns the memory pointed to if it supplied
 the value. Otherwise, it takes ownership of the memory pointed to.
-@strong{Such memory must come from @code{malloc()}!}
+@strong{Such memory must come from calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!}
 
 As mentioned earlier, strings are maintained using the current
 multibyte encoding.
@@ -29087,44 +29087,33 @@ value type, as appropriate.  This behavior is summarized in
 @end float
 @end ifplaintext
 
-@node Constructor Functions
-@subsection Constructor Functions and Convenience Macros
+@node Memory Allocation Functions
+@subsection Memory Allocation Functions and Convenience Macros
 
-The API provides a number of @dfn{constructor} functions for creating
-string and numeric values, as well as a number of convenience macros.
-This @value{SUBSECTION} presents them all as function prototypes, in
-the way that extension code would use them.
+The API provides a number of @dfn{memory allocation} functions for
+allocating memory that can be passed to gawk, as well as a number of convenience macros.
 
 @table @code
-@item static inline awk_value_t *
-@itemx make_const_string(const char *string, size_t length, awk_value_t *result)
-This function creates a string value in the @code{awk_value_t} variable
-pointed to by @code{result}. It expects @code{string} to be a C string constant
-(or other string data), and automatically creates a @emph{copy} of the data
-for storage in @code{result}. It returns @code{result}.
+@item void *gawk_malloc(size_t size);
+Call @command{gawk}-provided @code{api_malloc()} to allocate storage that may
+be passed to @command{gawk}.
 
-@item static inline awk_value_t *
-@itemx make_malloced_string(const char *string, size_t length, awk_value_t *result)
-This function creates a string value in the @code{awk_value_t} variable
-pointed to by @code{result}. It expects @code{string} to be a @samp{char *}
-value pointing to data previously obtained from @code{malloc()}. The idea here
-is that the data is passed directly to @command{gawk}, which assumes
-responsibility for it. It returns @code{result}.
+@item void *gawk_calloc(size_t nmemb, size_t size);
+Call @command{gawk}-provided @code{api_calloc()} to allocate storage that may
+be passed to @command{gawk}.
 
-@item static inline awk_value_t *
-@itemx make_null_string(awk_value_t *result)
-This specialized function creates a null string (the ``undefined'' value)
-in the @code{awk_value_t} variable pointed to by @code{result}.
-It returns @code{result}.
+@item void *gawk_realloc(void *ptr, size_t size);
+Call @command{gawk}-provided @code{api_realloc()} to allocate storage that may
+be passed to @command{gawk}.
 
-@item static inline awk_value_t *
-@itemx make_number(double num, awk_value_t *result)
-This function simply creates a numeric value in the @code{awk_value_t} variable
-pointed to by @code{result}.
+@item void gawk_free(void *ptr);
+Call @command{gawk}-provided @code{api_free()} to release storage that was
+allocated with @code{gawk_malloc()}, @code{gawk_calloc()} or @code{gawk_realloc()}.
 @end table
 
-Two convenience macros may be used for allocating storage from @code{malloc()}
-and @code{realloc()}. If the allocation fails, they cause @command{gawk} to
+
+Two convenience macros may be used for allocating storage from the api-provided function pointers @code{api_malloc()}
+and @code{api_realloc()}. If the allocation fails, they cause @command{gawk} to
 exit with a fatal error message.  They should be used as if they were
 procedure calls that do not return a value.
 
@@ -29137,7 +29126,7 @@ The arguments to this macro are as follows:
 The pointer variable to point at the allocated storage.
 
 @item type
-The type of the pointer variable, used to create a cast for the call to @code{malloc()}.
+The type of the pointer variable, used to create a cast for the call to @code{api_malloc()}.
 
 @item size
 The total number of bytes to be allocated.
@@ -29161,11 +29150,47 @@ make_malloced_string(message, strlen(message), & result);
 @end example
 
 @item #define erealloc(pointer, type, size, message) @dots{}
-This is like @code{emalloc()}, but it calls @code{realloc()},
-instead of @code{malloc()}.
+This is like @code{emalloc()}, but it calls @code{api_realloc()},
+instead of @code{api_malloc()}.
 The arguments are the same as for the @code{emalloc()} macro.
 @end table
 
+@node Constructor Functions
+@subsection Constructor Functions
+
+The API provides a number of @dfn{constructor} functions for creating
+string and numeric values, as well as a number of convenience macros.
+This @value{SUBSECTION} presents them all as function prototypes, in
+the way that extension code would use them.
+
+@table @code
+@item static inline awk_value_t *
+@itemx make_const_string(const char *string, size_t length, awk_value_t *result)
+This function creates a string value in the @code{awk_value_t} variable
+pointed to by @code{result}. It expects @code{string} to be a C string constant
+(or other string data), and automatically creates a @emph{copy} of the data
+for storage in @code{result}. It returns @code{result}.
+
+@item static inline awk_value_t *
+@itemx make_malloced_string(const char *string, size_t length, awk_value_t *result)
+This function creates a string value in the @code{awk_value_t} variable
+pointed to by @code{result}. It expects @code{string} to be a @samp{char *}
+value pointing to data previously obtained from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}. The idea here
+is that the data is passed directly to @command{gawk}, which assumes
+responsibility for it. It returns @code{result}.
+
+@item static inline awk_value_t *
+@itemx make_null_string(awk_value_t *result)
+This specialized function creates a null string (the ``undefined'' value)
+in the @code{awk_value_t} variable pointed to by @code{result}.
+It returns @code{result}.
+
+@item static inline awk_value_t *
+@itemx make_number(double num, awk_value_t *result)
+This function simply creates a numeric value in the @code{awk_value_t} variable
+pointed to by @code{result}.
+@end table
+
 @node Registration Functions
 @subsection Registration Functions
 
@@ -29213,7 +29238,7 @@ This is a pointer to the C function that provides the desired
 functionality.
 The function must fill in the result with either a number
 or a string. @command{gawk} takes ownership of any string memory.
-As mentioned earlier, string memory @strong{must} come from @code{malloc()}.
+As mentioned earlier, string memory @strong{must} come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}.
 
 The @code{num_actual_args} argument tells the C function how many
 actual parameters were passed from the calling @command{awk} code.
@@ -29951,7 +29976,7 @@ assign those values to variables using @code{sym_update()}
 or @code{sym_update_scalar()}, as you like.
 
 However, you can understand the point of cached values if you remember that
-@emph{every} string value's storage @emph{must} come from @code{malloc()}.
+@emph{every} string value's storage @emph{must} come from @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()}.
 If you have 20 variables, all of which have the same string value, you
 must create 20 identical copies of the string.@footnote{Numeric values
 are clearly less problematic, requiring only a C @code{double} to store.}
@@ -30148,7 +30173,7 @@ requires that you understand how such values are converted to strings
 (@pxref{Conversion}); thus using integral values is safest.
 
 As with @emph{all} strings passed into @code{gawk} from an extension,
-the string value of @code{index} must come from @code{malloc()}, and
+the string value of @code{index} must come from the api-provided functions @code{api_malloc()}, @code{api_calloc()} or @code{api_realloc()} and
 @command{gawk} releases the storage.
 
 @item awk_bool_t set_array_element(awk_array_t a_cookie,