summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndrew J. Schorr <aschorr@telemetry-investments.com>2014-03-08 14:41:00 -0500
committerAndrew J. Schorr <aschorr@telemetry-investments.com>2014-03-08 14:41:00 -0500
commitb4343b17479151d438d32530cdd2541262e3088e (patch)
tree59c81427d817fa5c704336313999e4428ec616c1
parent4c0b1ddb06fd9329fd34db65a93e067d6426a7d1 (diff)
downloadgawk-b4343b17479151d438d32530cdd2541262e3088e.tar.gz
Add memory allocation functions to gawk API.
Diffstat
-rw-r--r--ChangeLog10
-rw-r--r--doc/ChangeLog5
-rw-r--r--doc/gawk.info1224
-rw-r--r--doc/gawk.texi105
-rw-r--r--doc/gawktexi.in105
-rw-r--r--extension/ChangeLog11
-rw-r--r--extension/filefuncs.c6
-rw-r--r--extension/inplace.c6
-rw-r--r--extension/readdir.c4
-rw-r--r--extension/readfile.c2
-rw-r--r--extension/revtwoway.c4
-rw-r--r--extension/rwarray.c6
-rw-r--r--extension/testext.c4
-rw-r--r--gawkapi.c6
-rw-r--r--gawkapi.h24
15 files changed, 828 insertions, 694 deletions
diff --git a/ChangeLog b/ChangeLog
index 887d026c..31d1d616 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2014-03-08 Andrew J. Schorr <aschorr@telemetry-investments.com>
+
+ * gawkapi.c (api_impl): Add memory allocation function pointers.
+ * gawkapi.h (GAWK_API_MINOR_VERSION): Bump.
+ (gawk_api_t): Add memory allocation function pointers api_malloc,
+ api_calloc, api_realloc, and api_free.
+ (gawk_malloc, gawk_calloc, gawk_realloc, gawk_free): New macros.
+ (emalloc): Replace malloc with gawk_malloc.
+ (erealloc): Replace erealloc with gawk_erealloc.
+
2014-03-05 Arnold D. Robbins <arnold@skeeve.com>
Straighten out enumerated types some more.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index cf61ad19..085ba317 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2014-03-08 Andrew J. Schorr <aschorr@telemetry-investments.com>
+
+ * gawktexi.in: Document new extension API functions api_malloc,
+ api_calloc, api_realloc, and api_free.
+
2014-03-07 Arnold D. Robbins <arnold@skeeve.com>
* gawktexi.in: Indexing improvements.
diff --git a/doc/gawk.info b/doc/gawk.info
index 6fb7ee3e..799d1c11 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -522,6 +522,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b)
* 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
`gawk'.
@@ -21733,6 +21734,7 @@ This (rather large) minor node 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
`gawk'.
@@ -21809,10 +21811,8 @@ operations:
`EOF' `<stdio.h>'
`FILE' `<stdio.h>'
`NULL' `<stddef.h>'
- `malloc()' `<stdlib.h>'
`memcpy()' `<string.h>'
`memset()' `<string.h>'
- `realloc()' `<stdlib.h>'
`size_t' `<sys/types.h>'
`struct stat' `<sys/stat.h>'
@@ -21838,7 +21838,9 @@ operations:
* All pointers filled in by `gawk' are 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 `malloc()' and is managed by `gawk' from then on.
+ from calling the api-provided function pointers `api_malloc()',
+ `api_calloc()' or `api_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
@@ -21910,7 +21912,9 @@ that use them.
`} awk_string_t;'
This represents a mutable string. `gawk' owns the memory pointed
to if it supplied the value. Otherwise, it takes ownership of the
- memory pointed to. *Such memory must come from `malloc()'!*
+ memory pointed to. *Such memory must come from calling the
+ api-provided function pointers `api_malloc()', `api_calloc()', or
+ `api_realloc()'!*
As mentioned earlier, strings are maintained using the current
multibyte encoding.
@@ -22015,7 +22019,7 @@ the value.
See also the entry for "Cookie" in the *note Glossary::.

-File: gawk.info, Node: Requesting Values, Next: Constructor Functions, Prev: General Data Types, Up: Extension API Description
+File: gawk.info, Node: Requesting Values, Next: Memory Allocation Functions, Prev: General Data Types, Up: Extension API Description
16.4.3 Requesting Values
------------------------
@@ -22048,46 +22052,37 @@ Requested: Scalar Scalar Scalar false false
Table 16.1: Value Types Returned

-File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Requesting Values, Up: Extension API Description
+File: gawk.info, Node: Memory Allocation Functions, Next: Constructor Functions, Prev: Requesting Values, Up: Extension API Description
-16.4.4 Constructor Functions and Convenience Macros
----------------------------------------------------
+16.4.4 Memory Allocation Functions and Convenience Macros
+---------------------------------------------------------
-The API provides a number of "constructor" functions for creating
-string and numeric values, as well as a number of convenience macros.
-This node presents them all as function prototypes, in the way that
-extension code would use them.
+The API provides a number of "memory allocation" functions for
+allocating memory that can be passed to gawk, as well as a number of
+convenience macros.
-`static inline awk_value_t *'
-`make_const_string(const char *string, size_t length, awk_value_t *result)'
- This function creates a string value in the `awk_value_t' variable
- pointed to by `result'. It expects `string' to be a C string
- constant (or other string data), and automatically creates a
- _copy_ of the data for storage in `result'. It returns `result'.
+`void *gawk_malloc(size_t size);'
+ Call `gawk'-provided `api_malloc()' to allocate storage that may
+ be passed to `gawk'.
-`static inline awk_value_t *'
-`make_malloced_string(const char *string, size_t length, awk_value_t *result)'
- This function creates a string value in the `awk_value_t' variable
- pointed to by `result'. It expects `string' to be a `char *' value
- pointing to data previously obtained from `malloc()'. The idea here
- is that the data is passed directly to `gawk', which assumes
- responsibility for it. It returns `result'.
+`void *gawk_calloc(size_t nmemb, size_t size);'
+ Call `gawk'-provided `api_calloc()' to allocate storage that may
+ be passed to `gawk'.
-`static inline awk_value_t *'
-`make_null_string(awk_value_t *result)'
- This specialized function creates a null string (the "undefined"
- value) in the `awk_value_t' variable pointed to by `result'. It
- returns `result'.
+`void *gawk_realloc(void *ptr, size_t size);'
+ Call `gawk'-provided `api_realloc()' to allocate storage that may
+ be passed to `gawk'.
-`static inline awk_value_t *'
-`make_number(double num, awk_value_t *result)'
- This function simply creates a numeric value in the `awk_value_t'
- variable pointed to by `result'.
+`void gawk_free(void *ptr);'
+ Call `gawk'-provided `api_free()' to release storage that was
+ allocated with `gawk_malloc()', `gawk_calloc()' or
+ `gawk_realloc()'.
- Two convenience macros may be used for allocating storage from
-`malloc()' and `realloc()'. If the allocation fails, they cause `gawk'
-to exit with a fatal error message. They should be used as if they were
-procedure calls that do not return a value.
+ Two convenience macros may be used for allocating storage from the
+api-provided function pointers `api_malloc()' and `api_realloc()'. If
+the allocation fails, they cause `gawk' to exit with a fatal error
+message. They should be used as if they were procedure calls that do
+not return a value.
`#define emalloc(pointer, type, size, message) ...'
The arguments to this macro are as follows:
@@ -22096,7 +22091,7 @@ procedure calls that do not return a value.
`type'
The type of the pointer variable, used to create a cast for
- the call to `malloc()'.
+ the call to `api_malloc()'.
`size'
The total number of bytes to be allocated.
@@ -22116,14 +22111,52 @@ procedure calls that do not return a value.
make_malloced_string(message, strlen(message), & result);
`#define erealloc(pointer, type, size, message) ...'
- This is like `emalloc()', but it calls `realloc()', instead of
- `malloc()'. The arguments are the same as for the `emalloc()'
+ This is like `emalloc()', but it calls `api_realloc()', instead of
+ `api_malloc()'. The arguments are the same as for the `emalloc()'
macro.

+File: gawk.info, Node: Constructor Functions, Next: Registration Functions, Prev: Memory Allocation Functions, Up: Extension API Description
+
+16.4.5 Constructor Functions
+----------------------------
+
+The API provides a number of "constructor" functions for creating
+string and numeric values, as well as a number of convenience macros.
+This node presents them all as function prototypes, in the way that
+extension code would use them.
+
+`static inline awk_value_t *'
+`make_const_string(const char *string, size_t length, awk_value_t *result)'
+ This function creates a string value in the `awk_value_t' variable
+ pointed to by `result'. It expects `string' to be a C string
+ constant (or other string data), and automatically creates a
+ _copy_ of the data for storage in `result'. It returns `result'.
+
+`static inline awk_value_t *'
+`make_malloced_string(const char *string, size_t length, awk_value_t *result)'
+ This function creates a string value in the `awk_value_t' variable
+ pointed to by `result'. It expects `string' to be a `char *' value
+ pointing to data previously obtained from the api-provided
+ functions `api_malloc()', `api_calloc()' or `api_realloc()'. The
+ idea here is that the data is passed directly to `gawk', which
+ assumes responsibility for it. It returns `result'.
+
+`static inline awk_value_t *'
+`make_null_string(awk_value_t *result)'
+ This specialized function creates a null string (the "undefined"
+ value) in the `awk_value_t' variable pointed to by `result'. It
+ returns `result'.
+
+`static inline awk_value_t *'
+`make_number(double num, awk_value_t *result)'
+ This function simply creates a numeric value in the `awk_value_t'
+ variable pointed to by `result'.
+
+
File: gawk.info, Node: Registration Functions, Next: Printing Messages, Prev: Constructor Functions, Up: Extension API Description
-16.4.5 Registration Functions
+16.4.6 Registration Functions
-----------------------------
This minor node describes the API functions for registering parts of
@@ -22141,7 +22174,7 @@ your extension with `gawk'.

File: gawk.info, Node: Extension Functions, Next: Exit Callback Functions, Up: Registration Functions
-16.4.5.1 Registering An Extension Function
+16.4.6.1 Registering An Extension Function
..........................................
Extension functions are described by the following record:
@@ -22167,7 +22200,9 @@ Extension functions are described by the following record:
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. `gawk' takes ownership of any string memory.
- As mentioned earlier, string memory *must* come from `malloc()'.
+ As mentioned earlier, string memory *must* come from the
+ api-provided functions `api_malloc()', `api_calloc()' or
+ `api_realloc()'.
The `num_actual_args' argument tells the C function how many
actual parameters were passed from the calling `awk' code.
@@ -22193,7 +22228,7 @@ register it with `gawk' using this API function:

File: gawk.info, Node: Exit Callback Functions, Next: Extension Version String, Prev: Extension Functions, Up: Registration Functions
-16.4.5.2 Registering An Exit Callback Function
+16.4.6.2 Registering An Exit Callback Function
..............................................
An "exit callback" function is a function that `gawk' calls before it
@@ -22222,7 +22257,7 @@ order--that is, in the reverse order in which they are registered with

File: gawk.info, Node: Extension Version String, Next: Input Parsers, Prev: Exit Callback Functions, Up: Registration Functions
-16.4.5.3 Registering An Extension Version String
+16.4.6.3 Registering An Extension Version String
................................................
You can register a version string which indicates the name and version
@@ -22238,7 +22273,7 @@ invoked with the `--version' option.

File: gawk.info, Node: Input Parsers, Next: Output Wrappers, Prev: Extension Version String, Up: Registration Functions
-16.4.5.4 Customized Input Parsers
+16.4.6.4 Customized Input Parsers
.................................
By default, `gawk' reads text files as its input. It uses the value of
@@ -22460,7 +22495,7 @@ whether or not to activate an input parser (*note BEGINFILE/ENDFILE::).

File: gawk.info, Node: Output Wrappers, Next: Two-way processors, Prev: Input Parsers, Up: Registration Functions
-16.4.5.5 Customized Output Wrappers
+16.4.6.5 Customized Output Wrappers
...................................
An "output wrapper" is the mirror image of an input parser. It allows
@@ -22567,7 +22602,7 @@ normally.

File: gawk.info, Node: Two-way processors, Prev: Output Wrappers, Up: Registration Functions
-16.4.5.6 Customized Two-way Processors
+16.4.6.6 Customized Two-way Processors
......................................
A "two-way processor" combines an input parser and an output wrapper for
@@ -22620,7 +22655,7 @@ can take this" and "take over for this" functions,

File: gawk.info, Node: Printing Messages, Next: Updating `ERRNO', Prev: Registration Functions, Up: Extension API Description
-16.4.6 Printing Messages
+16.4.7 Printing Messages
------------------------
You can print different kinds of warning messages from your extension,
@@ -22651,7 +22686,7 @@ the pity.

File: gawk.info, Node: Updating `ERRNO', Next: Accessing Parameters, Prev: Printing Messages, Up: Extension API Description
-16.4.7 Updating `ERRNO'
+16.4.8 Updating `ERRNO'
-----------------------
The following functions allow you to update the `ERRNO' variable:
@@ -22672,7 +22707,7 @@ The following functions allow you to update the `ERRNO' variable:

File: gawk.info, Node: Accessing Parameters, Next: Symbol Table Access, Prev: Updating `ERRNO', Up: Extension API Description
-16.4.8 Accessing and Updating Parameters
+16.4.9 Accessing and Updating Parameters
----------------------------------------
Two functions give you access to the arguments (parameters) passed to
@@ -22698,8 +22733,8 @@ your extension function. They are:

File: gawk.info, Node: Symbol Table Access, Next: Array Manipulation, Prev: Accessing Parameters, Up: Extension API Description
-16.4.9 Symbol Table Access
---------------------------
+16.4.10 Symbol Table Access
+---------------------------
Two sets of routines provide access to global variables, and one set
allows you to create and release cached values.
@@ -22713,8 +22748,8 @@ allows you to create and release cached values.

File: gawk.info, Node: Symbol table by name, Next: Symbol table by cookie, Up: Symbol Table Access
-16.4.9.1 Variable Access and Update by Name
-...........................................
+16.4.10.1 Variable Access and Update by Name
+............................................
The following routines provide the ability to access and update global
`awk'-level variables by name. In compiler terminology, identifiers of
@@ -22749,8 +22784,8 @@ cannot change any of those variables.

File: gawk.info, Node: Symbol table by cookie, Next: Cached values, Prev: Symbol table by name, Up: Symbol Table Access
-16.4.9.2 Variable Access and Update by Cookie
-.............................................
+16.4.10.2 Variable Access and Update by Cookie
+..............................................
A "scalar cookie" is an opaque handle that provides access to a global
variable or array. It is an optimization that avoids looking up
@@ -22862,8 +22897,8 @@ like this:

File: gawk.info, Node: Cached values, Prev: Symbol table by cookie, Up: Symbol Table Access
-16.4.9.3 Creating and Using Cached Values
-.........................................
+16.4.10.3 Creating and Using Cached Values
+..........................................
The routines in this section allow you to create and release cached
values. As with scalar cookies, in theory, cached values are not
@@ -22873,8 +22908,9 @@ variables using `sym_update()' or `sym_update_scalar()', as you like.
However, you can understand the point of cached values if you
remember that _every_ string value's storage _must_ come from
-`malloc()'. If you have 20 variables, all of which have the same
-string value, you must create 20 identical copies of the string.(1)
+`api_malloc()', `api_calloc()' or `api_realloc()'. If you have 20
+variables, all of which have the same string value, you must create 20
+identical copies of the string.(1)
It is clearly more efficient, if possible, to create a value once,
and then tell `gawk' to reuse the value for multiple variables. That is
@@ -22957,7 +22993,7 @@ using `release_value()'.

File: gawk.info, Node: Array Manipulation, Next: Extension API Variables, Prev: Symbol Table Access, Up: Extension API Description
-16.4.10 Array Manipulation
+16.4.11 Array Manipulation
--------------------------
The primary data structure(1) in `awk' is the associative array (*note
@@ -22984,7 +23020,7 @@ arrays of arrays (*note General Data Types::).

File: gawk.info, Node: Array Data Types, Next: Array Functions, Up: Array Manipulation
-16.4.10.1 Array Data Types
+16.4.11.1 Array Data Types
..........................
The data types associated with arrays are listed below.
@@ -23051,7 +23087,7 @@ overuse this term.

File: gawk.info, Node: Array Functions, Next: Flattening Arrays, Prev: Array Data Types, Up: Array Manipulation
-16.4.10.2 Array Functions
+16.4.11.2 Array Functions
.........................
The following functions relate to individual array elements.
@@ -23077,7 +23113,8 @@ The following functions relate to individual array elements.
strings (*note Conversion::); thus using integral values is safest.
As with _all_ strings passed into `gawk' from an extension, the
- string value of `index' must come from `malloc()', and `gawk'
+ string value of `index' must come from the api-provided functions
+ `api_malloc()', `api_calloc()' or `api_realloc()' and `gawk'
releases the storage.
`awk_bool_t set_array_element(awk_array_t a_cookie,'
@@ -23128,7 +23165,7 @@ The following functions relate to individual array elements.

File: gawk.info, Node: Flattening Arrays, Next: Creating Arrays, Prev: Array Functions, Up: Array Manipulation
-16.4.10.3 Working With All The Elements of an Array
+16.4.11.3 Working With All The Elements of an Array
...................................................
To "flatten" an array is create a structure that represents the full
@@ -23302,7 +23339,7 @@ return value to success, and returns:

File: gawk.info, Node: Creating Arrays, Prev: Flattening Arrays, Up: Array Manipulation
-16.4.10.4 How To Create and Populate Arrays
+16.4.11.4 How To Create and Populate Arrays
...........................................
Besides working with arrays created by `awk' code, you can create
@@ -23441,7 +23478,7 @@ environment variable.)

File: gawk.info, Node: Extension API Variables, Next: Extension API Boilerplate, Prev: Array Manipulation, Up: Extension API Description
-16.4.11 API Variables
+16.4.12 API Variables
---------------------
The API provides two sets of variables. The first provides information
@@ -23458,7 +23495,7 @@ information about how `gawk' was invoked.

File: gawk.info, Node: Extension Versioning, Next: Extension API Informational Variables, Up: Extension API Variables
-16.4.11.1 API Version Constants and Variables
+16.4.12.1 API Version Constants and Variables
.............................................
The API provides both a "major" and a "minor" version number. The API
@@ -23507,7 +23544,7 @@ Boilerplate::).

File: gawk.info, Node: Extension API Informational Variables, Prev: Extension Versioning, Up: Extension API Variables
-16.4.11.2 Informational Variables
+16.4.12.2 Informational Variables
.................................
The API provides access to several variables that describe whether the
@@ -23543,7 +23580,7 @@ change during execution.

File: gawk.info, Node: Extension API Boilerplate, Prev: Extension API Variables, Up: Extension API Description
-16.4.12 Boilerplate Code
+16.4.13 Boilerplate Code
------------------------
As mentioned earlier (*note Extension Mechanism Outline::), the function
@@ -32792,526 +32829,527 @@ Index

Tag Table:
Node: Top1366
-Node: Foreword40856
-Node: Preface45201
-Ref: Preface-Footnote-148254
-Ref: Preface-Footnote-248350
-Node: History48582
-Node: Names50956
-Ref: Names-Footnote-152433
-Node: This Manual52505
-Ref: This Manual-Footnote-158279
-Node: Conventions58379
-Node: Manual History60535
-Ref: Manual History-Footnote-163983
-Ref: Manual History-Footnote-264024
-Node: How To Contribute64098
-Node: Acknowledgments65242
-Node: Getting Started69436
-Node: Running gawk71815
-Node: One-shot73001
-Node: Read Terminal74226
-Ref: Read Terminal-Footnote-175876
-Ref: Read Terminal-Footnote-276152
-Node: Long76323
-Node: Executable Scripts77699
-Ref: Executable Scripts-Footnote-179532
-Ref: Executable Scripts-Footnote-279634
-Node: Comments80181
-Node: Quoting82648
-Node: DOS Quoting87271
-Node: Sample Data Files87946
-Node: Very Simple90332
-Node: Two Rules94931
-Node: More Complex97078
-Ref: More Complex-Footnote-1100008
-Node: Statements/Lines100093
-Ref: Statements/Lines-Footnote-1104555
-Node: Other Features104820
-Node: When105748
-Node: Invoking Gawk107895
-Node: Command Line109358
-Node: Options110141
-Ref: Options-Footnote-1125536
-Node: Other Arguments125561
-Node: Naming Standard Input128219
-Node: Environment Variables129313
-Node: AWKPATH Variable129871
-Ref: AWKPATH Variable-Footnote-1132629
-Node: AWKLIBPATH Variable132889
-Node: Other Environment Variables133607
-Node: Exit Status136570
-Node: Include Files137245
-Node: Loading Shared Libraries140814
-Node: Obsolete142178
-Node: Undocumented142875
-Node: Regexp143117
-Node: Regexp Usage144506
-Node: Escape Sequences146532
-Node: Regexp Operators152201
-Ref: Regexp Operators-Footnote-1159581
-Ref: Regexp Operators-Footnote-2159728
-Node: Bracket Expressions159826
-Ref: table-char-classes161716
-Node: GNU Regexp Operators164239
-Node: Case-sensitivity167962
-Ref: Case-sensitivity-Footnote-1170930
-Ref: Case-sensitivity-Footnote-2171165
-Node: Leftmost Longest171273
-Node: Computed Regexps172474
-Node: Reading Files175811
-Node: Records177813
-Ref: Records-Footnote-1186901
-Node: Fields186938
-Ref: Fields-Footnote-1189971
-Node: Nonconstant Fields190057
-Node: Changing Fields192259
-Node: Field Separators198218
-Node: Default Field Splitting200920
-Node: Regexp Field Splitting202037
-Node: Single Character Fields205379
-Node: Command Line Field Separator206438
-Node: Full Line Fields209872
-Ref: Full Line Fields-Footnote-1210380
-Node: Field Splitting Summary210426
-Ref: Field Splitting Summary-Footnote-1213525
-Node: Constant Size213626
-Node: Splitting By Content218233
-Ref: Splitting By Content-Footnote-1221982
-Node: Multiple Line222022
-Ref: Multiple Line-Footnote-1227869
-Node: Getline228048
-Node: Plain Getline230264
-Node: Getline/Variable232359
-Node: Getline/File233506
-Node: Getline/Variable/File234847
-Ref: Getline/Variable/File-Footnote-1236446
-Node: Getline/Pipe236533
-Node: Getline/Variable/Pipe239232
-Node: Getline/Coprocess240339
-Node: Getline/Variable/Coprocess241591
-Node: Getline Notes242328
-Node: Getline Summary245115
-Ref: table-getline-variants245523
-Node: Read Timeout246435
-Ref: Read Timeout-Footnote-1250176
-Node: Command line directories250233
-Node: Printing250863
-Node: Print252494
-Node: Print Examples253831
-Node: Output Separators256615
-Node: OFMT258375
-Node: Printf259733
-Node: Basic Printf260639
-Node: Control Letters262178
-Node: Format Modifiers265990
-Node: Printf Examples271999
-Node: Redirection274714
-Node: Special Files281679
-Node: Special FD282212
-Ref: Special FD-Footnote-1285837
-Node: Special Network285911
-Node: Special Caveats286761
-Node: Close Files And Pipes287557
-Ref: Close Files And Pipes-Footnote-1294540
-Ref: Close Files And Pipes-Footnote-2294688
-Node: Expressions294838
-Node: Values295970
-Node: Constants296646
-Node: Scalar Constants297326
-Ref: Scalar Constants-Footnote-1298185
-Node: Nondecimal-numbers298367
-Node: Regexp Constants301367
-Node: Using Constant Regexps301842
-Node: Variables304897
-Node: Using Variables305552
-Node: Assignment Options307276
-Node: Conversion309148
-Ref: table-locale-affects314648
-Ref: Conversion-Footnote-1315272
-Node: All Operators315381
-Node: Arithmetic Ops316011
-Node: Concatenation318516
-Ref: Concatenation-Footnote-1321308
-Node: Assignment Ops321428
-Ref: table-assign-ops326416
-Node: Increment Ops327747
-Node: Truth Values and Conditions331181
-Node: Truth Values332264
-Node: Typing and Comparison333313
-Node: Variable Typing334106
-Ref: Variable Typing-Footnote-1338003
-Node: Comparison Operators338125
-Ref: table-relational-ops338535
-Node: POSIX String Comparison342083
-Ref: POSIX String Comparison-Footnote-1343039
-Node: Boolean Ops343177
-Ref: Boolean Ops-Footnote-1347255
-Node: Conditional Exp347346
-Node: Function Calls349078
-Node: Precedence352672
-Node: Locales356341
-Node: Patterns and Actions357430
-Node: Pattern Overview358484
-Node: Regexp Patterns360153
-Node: Expression Patterns360696
-Node: Ranges364381
-Node: BEGIN/END367485
-Node: Using BEGIN/END368247
-Ref: Using BEGIN/END-Footnote-1370978
-Node: I/O And BEGIN/END371084
-Node: BEGINFILE/ENDFILE373366
-Node: Empty376280
-Node: Using Shell Variables376596
-Node: Action Overview378881
-Node: Statements381238
-Node: If Statement383092
-Node: While Statement384591
-Node: Do Statement386635
-Node: For Statement387791
-Node: Switch Statement390943
-Node: Break Statement393097
-Node: Continue Statement395087
-Node: Next Statement396880
-Node: Nextfile Statement399270
-Node: Exit Statement401925
-Node: Built-in Variables404341
-Node: User-modified405436
-Ref: User-modified-Footnote-1413794
-Node: Auto-set413856
-Ref: Auto-set-Footnote-1426934
-Ref: Auto-set-Footnote-2427139
-Node: ARGC and ARGV427195
-Node: Arrays431046
-Node: Array Basics432551
-Node: Array Intro433377
-Node: Reference to Elements437694
-Node: Assigning Elements439964
-Node: Array Example440455
-Node: Scanning an Array442187
-Node: Controlling Scanning444501
-Ref: Controlling Scanning-Footnote-1449588
-Node: Delete449904
-Ref: Delete-Footnote-1452669
-Node: Numeric Array Subscripts452726
-Node: Uninitialized Subscripts454909
-Node: Multidimensional456536
-Node: Multiscanning459629
-Node: Arrays of Arrays461218
-Node: Functions465858
-Node: Built-in466677
-Node: Calling Built-in467755
-Node: Numeric Functions469743
-Ref: Numeric Functions-Footnote-1473575
-Ref: Numeric Functions-Footnote-2473932
-Ref: Numeric Functions-Footnote-3473980
-Node: String Functions474249
-Ref: String Functions-Footnote-1497169
-Ref: String Functions-Footnote-2497298
-Ref: String Functions-Footnote-3497546
-Node: Gory Details497633
-Ref: table-sub-escapes499312
-Ref: table-sub-posix-92500666
-Ref: table-sub-proposed502017
-Ref: table-posix-sub503371
-Ref: table-gensub-escapes504916
-Ref: Gory Details-Footnote-1506092
-Ref: Gory Details-Footnote-2506143
-Node: I/O Functions506294
-Ref: I/O Functions-Footnote-1513284
-Node: Time Functions513431
-Ref: Time Functions-Footnote-1524364
-Ref: Time Functions-Footnote-2524432
-Ref: Time Functions-Footnote-3524590
-Ref: Time Functions-Footnote-4524701
-Ref: Time Functions-Footnote-5524813
-Ref: Time Functions-Footnote-6525040
-Node: Bitwise Functions525306
-Ref: table-bitwise-ops525868
-Ref: Bitwise Functions-Footnote-1530089
-Node: Type Functions530273
-Node: I18N Functions531424
-Node: User-defined533051
-Node: Definition Syntax533855
-Ref: Definition Syntax-Footnote-1538769
-Node: Function Example538838
-Ref: Function Example-Footnote-1541487
-Node: Function Caveats541509
-Node: Calling A Function542027
-Node: Variable Scope542982
-Node: Pass By Value/Reference545945
-Node: Return Statement549453
-Node: Dynamic Typing552434
-Node: Indirect Calls553365
-Node: Library Functions563052
-Ref: Library Functions-Footnote-1566565
-Ref: Library Functions-Footnote-2566708
-Node: Library Names566879
-Ref: Library Names-Footnote-1570352
-Ref: Library Names-Footnote-2570572
-Node: General Functions570658
-Node: Strtonum Function571686
-Node: Assert Function574616
-Node: Round Function577942
-Node: Cliff Random Function579483
-Node: Ordinal Functions580499
-Ref: Ordinal Functions-Footnote-1583576
-Ref: Ordinal Functions-Footnote-2583828
-Node: Join Function584039
-Ref: Join Function-Footnote-1585810
-Node: Getlocaltime Function586010
-Node: Readfile Function589751
-Node: Data File Management591590
-Node: Filetrans Function592222
-Node: Rewind Function596291
-Node: File Checking597678
-Node: Empty Files598772
-Node: Ignoring Assigns601002
-Node: Getopt Function602556
-Ref: Getopt Function-Footnote-1613859
-Node: Passwd Functions614062
-Ref: Passwd Functions-Footnote-1623040
-Node: Group Functions623128
-Node: Walking Arrays631212
-Node: Sample Programs633348
-Node: Running Examples634022
-Node: Clones634750
-Node: Cut Program635974
-Node: Egrep Program645825
-Ref: Egrep Program-Footnote-1653598
-Node: Id Program653708
-Node: Split Program657324
-Ref: Split Program-Footnote-1660843
-Node: Tee Program660971
-Node: Uniq Program663774
-Node: Wc Program671203
-Ref: Wc Program-Footnote-1675469
-Ref: Wc Program-Footnote-2675669
-Node: Miscellaneous Programs675761
-Node: Dupword Program676949
-Node: Alarm Program678980
-Node: Translate Program683787
-Ref: Translate Program-Footnote-1688174
-Ref: Translate Program-Footnote-2688422
-Node: Labels Program688556
-Ref: Labels Program-Footnote-1691927
-Node: Word Sorting692011
-Node: History Sorting695895
-Node: Extract Program697734
-Ref: Extract Program-Footnote-1705237
-Node: Simple Sed705365
-Node: Igawk Program708427
-Ref: Igawk Program-Footnote-1723584
-Ref: Igawk Program-Footnote-2723785
-Node: Anagram Program723923
-Node: Signature Program726991
-Node: Advanced Features728091
-Node: Nondecimal Data729977
-Node: Array Sorting731560
-Node: Controlling Array Traversal732257
-Node: Array Sorting Functions740541
-Ref: Array Sorting Functions-Footnote-1744410
-Node: Two-way I/O744604
-Ref: Two-way I/O-Footnote-1750036
-Node: TCP/IP Networking750118
-Node: Profiling752962
-Node: Internationalization760465
-Node: I18N and L10N761890
-Node: Explaining gettext762576
-Ref: Explaining gettext-Footnote-1767644
-Ref: Explaining gettext-Footnote-2767828
-Node: Programmer i18n767993
-Node: Translator i18n772195
-Node: String Extraction772989
-Ref: String Extraction-Footnote-1773950
-Node: Printf Ordering774036
-Ref: Printf Ordering-Footnote-1776818
-Node: I18N Portability776882
-Ref: I18N Portability-Footnote-1779331
-Node: I18N Example779394
-Ref: I18N Example-Footnote-1782032
-Node: Gawk I18N782104
-Node: Debugger782725
-Node: Debugging783696
-Node: Debugging Concepts784129
-Node: Debugging Terms785985
-Node: Awk Debugging788582
-Node: Sample Debugging Session789474
-Node: Debugger Invocation789994
-Node: Finding The Bug791327
-Node: List of Debugger Commands797814
-Node: Breakpoint Control799148
-Node: Debugger Execution Control802812
-Node: Viewing And Changing Data806172
-Node: Execution Stack809528
-Node: Debugger Info810995
-Node: Miscellaneous Debugger Commands814977
-Node: Readline Support820153
-Node: Limitations820984
-Node: Arbitrary Precision Arithmetic823236
-Ref: Arbitrary Precision Arithmetic-Footnote-1824885
-Node: General Arithmetic825033
-Node: Floating Point Issues826753
-Node: String Conversion Precision827634
-Ref: String Conversion Precision-Footnote-1829339
-Node: Unexpected Results829448
-Node: POSIX Floating Point Problems831601
-Ref: POSIX Floating Point Problems-Footnote-1835426
-Node: Integer Programming835464
-Node: Floating-point Programming837203
-Ref: Floating-point Programming-Footnote-1843534
-Ref: Floating-point Programming-Footnote-2843804
-Node: Floating-point Representation844068
-Node: Floating-point Context845233
-Ref: table-ieee-formats846072
-Node: Rounding Mode847456
-Ref: table-rounding-modes847935
-Ref: Rounding Mode-Footnote-1850950
-Node: Gawk and MPFR851129
-Node: Arbitrary Precision Floats852384
-Ref: Arbitrary Precision Floats-Footnote-1854827
-Node: Setting Precision855143
-Ref: table-predefined-precision-strings855829
-Node: Setting Rounding Mode857974
-Ref: table-gawk-rounding-modes858378
-Node: Floating-point Constants859565
-Node: Changing Precision860994
-Ref: Changing Precision-Footnote-1862391
-Node: Exact Arithmetic862565
-Node: Arbitrary Precision Integers865703
-Ref: Arbitrary Precision Integers-Footnote-1868718
-Node: Dynamic Extensions868865
-Node: Extension Intro870323
-Node: Plugin License871588
-Node: Extension Mechanism Outline872273
-Ref: load-extension872690
-Ref: load-new-function874168
-Ref: call-new-function875163
-Node: Extension API Description877178
-Node: Extension API Functions Introduction878391
-Node: General Data Types883257
-Ref: General Data Types-Footnote-1888859
-Node: Requesting Values889158
-Ref: table-value-types-returned889889
-Node: Constructor Functions890843
-Node: Registration Functions893863
-Node: Extension Functions894548
-Node: Exit Callback Functions896774
-Node: Extension Version String898023
-Node: Input Parsers898673
-Node: Output Wrappers908430
-Node: Two-way processors912940
-Node: Printing Messages915148
-Ref: Printing Messages-Footnote-1916225
-Node: Updating `ERRNO'916377
-Node: Accessing Parameters917116
-Node: Symbol Table Access918346
-Node: Symbol table by name918858
-Node: Symbol table by cookie920605
-Ref: Symbol table by cookie-Footnote-1924735
-Node: Cached values924798
-Ref: Cached values-Footnote-1928247
-Node: Array Manipulation928338
-Ref: Array Manipulation-Footnote-1929436
-Node: Array Data Types929475
-Ref: Array Data Types-Footnote-1932178
-Node: Array Functions932270
-Node: Flattening Arrays936036
-Node: Creating Arrays942888
-Node: Extension API Variables947613
-Node: Extension Versioning948249
-Node: Extension API Informational Variables950150
-Node: Extension API Boilerplate951236
-Node: Finding Extensions955040
-Node: Extension Example955600
-Node: Internal File Description956330
-Node: Internal File Ops960421
-Ref: Internal File Ops-Footnote-1971930
-Node: Using Internal File Ops972070
-Ref: Using Internal File Ops-Footnote-1974423
-Node: Extension Samples974689
-Node: Extension Sample File Functions976213
-Node: Extension Sample Fnmatch984698
-Node: Extension Sample Fork986467
-Node: Extension Sample Inplace987680
-Node: Extension Sample Ord989458
-Node: Extension Sample Readdir990294
-Node: Extension Sample Revout991826
-Node: Extension Sample Rev2way992419
-Node: Extension Sample Read write array993109
-Node: Extension Sample Readfile994992
-Node: Extension Sample API Tests995810
-Node: Extension Sample Time996335
-Node: gawkextlib997699
-Node: Language History1000480
-Node: V7/SVR3.11002073
-Node: SVR41004393
-Node: POSIX1005835
-Node: BTL1007221
-Node: POSIX/GNU1007955
-Node: Feature History1013554
-Node: Common Extensions1026530
-Node: Ranges and Locales1027842
-Ref: Ranges and Locales-Footnote-11032459
-Ref: Ranges and Locales-Footnote-21032486
-Ref: Ranges and Locales-Footnote-31032720
-Node: Contributors1032941
-Node: Installation1038086
-Node: Gawk Distribution1038980
-Node: Getting1039464
-Node: Extracting1040290
-Node: Distribution contents1041982
-Node: Unix Installation1047687
-Node: Quick Installation1048304
-Node: Additional Configuration Options1050750
-Node: Configuration Philosophy1052486
-Node: Non-Unix Installation1054840
-Node: PC Installation1055298
-Node: PC Binary Installation1056597
-Node: PC Compiling1058445
-Node: PC Testing1061389
-Node: PC Using1062565
-Node: Cygwin1066733
-Node: MSYS1067542
-Node: VMS Installation1068056
-Node: VMS Compilation1068820
-Ref: VMS Compilation-Footnote-11070072
-Node: VMS Dynamic Extensions1070130
-Node: VMS Installation Details1071503
-Node: VMS Running1073754
-Node: VMS GNV1076588
-Node: VMS Old Gawk1077311
-Node: Bugs1077781
-Node: Other Versions1081699
-Node: Notes1087783
-Node: Compatibility Mode1088583
-Node: Additions1089366
-Node: Accessing The Source1090293
-Node: Adding Code1091733
-Node: New Ports1097778
-Node: Derived Files1101913
-Ref: Derived Files-Footnote-11107234
-Ref: Derived Files-Footnote-21107268
-Ref: Derived Files-Footnote-31107868
-Node: Future Extensions1107966
-Node: Implementation Limitations1108549
-Node: Extension Design1109801
-Node: Old Extension Problems1110955
-Ref: Old Extension Problems-Footnote-11112463
-Node: Extension New Mechanism Goals1112520
-Ref: Extension New Mechanism Goals-Footnote-11115885
-Node: Extension Other Design Decisions1116071
-Node: Extension Future Growth1118177
-Node: Old Extension Mechanism1119013
-Node: Basic Concepts1120753
-Node: Basic High Level1121434
-Ref: figure-general-flow1121705
-Ref: figure-process-flow1122304
-Ref: Basic High Level-Footnote-11125533
-Node: Basic Data Typing1125718
-Node: Glossary1129073
-Node: Copying1154535
-Node: GNU Free Documentation License1192092
-Node: Index1217229
+Node: Foreword40929
+Node: Preface45274
+Ref: Preface-Footnote-148327
+Ref: Preface-Footnote-248423
+Node: History48655
+Node: Names51029
+Ref: Names-Footnote-152506
+Node: This Manual52578
+Ref: This Manual-Footnote-158352
+Node: Conventions58452
+Node: Manual History60608
+Ref: Manual History-Footnote-164056
+Ref: Manual History-Footnote-264097
+Node: How To Contribute64171
+Node: Acknowledgments65315
+Node: Getting Started69509
+Node: Running gawk71888
+Node: One-shot73074
+Node: Read Terminal74299
+Ref: Read Terminal-Footnote-175949
+Ref: Read Terminal-Footnote-276225
+Node: Long76396
+Node: Executable Scripts77772
+Ref: Executable Scripts-Footnote-179605
+Ref: Executable Scripts-Footnote-279707
+Node: Comments80254
+Node: Quoting82721
+Node: DOS Quoting87344
+Node: Sample Data Files88019
+Node: Very Simple90405
+Node: Two Rules95004
+Node: More Complex97151
+Ref: More Complex-Footnote-1100081
+Node: Statements/Lines100166
+Ref: Statements/Lines-Footnote-1104628
+Node: Other Features104893
+Node: When105821
+Node: Invoking Gawk107968
+Node: Command Line109431
+Node: Options110214
+Ref: Options-Footnote-1125609
+Node: Other Arguments125634
+Node: Naming Standard Input128292
+Node: Environment Variables129386
+Node: AWKPATH Variable129944
+Ref: AWKPATH Variable-Footnote-1132702
+Node: AWKLIBPATH Variable132962
+Node: Other Environment Variables133680
+Node: Exit Status136643
+Node: Include Files137318
+Node: Loading Shared Libraries140887
+Node: Obsolete142251
+Node: Undocumented142948
+Node: Regexp143190
+Node: Regexp Usage144579
+Node: Escape Sequences146605
+Node: Regexp Operators152274
+Ref: Regexp Operators-Footnote-1159654
+Ref: Regexp Operators-Footnote-2159801
+Node: Bracket Expressions159899
+Ref: table-char-classes161789
+Node: GNU Regexp Operators164312
+Node: Case-sensitivity168035
+Ref: Case-sensitivity-Footnote-1171003
+Ref: Case-sensitivity-Footnote-2171238
+Node: Leftmost Longest171346
+Node: Computed Regexps172547
+Node: Reading Files175884
+Node: Records177886
+Ref: Records-Footnote-1186974
+Node: Fields187011
+Ref: Fields-Footnote-1190044
+Node: Nonconstant Fields190130
+Node: Changing Fields192332
+Node: Field Separators198291
+Node: Default Field Splitting200993
+Node: Regexp Field Splitting202110
+Node: Single Character Fields205452
+Node: Command Line Field Separator206511
+Node: Full Line Fields209945
+Ref: Full Line Fields-Footnote-1210453
+Node: Field Splitting Summary210499
+Ref: Field Splitting Summary-Footnote-1213598
+Node: Constant Size213699
+Node: Splitting By Content218306
+Ref: Splitting By Content-Footnote-1222055
+Node: Multiple Line222095
+Ref: Multiple Line-Footnote-1227942
+Node: Getline228121
+Node: Plain Getline230337
+Node: Getline/Variable232432
+Node: Getline/File233579
+Node: Getline/Variable/File234920
+Ref: Getline/Variable/File-Footnote-1236519
+Node: Getline/Pipe236606
+Node: Getline/Variable/Pipe239305
+Node: Getline/Coprocess240412
+Node: Getline/Variable/Coprocess241664
+Node: Getline Notes242401
+Node: Getline Summary245188
+Ref: table-getline-variants245596
+Node: Read Timeout246508
+Ref: Read Timeout-Footnote-1250249
+Node: Command line directories250306
+Node: Printing250936
+Node: Print252567
+Node: Print Examples253904
+Node: Output Separators256688
+Node: OFMT258448
+Node: Printf259806
+Node: Basic Printf260712
+Node: Control Letters262251
+Node: Format Modifiers266063
+Node: Printf Examples272072
+Node: Redirection274787
+Node: Special Files281752
+Node: Special FD282285
+Ref: Special FD-Footnote-1285910
+Node: Special Network285984
+Node: Special Caveats286834
+Node: Close Files And Pipes287630
+Ref: Close Files And Pipes-Footnote-1294613
+Ref: Close Files And Pipes-Footnote-2294761
+Node: Expressions294911
+Node: Values296043
+Node: Constants296719
+Node: Scalar Constants297399
+Ref: Scalar Constants-Footnote-1298258
+Node: Nondecimal-numbers298440
+Node: Regexp Constants301440
+Node: Using Constant Regexps301915
+Node: Variables304970
+Node: Using Variables305625
+Node: Assignment Options307349
+Node: Conversion309221
+Ref: table-locale-affects314721
+Ref: Conversion-Footnote-1315345
+Node: All Operators315454
+Node: Arithmetic Ops316084
+Node: Concatenation318589
+Ref: Concatenation-Footnote-1321381
+Node: Assignment Ops321501
+Ref: table-assign-ops326489
+Node: Increment Ops327820
+Node: Truth Values and Conditions331254
+Node: Truth Values332337
+Node: Typing and Comparison333386
+Node: Variable Typing334179
+Ref: Variable Typing-Footnote-1338076
+Node: Comparison Operators338198
+Ref: table-relational-ops338608
+Node: POSIX String Comparison342156
+Ref: POSIX String Comparison-Footnote-1343112
+Node: Boolean Ops343250
+Ref: Boolean Ops-Footnote-1347328
+Node: Conditional Exp347419
+Node: Function Calls349151
+Node: Precedence352745
+Node: Locales356414
+Node: Patterns and Actions357503
+Node: Pattern Overview358557
+Node: Regexp Patterns360226
+Node: Expression Patterns360769
+Node: Ranges364454
+Node: BEGIN/END367558
+Node: Using BEGIN/END368320
+Ref: Using BEGIN/END-Footnote-1371051
+Node: I/O And BEGIN/END371157
+Node: BEGINFILE/ENDFILE373439
+Node: Empty376353
+Node: Using Shell Variables376669
+Node: Action Overview378954
+Node: Statements381311
+Node: If Statement383165
+Node: While Statement384664
+Node: Do Statement386708
+Node: For Statement387864
+Node: Switch Statement391016
+Node: Break Statement393170
+Node: Continue Statement395160
+Node: Next Statement396953
+Node: Nextfile Statement399343
+Node: Exit Statement401998
+Node: Built-in Variables404414
+Node: User-modified405509
+Ref: User-modified-Footnote-1413867
+Node: Auto-set413929
+Ref: Auto-set-Footnote-1427007
+Ref: Auto-set-Footnote-2427212
+Node: ARGC and ARGV427268
+Node: Arrays431119
+Node: Array Basics432624
+Node: Array Intro433450
+Node: Reference to Elements437767
+Node: Assigning Elements440037
+Node: Array Example440528
+Node: Scanning an Array442260
+Node: Controlling Scanning444574
+Ref: Controlling Scanning-Footnote-1449661
+Node: Delete449977
+Ref: Delete-Footnote-1452742
+Node: Numeric Array Subscripts452799
+Node: Uninitialized Subscripts454982
+Node: Multidimensional456609
+Node: Multiscanning459702
+Node: Arrays of Arrays461291
+Node: Functions465931
+Node: Built-in466750
+Node: Calling Built-in467828
+Node: Numeric Functions469816
+Ref: Numeric Functions-Footnote-1473648
+Ref: Numeric Functions-Footnote-2474005
+Ref: Numeric Functions-Footnote-3474053
+Node: String Functions474322
+Ref: String Functions-Footnote-1497242
+Ref: String Functions-Footnote-2497371
+Ref: String Functions-Footnote-3497619
+Node: Gory Details497706
+Ref: table-sub-escapes499385
+Ref: table-sub-posix-92500739
+Ref: table-sub-proposed502090
+Ref: table-posix-sub503444
+Ref: table-gensub-escapes504989
+Ref: Gory Details-Footnote-1506165
+Ref: Gory Details-Footnote-2506216
+Node: I/O Functions506367
+Ref: I/O Functions-Footnote-1513357
+Node: Time Functions513504
+Ref: Time Functions-Footnote-1524437
+Ref: Time Functions-Footnote-2524505
+Ref: Time Functions-Footnote-3524663
+Ref: Time Functions-Footnote-4524774
+Ref: Time Functions-Footnote-5524886
+Ref: Time Functions-Footnote-6525113
+Node: Bitwise Functions525379
+Ref: table-bitwise-ops525941
+Ref: Bitwise Functions-Footnote-1530162
+Node: Type Functions530346
+Node: I18N Functions531497
+Node: User-defined533124
+Node: Definition Syntax533928
+Ref: Definition Syntax-Footnote-1538842
+Node: Function Example538911
+Ref: Function Example-Footnote-1541560
+Node: Function Caveats541582
+Node: Calling A Function542100
+Node: Variable Scope543055
+Node: Pass By Value/Reference546018
+Node: Return Statement549526
+Node: Dynamic Typing552507
+Node: Indirect Calls553438
+Node: Library Functions563125
+Ref: Library Functions-Footnote-1566638
+Ref: Library Functions-Footnote-2566781
+Node: Library Names566952
+Ref: Library Names-Footnote-1570425
+Ref: Library Names-Footnote-2570645
+Node: General Functions570731
+Node: Strtonum Function571759
+Node: Assert Function574689
+Node: Round Function578015
+Node: Cliff Random Function579556
+Node: Ordinal Functions580572
+Ref: Ordinal Functions-Footnote-1583649
+Ref: Ordinal Functions-Footnote-2583901
+Node: Join Function584112
+Ref: Join Function-Footnote-1585883
+Node: Getlocaltime Function586083
+Node: Readfile Function589824
+Node: Data File Management591663
+Node: Filetrans Function592295
+Node: Rewind Function596364
+Node: File Checking597751
+Node: Empty Files598845
+Node: Ignoring Assigns601075
+Node: Getopt Function602629
+Ref: Getopt Function-Footnote-1613932
+Node: Passwd Functions614135
+Ref: Passwd Functions-Footnote-1623113
+Node: Group Functions623201
+Node: Walking Arrays631285
+Node: Sample Programs633421
+Node: Running Examples634095
+Node: Clones634823
+Node: Cut Program636047
+Node: Egrep Program645898
+Ref: Egrep Program-Footnote-1653671
+Node: Id Program653781
+Node: Split Program657397
+Ref: Split Program-Footnote-1660916
+Node: Tee Program661044
+Node: Uniq Program663847
+Node: Wc Program671276
+Ref: Wc Program-Footnote-1675542
+Ref: Wc Program-Footnote-2675742
+Node: Miscellaneous Programs675834
+Node: Dupword Program677022
+Node: Alarm Program679053
+Node: Translate Program683860
+Ref: Translate Program-Footnote-1688247
+Ref: Translate Program-Footnote-2688495
+Node: Labels Program688629
+Ref: Labels Program-Footnote-1692000
+Node: Word Sorting692084
+Node: History Sorting695968
+Node: Extract Program697807
+Ref: Extract Program-Footnote-1705310
+Node: Simple Sed705438
+Node: Igawk Program708500
+Ref: Igawk Program-Footnote-1723657
+Ref: Igawk Program-Footnote-2723858
+Node: Anagram Program723996
+Node: Signature Program727064
+Node: Advanced Features728164
+Node: Nondecimal Data730050
+Node: Array Sorting731633
+Node: Controlling Array Traversal732330
+Node: Array Sorting Functions740614
+Ref: Array Sorting Functions-Footnote-1744483
+Node: Two-way I/O744677
+Ref: Two-way I/O-Footnote-1750109
+Node: TCP/IP Networking750191
+Node: Profiling753035
+Node: Internationalization760538
+Node: I18N and L10N761963
+Node: Explaining gettext762649
+Ref: Explaining gettext-Footnote-1767717
+Ref: Explaining gettext-Footnote-2767901
+Node: Programmer i18n768066
+Node: Translator i18n772268
+Node: String Extraction773062
+Ref: String Extraction-Footnote-1774023
+Node: Printf Ordering774109
+Ref: Printf Ordering-Footnote-1776891
+Node: I18N Portability776955
+Ref: I18N Portability-Footnote-1779404
+Node: I18N Example779467
+Ref: I18N Example-Footnote-1782105
+Node: Gawk I18N782177
+Node: Debugger782798
+Node: Debugging783769
+Node: Debugging Concepts784202
+Node: Debugging Terms786058
+Node: Awk Debugging788655
+Node: Sample Debugging Session789547
+Node: Debugger Invocation790067
+Node: Finding The Bug791400
+Node: List of Debugger Commands797887
+Node: Breakpoint Control799221
+Node: Debugger Execution Control802885
+Node: Viewing And Changing Data806245
+Node: Execution Stack809601
+Node: Debugger Info811068
+Node: Miscellaneous Debugger Commands815050
+Node: Readline Support820226
+Node: Limitations821057
+Node: Arbitrary Precision Arithmetic823309
+Ref: Arbitrary Precision Arithmetic-Footnote-1824958
+Node: General Arithmetic825106
+Node: Floating Point Issues826826
+Node: String Conversion Precision827707
+Ref: String Conversion Precision-Footnote-1829412
+Node: Unexpected Results829521
+Node: POSIX Floating Point Problems831674
+Ref: POSIX Floating Point Problems-Footnote-1835499
+Node: Integer Programming835537
+Node: Floating-point Programming837276
+Ref: Floating-point Programming-Footnote-1843607
+Ref: Floating-point Programming-Footnote-2843877
+Node: Floating-point Representation844141
+Node: Floating-point Context845306
+Ref: table-ieee-formats846145
+Node: Rounding Mode847529
+Ref: table-rounding-modes848008
+Ref: Rounding Mode-Footnote-1851023
+Node: Gawk and MPFR851202
+Node: Arbitrary Precision Floats852457
+Ref: Arbitrary Precision Floats-Footnote-1854900
+Node: Setting Precision855216
+Ref: table-predefined-precision-strings855902
+Node: Setting Rounding Mode858047
+Ref: table-gawk-rounding-modes858451
+Node: Floating-point Constants859638
+Node: Changing Precision861067
+Ref: Changing Precision-Footnote-1862464
+Node: Exact Arithmetic862638
+Node: Arbitrary Precision Integers865776
+Ref: Arbitrary Precision Integers-Footnote-1868791
+Node: Dynamic Extensions868938
+Node: Extension Intro870396
+Node: Plugin License871661
+Node: Extension Mechanism Outline872346
+Ref: load-extension872763
+Ref: load-new-function874241
+Ref: call-new-function875236
+Node: Extension API Description877251
+Node: Extension API Functions Introduction878538
+Node: General Data Types883410
+Ref: General Data Types-Footnote-1889105
+Node: Requesting Values889404
+Ref: table-value-types-returned890141
+Node: Memory Allocation Functions891095
+Node: Constructor Functions893456
+Node: Registration Functions895214
+Node: Extension Functions895899
+Node: Exit Callback Functions898201
+Node: Extension Version String899450
+Node: Input Parsers900100
+Node: Output Wrappers909857
+Node: Two-way processors914367
+Node: Printing Messages916575
+Ref: Printing Messages-Footnote-1917652
+Node: Updating `ERRNO'917804
+Node: Accessing Parameters918543
+Node: Symbol Table Access919773
+Node: Symbol table by name920287
+Node: Symbol table by cookie922036
+Ref: Symbol table by cookie-Footnote-1926168
+Node: Cached values926231
+Ref: Cached values-Footnote-1929721
+Node: Array Manipulation929812
+Ref: Array Manipulation-Footnote-1930910
+Node: Array Data Types930949
+Ref: Array Data Types-Footnote-1933652
+Node: Array Functions933744
+Node: Flattening Arrays937580
+Node: Creating Arrays944432
+Node: Extension API Variables949157
+Node: Extension Versioning949793
+Node: Extension API Informational Variables951694
+Node: Extension API Boilerplate952780
+Node: Finding Extensions956584
+Node: Extension Example957144
+Node: Internal File Description957874
+Node: Internal File Ops961965
+Ref: Internal File Ops-Footnote-1973474
+Node: Using Internal File Ops973614
+Ref: Using Internal File Ops-Footnote-1975967
+Node: Extension Samples976233
+Node: Extension Sample File Functions977757
+Node: Extension Sample Fnmatch986242
+Node: Extension Sample Fork988011
+Node: Extension Sample Inplace989224
+Node: Extension Sample Ord991002
+Node: Extension Sample Readdir991838
+Node: Extension Sample Revout993370
+Node: Extension Sample Rev2way993963
+Node: Extension Sample Read write array994653
+Node: Extension Sample Readfile996536
+Node: Extension Sample API Tests997354
+Node: Extension Sample Time997879
+Node: gawkextlib999243
+Node: Language History1002024
+Node: V7/SVR3.11003617
+Node: SVR41005937
+Node: POSIX1007379
+Node: BTL1008765
+Node: POSIX/GNU1009499
+Node: Feature History1015098
+Node: Common Extensions1028074
+Node: Ranges and Locales1029386
+Ref: Ranges and Locales-Footnote-11034003
+Ref: Ranges and Locales-Footnote-21034030
+Ref: Ranges and Locales-Footnote-31034264
+Node: Contributors1034485
+Node: Installation1039630
+Node: Gawk Distribution1040524
+Node: Getting1041008
+Node: Extracting1041834
+Node: Distribution contents1043526
+Node: Unix Installation1049231
+Node: Quick Installation1049848
+Node: Additional Configuration Options1052294
+Node: Configuration Philosophy1054030
+Node: Non-Unix Installation1056384
+Node: PC Installation1056842
+Node: PC Binary Installation1058141
+Node: PC Compiling1059989
+Node: PC Testing1062933
+Node: PC Using1064109
+Node: Cygwin1068277
+Node: MSYS1069086
+Node: VMS Installation1069600
+Node: VMS Compilation1070364
+Ref: VMS Compilation-Footnote-11071616
+Node: VMS Dynamic Extensions1071674
+Node: VMS Installation Details1073047
+Node: VMS Running1075298
+Node: VMS GNV1078132
+Node: VMS Old Gawk1078855
+Node: Bugs1079325
+Node: Other Versions1083243
+Node: Notes1089327
+Node: Compatibility Mode1090127
+Node: Additions1090910
+Node: Accessing The Source1091837
+Node: Adding Code1093277
+Node: New Ports1099322
+Node: Derived Files1103457
+Ref: Derived Files-Footnote-11108778
+Ref: Derived Files-Footnote-21108812
+Ref: Derived Files-Footnote-31109412
+Node: Future Extensions1109510
+Node: Implementation Limitations1110093
+Node: Extension Design1111345
+Node: Old Extension Problems1112499
+Ref: Old Extension Problems-Footnote-11114007
+Node: Extension New Mechanism Goals1114064
+Ref: Extension New Mechanism Goals-Footnote-11117429
+Node: Extension Other Design Decisions1117615
+Node: Extension Future Growth1119721
+Node: Old Extension Mechanism1120557
+Node: Basic Concepts1122297
+Node: Basic High Level1122978
+Ref: figure-general-flow1123249
+Ref: figure-process-flow1123848
+Ref: Basic High Level-Footnote-11127077
+Node: Basic Data Typing1127262
+Node: Glossary1130617
+Node: Copying1156079
+Node: GNU Free Documentation License1193636
+Node: Index1218773

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 713f5a46..f0c7d6e6 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -742,6 +742,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}.
@@ -29575,6 +29576,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}.
@@ -29668,10 +29670,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
@@ -29701,7 +29701,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
@@ -29784,7 +29784,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.
@@ -29946,44 +29946,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.
@@ -29996,7 +29985,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.
@@ -30020,11 +30009,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
@@ -30072,7 +30097,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.
@@ -30810,7 +30835,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.}
@@ -31007,7 +31032,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,
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,
diff --git a/extension/ChangeLog b/extension/ChangeLog
index bde626de..4a1fe2ed 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,3 +1,14 @@
+2014-03-08 Andrew J. Schorr <aschorr@telemetry-investments.com>
+
+ * filefuncs.c (read_symlink, do_fts): Replace free with gawk_free.
+ * inplace.c (at_exit, do_inplace_end): Ditto.
+ * readdir.c (dir_close): Ditto.
+ * readfile.c (do_readfile): Ditto.
+ * revtwoway.c (close_two_proc_data): Ditto.
+ * rwarray (read_elem): Replace realloc with gawk_realloc.
+ (read_value): Replace malloc and free with gawk_malloc and gawk_free.
+ * testext.c (try_modify_environ): Replace free with gawk_free.
+
2014-02-12 John E. Malmberg <wb8tyw@qsl.net>
* time.c: Better hack for nanosleep bug based on feedback from HP.
diff --git a/extension/filefuncs.c b/extension/filefuncs.c
index 3eb2a6b5..58acab4d 100644
--- a/extension/filefuncs.c
+++ b/extension/filefuncs.c
@@ -284,7 +284,7 @@ read_symlink(const char *fname, size_t bufsize, ssize_t *linksize)
returns -1 with errno == ERANGE if the buffer is
too small. */
if (errno != ERANGE) {
- free(buf);
+ gawk_free(buf);
return NULL;
}
}
@@ -293,7 +293,7 @@ read_symlink(const char *fname, size_t bufsize, ssize_t *linksize)
buf[*linksize] = '\0';
return buf;
}
- free(buf);
+ gawk_free(buf);
if (bufsize <= MAXSIZE/2)
bufsize *= 2;
else if (bufsize < MAXSIZE)
@@ -854,7 +854,7 @@ do_fts(int nargs, awk_value_t *result)
out:
if (pathvector != NULL)
- free(pathvector);
+ gawk_free(pathvector);
if (path_array != NULL)
(void) release_flattened_array(pathlist.array_cookie, path_array);
diff --git a/extension/inplace.c b/extension/inplace.c
index 91b1a229..b6228a5b 100644
--- a/extension/inplace.c
+++ b/extension/inplace.c
@@ -96,7 +96,7 @@ at_exit(void *data, int exit_status)
(void) exit_status; /* silence warnings */
if (state.tname) {
unlink(state.tname);
- free(state.tname);
+ gawk_free(state.tname);
state.tname = NULL;
}
}
@@ -242,7 +242,7 @@ do_inplace_end(int nargs, awk_value_t *result)
if (link(filename.str_value.str, bakname) < 0)
fatal(ext_id, _("inplace_end: link(`%s', `%s') failed (%s)"),
filename.str_value.str, bakname, strerror(errno));
- free(bakname);
+ gawk_free(bakname);
}
#ifdef __MINGW32__
@@ -252,7 +252,7 @@ do_inplace_end(int nargs, awk_value_t *result)
if (rename(state.tname, filename.str_value.str) < 0)
fatal(ext_id, _("inplace_end: rename(`%s', `%s') failed (%s)"),
state.tname, filename.str_value.str, strerror(errno));
- free(state.tname);
+ gawk_free(state.tname);
state.tname = NULL;
return make_number(0, result);
}
diff --git a/extension/readdir.c b/extension/readdir.c
index 91296801..5b9a7913 100644
--- a/extension/readdir.c
+++ b/extension/readdir.c
@@ -235,8 +235,8 @@ dir_close(awk_input_buf_t *iobuf)
the_dir = (open_directory_t *) iobuf->opaque;
closedir(the_dir->dp);
- free(the_dir->buf);
- free(the_dir);
+ gawk_free(the_dir->buf);
+ gawk_free(the_dir);
iobuf->fd = -1;
}
diff --git a/extension/readfile.c b/extension/readfile.c
index 06889c3d..71d67ee6 100644
--- a/extension/readfile.c
+++ b/extension/readfile.c
@@ -107,7 +107,7 @@ do_readfile(int nargs, awk_value_t *result)
if ((ret = read(fd, text, sbuf.st_size)) != sbuf.st_size) {
(void) close(fd);
update_ERRNO_int(errno);
- free(text);
+ gawk_free(text);
goto done;
}
diff --git a/extension/revtwoway.c b/extension/revtwoway.c
index 5f490825..675e0efa 100644
--- a/extension/revtwoway.c
+++ b/extension/revtwoway.c
@@ -119,8 +119,8 @@ close_two_proc_data(two_way_proc_data_t *proc_data)
return;
}
- free(proc_data->data);
- free(proc_data);
+ gawk_free(proc_data->data);
+ gawk_free(proc_data);
}
/*
diff --git a/extension/rwarray.c b/extension/rwarray.c
index 6185000b..940acd62 100644
--- a/extension/rwarray.c
+++ b/extension/rwarray.c
@@ -408,7 +408,7 @@ read_elem(FILE *fp, awk_element_t *element)
buflen = index_len;
} else if (buflen < index_len) {
/* reallocate buffer */
- char *cp = realloc(buffer, index_len);
+ char *cp = gawk_realloc(buffer, index_len);
if (cp == NULL)
return awk_false;
@@ -468,11 +468,11 @@ read_value(FILE *fp, awk_value_t *value)
len = ntohl(len);
value->val_type = AWK_STRING;
value->str_value.len = len;
- value->str_value.str = malloc(len + 2);
+ value->str_value.str = gawk_malloc(len + 2);
memset(value->str_value.str, '\0', len + 2);
if (fread(value->str_value.str, 1, len, fp) != (ssize_t) len) {
- free(value->str_value.str);
+ gawk_free(value->str_value.str);
return awk_false;
}
}
diff --git a/extension/testext.c b/extension/testext.c
index d11272b8..22f2eb84 100644
--- a/extension/testext.c
+++ b/extension/testext.c
@@ -237,8 +237,8 @@ try_modify_environ(int nargs, awk_value_t *result)
printf("try_modify_environ: set_array_element of ENVIRON passed\n");
} else {
printf("try_modify_environ: set_array_element of ENVIRON failed\n");
- free(index.str_value.str);
- free(value.str_value.str);
+ gawk_free(index.str_value.str);
+ gawk_free(value.str_value.str);
}
if (! flatten_array(environ_array, & flat_array)) {
diff --git a/gawkapi.c b/gawkapi.c
index fb456ce7..782cee48 100644
--- a/gawkapi.c
+++ b/gawkapi.c
@@ -1111,6 +1111,12 @@ gawk_api_t api_impl = {
api_clear_array,
api_flatten_array,
api_release_flattened_array,
+
+ /* Memory allocation */
+ malloc,
+ calloc,
+ realloc,
+ free,
};
/* init_ext_api --- init the extension API */
diff --git a/gawkapi.h b/gawkapi.h
index b26ee24c..e84f2dea 100644
--- a/gawkapi.h
+++ b/gawkapi.h
@@ -30,7 +30,6 @@
*
* FILE - <stdio.h>
* NULL - <stddef.h>
- * malloc() - <stdlib.h>
* memset(), memcpy() - <string.h>
* size_t - <sys/types.h>
* struct stat - <sys/stat.h>
@@ -62,7 +61,7 @@
*
* Additional important information:
*
- * 1. ALL string values in awk_value_t objects need to come from malloc().
+ * 1. ALL string values in awk_value_t objects need to come from api_malloc().
* Gawk will handle releasing the storage if necessary. This is slightly
* awkward, in that you can't take an awk_value_t that you got from gawk
* and reuse it directly, even for something that is conceptually pass
@@ -264,7 +263,7 @@ typedef struct awk_two_way_processor {
/* Current version of the API. */
enum {
GAWK_API_MAJOR_VERSION = 1,
- GAWK_API_MINOR_VERSION = 0
+ GAWK_API_MINOR_VERSION = 1
};
/* A number of typedefs related to different types of values. */
@@ -665,6 +664,16 @@ typedef struct gawk_api {
awk_bool_t (*api_release_flattened_array)(awk_ext_id_t id,
awk_array_t a_cookie,
awk_flat_array_t *data);
+
+ /*
+ * Hooks to provide access to gawk's memory allocation functions.
+ * This ensures that memory passed between gawk and the extension
+ * is allocated and released by the same library.
+ */
+ void *(*api_malloc)(size_t size);
+ void *(*api_calloc)(size_t nmemb, size_t size);
+ void *(*api_realloc)(void *ptr, size_t size);
+ void (*api_free)(void *ptr);
} gawk_api_t;
#ifndef GAWK /* these are not for the gawk code itself! */
@@ -736,6 +745,11 @@ typedef struct gawk_api {
#define release_flattened_array(array, data) \
(api->api_release_flattened_array(ext_id, array, data))
+#define gawk_malloc(size) (api->api_malloc(size))
+#define gawk_calloc(nmemb, size) (api->api_calloc(nmemb, size))
+#define gawk_realloc(ptr, size) (api->api_realloc(ptr, size))
+#define gawk_free(ptr) (api->api_free(ptr))
+
#define create_value(value, result) \
(api->api_create_value(ext_id, value,result))
@@ -747,13 +761,13 @@ typedef struct gawk_api {
#define emalloc(pointer, type, size, message) \
do { \
- if ((pointer = (type) malloc(size)) == 0) \
+ if ((pointer = (type) gawk_malloc(size)) == 0) \
fatal(ext_id, "%s: malloc of %d bytes failed\n", message, size); \
} while(0)
#define erealloc(pointer, type, size, message) \
do { \
- if ((pointer = (type) realloc(pointer, size)) == 0) \
+ if ((pointer = (type) gawk_realloc(pointer, size)) == 0) \
fatal(ext_id, "%s: realloc of %d bytes failed\n", message, size); \
} while(0)
View Lorry Controller Status