aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--ChangeLog10
-rw-r--r--NEWS4
-rw-r--r--doc/ChangeLog10
-rw-r--r--doc/gawk.info1238
-rw-r--r--doc/gawk.texi124
-rw-r--r--doc/gawktexi.in124
-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
-rw-r--r--helpers/ChangeLog4
-rwxr-xr-xhelpers/quoteconvert2.sh49
-rw-r--r--helpers/scanfmt.c22
-rw-r--r--helpers/tryfmt.c23
20 files changed, 983 insertions, 698 deletions
diff --git a/ChangeLog b/ChangeLog
index 60fbcca2..4ec71357 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/NEWS b/NEWS
index fe841916..8d919351 100644
--- a/NEWS
+++ b/NEWS
@@ -48,6 +48,10 @@ is now generated by a DCL script. Also, the extension facility works
and several of the extensions can be built and used. Currently, the
extension facility only works on Alpha and Itanium.
+12. The API now provides functions pointers for malloc(), calloc(),
+realloc() and free(), to insure that the same memory allocation
+functions are always used. This bumps the minor version by one.
+
XXX. A number of bugs have been fixed. See the ChangeLog.
Changes from 4.0.2 to 4.1.0
diff --git a/doc/ChangeLog b/doc/ChangeLog
index 71ca6a1f..ac48a973 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,13 @@
+2014-03-08 Arnold D. Robbins <arnold@skeeve.com>
+
+ * gawktexi.in: Minor edits to the discussion of the memory allocation
+ functions.
+
+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 c3565d3c..74773fcb 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'.
@@ -21742,6 +21743,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'.
@@ -21790,6 +21792,8 @@ operations:
* Symbol table access: retrieving a global variable, creating one,
or changing one.
+ * Allocating, reallocating, and releasing memory.
+
* Creating and releasing cached values; this provides an efficient
way to use values for multiple variables and can be a big
performance win.
@@ -21818,10 +21822,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>'
@@ -21847,7 +21849,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
@@ -21919,7 +21923,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.
@@ -22024,7 +22030,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
------------------------
@@ -22057,46 +22063,43 @@ 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.
+ The API has to provide these functions because it is possible for an
+extension to be compiled and linked against a different version of the
+C library than was used for the `gawk' executable.(1) If `gawk' were to
+use its version of `free()' when the memory came from an unrelated
+version of `malloc()', unexpected behavior would likely result.
+
+ 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:
@@ -22105,7 +22108,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.
@@ -22125,14 +22128,57 @@ 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.
+ ---------- Footnotes ----------
+
+ (1) This is more common on MS-Windows systems, but can happen on
+Unix-like systems as well.
+
+
+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
@@ -22150,7 +22196,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:
@@ -22176,7 +22222,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.
@@ -22202,7 +22250,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
@@ -22231,7 +22279,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
@@ -22247,7 +22295,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
@@ -22469,7 +22517,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
@@ -22576,7 +22624,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
@@ -22629,7 +22677,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,
@@ -22660,7 +22708,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:
@@ -22681,7 +22729,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
@@ -22707,8 +22755,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.
@@ -22722,8 +22770,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
@@ -22758,8 +22806,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
@@ -22871,8 +22919,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
@@ -22882,8 +22930,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
@@ -22966,7 +23015,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
@@ -22993,7 +23042,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.
@@ -23060,7 +23109,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.
@@ -23086,7 +23135,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,'
@@ -23137,7 +23187,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
@@ -23311,7 +23361,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
@@ -23450,7 +23500,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
@@ -23467,7 +23517,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
@@ -23516,7 +23566,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
@@ -23552,7 +23602,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
@@ -32801,526 +32851,528 @@ 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-1427326
-Ref: Auto-set-Footnote-2427531
-Node: ARGC and ARGV427587
-Node: Arrays431438
-Node: Array Basics432943
-Node: Array Intro433769
-Node: Reference to Elements438086
-Node: Assigning Elements440356
-Node: Array Example440847
-Node: Scanning an Array442579
-Node: Controlling Scanning444893
-Ref: Controlling Scanning-Footnote-1449980
-Node: Delete450296
-Ref: Delete-Footnote-1453061
-Node: Numeric Array Subscripts453118
-Node: Uninitialized Subscripts455301
-Node: Multidimensional456928
-Node: Multiscanning460021
-Node: Arrays of Arrays461610
-Node: Functions466250
-Node: Built-in467069
-Node: Calling Built-in468147
-Node: Numeric Functions470135
-Ref: Numeric Functions-Footnote-1473967
-Ref: Numeric Functions-Footnote-2474324
-Ref: Numeric Functions-Footnote-3474372
-Node: String Functions474641
-Ref: String Functions-Footnote-1497561
-Ref: String Functions-Footnote-2497690
-Ref: String Functions-Footnote-3497938
-Node: Gory Details498025
-Ref: table-sub-escapes499704
-Ref: table-sub-posix-92501058
-Ref: table-sub-proposed502409
-Ref: table-posix-sub503763
-Ref: table-gensub-escapes505308
-Ref: Gory Details-Footnote-1506484
-Ref: Gory Details-Footnote-2506535
-Node: I/O Functions506686
-Ref: I/O Functions-Footnote-1513676
-Node: Time Functions513823
-Ref: Time Functions-Footnote-1524756
-Ref: Time Functions-Footnote-2524824
-Ref: Time Functions-Footnote-3524982
-Ref: Time Functions-Footnote-4525093
-Ref: Time Functions-Footnote-5525205
-Ref: Time Functions-Footnote-6525432
-Node: Bitwise Functions525698
-Ref: table-bitwise-ops526260
-Ref: Bitwise Functions-Footnote-1530481
-Node: Type Functions530665
-Node: I18N Functions531816
-Node: User-defined533443
-Node: Definition Syntax534247
-Ref: Definition Syntax-Footnote-1539161
-Node: Function Example539230
-Ref: Function Example-Footnote-1541879
-Node: Function Caveats541901
-Node: Calling A Function542419
-Node: Variable Scope543374
-Node: Pass By Value/Reference546337
-Node: Return Statement549845
-Node: Dynamic Typing552826
-Node: Indirect Calls553757
-Node: Library Functions563444
-Ref: Library Functions-Footnote-1566957
-Ref: Library Functions-Footnote-2567100
-Node: Library Names567271
-Ref: Library Names-Footnote-1570744
-Ref: Library Names-Footnote-2570964
-Node: General Functions571050
-Node: Strtonum Function572078
-Node: Assert Function575008
-Node: Round Function578334
-Node: Cliff Random Function579875
-Node: Ordinal Functions580891
-Ref: Ordinal Functions-Footnote-1583968
-Ref: Ordinal Functions-Footnote-2584220
-Node: Join Function584431
-Ref: Join Function-Footnote-1586202
-Node: Getlocaltime Function586402
-Node: Readfile Function590143
-Node: Data File Management591982
-Node: Filetrans Function592614
-Node: Rewind Function596683
-Node: File Checking598070
-Node: Empty Files599164
-Node: Ignoring Assigns601394
-Node: Getopt Function602948
-Ref: Getopt Function-Footnote-1614251
-Node: Passwd Functions614454
-Ref: Passwd Functions-Footnote-1623432
-Node: Group Functions623520
-Node: Walking Arrays631604
-Node: Sample Programs633740
-Node: Running Examples634414
-Node: Clones635142
-Node: Cut Program636366
-Node: Egrep Program646217
-Ref: Egrep Program-Footnote-1653990
-Node: Id Program654100
-Node: Split Program657716
-Ref: Split Program-Footnote-1661235
-Node: Tee Program661363
-Node: Uniq Program664166
-Node: Wc Program671595
-Ref: Wc Program-Footnote-1675861
-Ref: Wc Program-Footnote-2676061
-Node: Miscellaneous Programs676153
-Node: Dupword Program677341
-Node: Alarm Program679372
-Node: Translate Program684179
-Ref: Translate Program-Footnote-1688566
-Ref: Translate Program-Footnote-2688814
-Node: Labels Program688948
-Ref: Labels Program-Footnote-1692319
-Node: Word Sorting692403
-Node: History Sorting696287
-Node: Extract Program698126
-Ref: Extract Program-Footnote-1705629
-Node: Simple Sed705757
-Node: Igawk Program708819
-Ref: Igawk Program-Footnote-1723976
-Ref: Igawk Program-Footnote-2724177
-Node: Anagram Program724315
-Node: Signature Program727383
-Node: Advanced Features728483
-Node: Nondecimal Data730369
-Node: Array Sorting731952
-Node: Controlling Array Traversal732649
-Node: Array Sorting Functions740933
-Ref: Array Sorting Functions-Footnote-1744802
-Node: Two-way I/O744996
-Ref: Two-way I/O-Footnote-1750428
-Node: TCP/IP Networking750510
-Node: Profiling753354
-Node: Internationalization760857
-Node: I18N and L10N762282
-Node: Explaining gettext762968
-Ref: Explaining gettext-Footnote-1768036
-Ref: Explaining gettext-Footnote-2768220
-Node: Programmer i18n768385
-Node: Translator i18n772587
-Node: String Extraction773381
-Ref: String Extraction-Footnote-1774342
-Node: Printf Ordering774428
-Ref: Printf Ordering-Footnote-1777210
-Node: I18N Portability777274
-Ref: I18N Portability-Footnote-1779723
-Node: I18N Example779786
-Ref: I18N Example-Footnote-1782424
-Node: Gawk I18N782496
-Node: Debugger783117
-Node: Debugging784088
-Node: Debugging Concepts784521
-Node: Debugging Terms786377
-Node: Awk Debugging788974
-Node: Sample Debugging Session789866
-Node: Debugger Invocation790386
-Node: Finding The Bug791719
-Node: List of Debugger Commands798206
-Node: Breakpoint Control799540
-Node: Debugger Execution Control803204
-Node: Viewing And Changing Data806564
-Node: Execution Stack809920
-Node: Debugger Info811387
-Node: Miscellaneous Debugger Commands815369
-Node: Readline Support820545
-Node: Limitations821376
-Node: Arbitrary Precision Arithmetic823628
-Ref: Arbitrary Precision Arithmetic-Footnote-1825277
-Node: General Arithmetic825425
-Node: Floating Point Issues827145
-Node: String Conversion Precision828026
-Ref: String Conversion Precision-Footnote-1829731
-Node: Unexpected Results829840
-Node: POSIX Floating Point Problems831993
-Ref: POSIX Floating Point Problems-Footnote-1835818
-Node: Integer Programming835856
-Node: Floating-point Programming837595
-Ref: Floating-point Programming-Footnote-1843926
-Ref: Floating-point Programming-Footnote-2844196
-Node: Floating-point Representation844460
-Node: Floating-point Context845625
-Ref: table-ieee-formats846464
-Node: Rounding Mode847848
-Ref: table-rounding-modes848327
-Ref: Rounding Mode-Footnote-1851342
-Node: Gawk and MPFR851521
-Node: Arbitrary Precision Floats852776
-Ref: Arbitrary Precision Floats-Footnote-1855219
-Node: Setting Precision855535
-Ref: table-predefined-precision-strings856221
-Node: Setting Rounding Mode858366
-Ref: table-gawk-rounding-modes858770
-Node: Floating-point Constants859957
-Node: Changing Precision861386
-Ref: Changing Precision-Footnote-1862783
-Node: Exact Arithmetic862957
-Node: Arbitrary Precision Integers866095
-Ref: Arbitrary Precision Integers-Footnote-1869110
-Node: Dynamic Extensions869257
-Node: Extension Intro870715
-Node: Plugin License871980
-Node: Extension Mechanism Outline872665
-Ref: load-extension873082
-Ref: load-new-function874560
-Ref: call-new-function875555
-Node: Extension API Description877570
-Node: Extension API Functions Introduction878783
-Node: General Data Types883649
-Ref: General Data Types-Footnote-1889251
-Node: Requesting Values889550
-Ref: table-value-types-returned890281
-Node: Constructor Functions891235
-Node: Registration Functions894255
-Node: Extension Functions894940
-Node: Exit Callback Functions897166
-Node: Extension Version String898415
-Node: Input Parsers899065
-Node: Output Wrappers908822
-Node: Two-way processors913332
-Node: Printing Messages915540
-Ref: Printing Messages-Footnote-1916617
-Node: Updating `ERRNO'916769
-Node: Accessing Parameters917508
-Node: Symbol Table Access918738
-Node: Symbol table by name919250
-Node: Symbol table by cookie920997
-Ref: Symbol table by cookie-Footnote-1925127
-Node: Cached values925190
-Ref: Cached values-Footnote-1928639
-Node: Array Manipulation928730
-Ref: Array Manipulation-Footnote-1929828
-Node: Array Data Types929867
-Ref: Array Data Types-Footnote-1932570
-Node: Array Functions932662
-Node: Flattening Arrays936428
-Node: Creating Arrays943280
-Node: Extension API Variables948005
-Node: Extension Versioning948641
-Node: Extension API Informational Variables950542
-Node: Extension API Boilerplate951628
-Node: Finding Extensions955432
-Node: Extension Example955992
-Node: Internal File Description956722
-Node: Internal File Ops960813
-Ref: Internal File Ops-Footnote-1972322
-Node: Using Internal File Ops972462
-Ref: Using Internal File Ops-Footnote-1974815
-Node: Extension Samples975081
-Node: Extension Sample File Functions976605
-Node: Extension Sample Fnmatch985090
-Node: Extension Sample Fork986859
-Node: Extension Sample Inplace988072
-Node: Extension Sample Ord989850
-Node: Extension Sample Readdir990686
-Node: Extension Sample Revout992218
-Node: Extension Sample Rev2way992811
-Node: Extension Sample Read write array993501
-Node: Extension Sample Readfile995384
-Node: Extension Sample API Tests996202
-Node: Extension Sample Time996727
-Node: gawkextlib998091
-Node: Language History1000872
-Node: V7/SVR3.11002465
-Node: SVR41004785
-Node: POSIX1006227
-Node: BTL1007613
-Node: POSIX/GNU1008347
-Node: Feature History1013946
-Node: Common Extensions1026922
-Node: Ranges and Locales1028234
-Ref: Ranges and Locales-Footnote-11032851
-Ref: Ranges and Locales-Footnote-21032878
-Ref: Ranges and Locales-Footnote-31033112
-Node: Contributors1033333
-Node: Installation1038478
-Node: Gawk Distribution1039372
-Node: Getting1039856
-Node: Extracting1040682
-Node: Distribution contents1042374
-Node: Unix Installation1048079
-Node: Quick Installation1048696
-Node: Additional Configuration Options1051142
-Node: Configuration Philosophy1052878
-Node: Non-Unix Installation1055232
-Node: PC Installation1055690
-Node: PC Binary Installation1056989
-Node: PC Compiling1058837
-Node: PC Testing1061781
-Node: PC Using1062957
-Node: Cygwin1067125
-Node: MSYS1067934
-Node: VMS Installation1068448
-Node: VMS Compilation1069212
-Ref: VMS Compilation-Footnote-11070464
-Node: VMS Dynamic Extensions1070522
-Node: VMS Installation Details1071895
-Node: VMS Running1074146
-Node: VMS GNV1076980
-Node: VMS Old Gawk1077703
-Node: Bugs1078173
-Node: Other Versions1082091
-Node: Notes1088175
-Node: Compatibility Mode1088975
-Node: Additions1089758
-Node: Accessing The Source1090685
-Node: Adding Code1092125
-Node: New Ports1098170
-Node: Derived Files1102305
-Ref: Derived Files-Footnote-11107626
-Ref: Derived Files-Footnote-21107660
-Ref: Derived Files-Footnote-31108260
-Node: Future Extensions1108358
-Node: Implementation Limitations1108941
-Node: Extension Design1110193
-Node: Old Extension Problems1111347
-Ref: Old Extension Problems-Footnote-11112855
-Node: Extension New Mechanism Goals1112912
-Ref: Extension New Mechanism Goals-Footnote-11116277
-Node: Extension Other Design Decisions1116463
-Node: Extension Future Growth1118569
-Node: Old Extension Mechanism1119405
-Node: Basic Concepts1121145
-Node: Basic High Level1121826
-Ref: figure-general-flow1122097
-Ref: figure-process-flow1122696
-Ref: Basic High Level-Footnote-11125925
-Node: Basic Data Typing1126110
-Node: Glossary1129465
-Node: Copying1154927
-Node: GNU Free Documentation License1192484
-Node: Index1217621
+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-1427399
+Ref: Auto-set-Footnote-2427604
+Node: ARGC and ARGV427660
+Node: Arrays431511
+Node: Array Basics433016
+Node: Array Intro433842
+Node: Reference to Elements438159
+Node: Assigning Elements440429
+Node: Array Example440920
+Node: Scanning an Array442652
+Node: Controlling Scanning444966
+Ref: Controlling Scanning-Footnote-1450053
+Node: Delete450369
+Ref: Delete-Footnote-1453134
+Node: Numeric Array Subscripts453191
+Node: Uninitialized Subscripts455374
+Node: Multidimensional457001
+Node: Multiscanning460094
+Node: Arrays of Arrays461683
+Node: Functions466323
+Node: Built-in467142
+Node: Calling Built-in468220
+Node: Numeric Functions470208
+Ref: Numeric Functions-Footnote-1474040
+Ref: Numeric Functions-Footnote-2474397
+Ref: Numeric Functions-Footnote-3474445
+Node: String Functions474714
+Ref: String Functions-Footnote-1497634
+Ref: String Functions-Footnote-2497763
+Ref: String Functions-Footnote-3498011
+Node: Gory Details498098
+Ref: table-sub-escapes499777
+Ref: table-sub-posix-92501131
+Ref: table-sub-proposed502482
+Ref: table-posix-sub503836
+Ref: table-gensub-escapes505381
+Ref: Gory Details-Footnote-1506557
+Ref: Gory Details-Footnote-2506608
+Node: I/O Functions506759
+Ref: I/O Functions-Footnote-1513749
+Node: Time Functions513896
+Ref: Time Functions-Footnote-1524829
+Ref: Time Functions-Footnote-2524897
+Ref: Time Functions-Footnote-3525055
+Ref: Time Functions-Footnote-4525166
+Ref: Time Functions-Footnote-5525278
+Ref: Time Functions-Footnote-6525505
+Node: Bitwise Functions525771
+Ref: table-bitwise-ops526333
+Ref: Bitwise Functions-Footnote-1530554
+Node: Type Functions530738
+Node: I18N Functions531889
+Node: User-defined533516
+Node: Definition Syntax534320
+Ref: Definition Syntax-Footnote-1539234
+Node: Function Example539303
+Ref: Function Example-Footnote-1541952
+Node: Function Caveats541974
+Node: Calling A Function542492
+Node: Variable Scope543447
+Node: Pass By Value/Reference546410
+Node: Return Statement549918
+Node: Dynamic Typing552899
+Node: Indirect Calls553830
+Node: Library Functions563517
+Ref: Library Functions-Footnote-1567030
+Ref: Library Functions-Footnote-2567173
+Node: Library Names567344
+Ref: Library Names-Footnote-1570817
+Ref: Library Names-Footnote-2571037
+Node: General Functions571123
+Node: Strtonum Function572151
+Node: Assert Function575081
+Node: Round Function578407
+Node: Cliff Random Function579948
+Node: Ordinal Functions580964
+Ref: Ordinal Functions-Footnote-1584041
+Ref: Ordinal Functions-Footnote-2584293
+Node: Join Function584504
+Ref: Join Function-Footnote-1586275
+Node: Getlocaltime Function586475
+Node: Readfile Function590216
+Node: Data File Management592055
+Node: Filetrans Function592687
+Node: Rewind Function596756
+Node: File Checking598143
+Node: Empty Files599237
+Node: Ignoring Assigns601467
+Node: Getopt Function603021
+Ref: Getopt Function-Footnote-1614324
+Node: Passwd Functions614527
+Ref: Passwd Functions-Footnote-1623505
+Node: Group Functions623593
+Node: Walking Arrays631677
+Node: Sample Programs633813
+Node: Running Examples634487
+Node: Clones635215
+Node: Cut Program636439
+Node: Egrep Program646290
+Ref: Egrep Program-Footnote-1654063
+Node: Id Program654173
+Node: Split Program657789
+Ref: Split Program-Footnote-1661308
+Node: Tee Program661436
+Node: Uniq Program664239
+Node: Wc Program671668
+Ref: Wc Program-Footnote-1675934
+Ref: Wc Program-Footnote-2676134
+Node: Miscellaneous Programs676226
+Node: Dupword Program677414
+Node: Alarm Program679445
+Node: Translate Program684252
+Ref: Translate Program-Footnote-1688639
+Ref: Translate Program-Footnote-2688887
+Node: Labels Program689021
+Ref: Labels Program-Footnote-1692392
+Node: Word Sorting692476
+Node: History Sorting696360
+Node: Extract Program698199
+Ref: Extract Program-Footnote-1705702
+Node: Simple Sed705830
+Node: Igawk Program708892
+Ref: Igawk Program-Footnote-1724049
+Ref: Igawk Program-Footnote-2724250
+Node: Anagram Program724388
+Node: Signature Program727456
+Node: Advanced Features728556
+Node: Nondecimal Data730442
+Node: Array Sorting732025
+Node: Controlling Array Traversal732722
+Node: Array Sorting Functions741006
+Ref: Array Sorting Functions-Footnote-1744875
+Node: Two-way I/O745069
+Ref: Two-way I/O-Footnote-1750501
+Node: TCP/IP Networking750583
+Node: Profiling753427
+Node: Internationalization760930
+Node: I18N and L10N762355
+Node: Explaining gettext763041
+Ref: Explaining gettext-Footnote-1768109
+Ref: Explaining gettext-Footnote-2768293
+Node: Programmer i18n768458
+Node: Translator i18n772660
+Node: String Extraction773454
+Ref: String Extraction-Footnote-1774415
+Node: Printf Ordering774501
+Ref: Printf Ordering-Footnote-1777283
+Node: I18N Portability777347
+Ref: I18N Portability-Footnote-1779796
+Node: I18N Example779859
+Ref: I18N Example-Footnote-1782497
+Node: Gawk I18N782569
+Node: Debugger783190
+Node: Debugging784161
+Node: Debugging Concepts784594
+Node: Debugging Terms786450
+Node: Awk Debugging789047
+Node: Sample Debugging Session789939
+Node: Debugger Invocation790459
+Node: Finding The Bug791792
+Node: List of Debugger Commands798279
+Node: Breakpoint Control799613
+Node: Debugger Execution Control803277
+Node: Viewing And Changing Data806637
+Node: Execution Stack809993
+Node: Debugger Info811460
+Node: Miscellaneous Debugger Commands815442
+Node: Readline Support820618
+Node: Limitations821449
+Node: Arbitrary Precision Arithmetic823701
+Ref: Arbitrary Precision Arithmetic-Footnote-1825350
+Node: General Arithmetic825498
+Node: Floating Point Issues827218
+Node: String Conversion Precision828099
+Ref: String Conversion Precision-Footnote-1829804
+Node: Unexpected Results829913
+Node: POSIX Floating Point Problems832066
+Ref: POSIX Floating Point Problems-Footnote-1835891
+Node: Integer Programming835929
+Node: Floating-point Programming837668
+Ref: Floating-point Programming-Footnote-1843999
+Ref: Floating-point Programming-Footnote-2844269
+Node: Floating-point Representation844533
+Node: Floating-point Context845698
+Ref: table-ieee-formats846537
+Node: Rounding Mode847921
+Ref: table-rounding-modes848400
+Ref: Rounding Mode-Footnote-1851415
+Node: Gawk and MPFR851594
+Node: Arbitrary Precision Floats852849
+Ref: Arbitrary Precision Floats-Footnote-1855292
+Node: Setting Precision855608
+Ref: table-predefined-precision-strings856294
+Node: Setting Rounding Mode858439
+Ref: table-gawk-rounding-modes858843
+Node: Floating-point Constants860030
+Node: Changing Precision861459
+Ref: Changing Precision-Footnote-1862856
+Node: Exact Arithmetic863030
+Node: Arbitrary Precision Integers866168
+Ref: Arbitrary Precision Integers-Footnote-1869183
+Node: Dynamic Extensions869330
+Node: Extension Intro870788
+Node: Plugin License872053
+Node: Extension Mechanism Outline872738
+Ref: load-extension873155
+Ref: load-new-function874633
+Ref: call-new-function875628
+Node: Extension API Description877643
+Node: Extension API Functions Introduction878930
+Node: General Data Types883857
+Ref: General Data Types-Footnote-1889552
+Node: Requesting Values889851
+Ref: table-value-types-returned890588
+Node: Memory Allocation Functions891542
+Ref: Memory Allocation Functions-Footnote-1894288
+Node: Constructor Functions894384
+Node: Registration Functions896142
+Node: Extension Functions896827
+Node: Exit Callback Functions899129
+Node: Extension Version String900378
+Node: Input Parsers901028
+Node: Output Wrappers910785
+Node: Two-way processors915295
+Node: Printing Messages917503
+Ref: Printing Messages-Footnote-1918580
+Node: Updating `ERRNO'918732
+Node: Accessing Parameters919471
+Node: Symbol Table Access920701
+Node: Symbol table by name921215
+Node: Symbol table by cookie922964
+Ref: Symbol table by cookie-Footnote-1927096
+Node: Cached values927159
+Ref: Cached values-Footnote-1930649
+Node: Array Manipulation930740
+Ref: Array Manipulation-Footnote-1931838
+Node: Array Data Types931877
+Ref: Array Data Types-Footnote-1934580
+Node: Array Functions934672
+Node: Flattening Arrays938508
+Node: Creating Arrays945360
+Node: Extension API Variables950085
+Node: Extension Versioning950721
+Node: Extension API Informational Variables952622
+Node: Extension API Boilerplate953708
+Node: Finding Extensions957512
+Node: Extension Example958072
+Node: Internal File Description958802
+Node: Internal File Ops962893
+Ref: Internal File Ops-Footnote-1974402
+Node: Using Internal File Ops974542
+Ref: Using Internal File Ops-Footnote-1976895
+Node: Extension Samples977161
+Node: Extension Sample File Functions978685
+Node: Extension Sample Fnmatch987170
+Node: Extension Sample Fork988939
+Node: Extension Sample Inplace990152
+Node: Extension Sample Ord991930
+Node: Extension Sample Readdir992766
+Node: Extension Sample Revout994298
+Node: Extension Sample Rev2way994891
+Node: Extension Sample Read write array995581
+Node: Extension Sample Readfile997464
+Node: Extension Sample API Tests998282
+Node: Extension Sample Time998807
+Node: gawkextlib1000171
+Node: Language History1002952
+Node: V7/SVR3.11004545
+Node: SVR41006865
+Node: POSIX1008307
+Node: BTL1009693
+Node: POSIX/GNU1010427
+Node: Feature History1016026
+Node: Common Extensions1029002
+Node: Ranges and Locales1030314
+Ref: Ranges and Locales-Footnote-11034931
+Ref: Ranges and Locales-Footnote-21034958
+Ref: Ranges and Locales-Footnote-31035192
+Node: Contributors1035413
+Node: Installation1040558
+Node: Gawk Distribution1041452
+Node: Getting1041936
+Node: Extracting1042762
+Node: Distribution contents1044454
+Node: Unix Installation1050159
+Node: Quick Installation1050776
+Node: Additional Configuration Options1053222
+Node: Configuration Philosophy1054958
+Node: Non-Unix Installation1057312
+Node: PC Installation1057770
+Node: PC Binary Installation1059069
+Node: PC Compiling1060917
+Node: PC Testing1063861
+Node: PC Using1065037
+Node: Cygwin1069205
+Node: MSYS1070014
+Node: VMS Installation1070528
+Node: VMS Compilation1071292
+Ref: VMS Compilation-Footnote-11072544
+Node: VMS Dynamic Extensions1072602
+Node: VMS Installation Details1073975
+Node: VMS Running1076226
+Node: VMS GNV1079060
+Node: VMS Old Gawk1079783
+Node: Bugs1080253
+Node: Other Versions1084171
+Node: Notes1090255
+Node: Compatibility Mode1091055
+Node: Additions1091838
+Node: Accessing The Source1092765
+Node: Adding Code1094205
+Node: New Ports1100250
+Node: Derived Files1104385
+Ref: Derived Files-Footnote-11109706
+Ref: Derived Files-Footnote-21109740
+Ref: Derived Files-Footnote-31110340
+Node: Future Extensions1110438
+Node: Implementation Limitations1111021
+Node: Extension Design1112273
+Node: Old Extension Problems1113427
+Ref: Old Extension Problems-Footnote-11114935
+Node: Extension New Mechanism Goals1114992
+Ref: Extension New Mechanism Goals-Footnote-11118357
+Node: Extension Other Design Decisions1118543
+Node: Extension Future Growth1120649
+Node: Old Extension Mechanism1121485
+Node: Basic Concepts1123225
+Node: Basic High Level1123906
+Ref: figure-general-flow1124177
+Ref: figure-process-flow1124776
+Ref: Basic High Level-Footnote-11128005
+Node: Basic Data Typing1128190
+Node: Glossary1131545
+Node: Copying1157007
+Node: GNU Free Documentation License1194564
+Node: Index1219701

End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index f326bd1a..b9bf2170 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}.
@@ -29583,6 +29584,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}.
@@ -29638,6 +29640,9 @@ Symbol table access: retrieving a global variable, creating one,
or changing one.
@item
+Allocating, reallocating, and releasing memory.
+
+@item
Creating and releasing cached values; this provides an
efficient way to use values for multiple variables and
can be a big performance win.
@@ -29676,10 +29681,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
@@ -29709,8 +29712,9 @@ 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
-by @command{gawk} from then on.
+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
The API defines several simple @code{struct}s that map values as seen
@@ -29792,7 +29796,8 @@ 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.
@@ -29954,45 +29959,44 @@ 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 @command{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
-exit with a fatal error message. They should be used as if they were
+The API has to provide these functions because it is possible
+for an extension to be compiled and linked against a different
+version of the C library than was used for the @command{gawk}
+executable.@footnote{This is more common on MS-Windows systems, but
+can happen on Unix-like systems as well.} If @command{gawk} were
+to use its version of @code{free()} when the memory came from an
+unrelated version of @code{malloc()}, unexpected behavior would
+likely result.
+
+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.
@table @code
@@ -30004,7 +30008,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.
@@ -30028,11 +30032,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
@@ -30080,7 +30120,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.
@@ -30818,7 +30858,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.}
@@ -31015,7 +31055,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 cd110527..6054ed40 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}.
@@ -28724,6 +28725,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}.
@@ -28779,6 +28781,9 @@ Symbol table access: retrieving a global variable, creating one,
or changing one.
@item
+Allocating, reallocating, and releasing memory.
+
+@item
Creating and releasing cached values; this provides an
efficient way to use values for multiple variables and
can be a big performance win.
@@ -28817,10 +28822,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
@@ -28850,8 +28853,9 @@ 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
-by @command{gawk} from then on.
+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
The API defines several simple @code{struct}s that map values as seen
@@ -28933,7 +28937,8 @@ 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.
@@ -29095,45 +29100,44 @@ 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 @command{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
-exit with a fatal error message. They should be used as if they were
+The API has to provide these functions because it is possible
+for an extension to be compiled and linked against a different
+version of the C library than was used for the @command{gawk}
+executable.@footnote{This is more common on MS-Windows systems, but
+can happen on Unix-like systems as well.} If @command{gawk} were
+to use its version of @code{free()} when the memory came from an
+unrelated version of @code{malloc()}, unexpected behavior would
+likely result.
+
+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.
@table @code
@@ -29145,7 +29149,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.
@@ -29169,11 +29173,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
@@ -29221,7 +29261,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.
@@ -29959,7 +29999,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.}
@@ -30156,7 +30196,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)
diff --git a/helpers/ChangeLog b/helpers/ChangeLog
index 91d43464..14affebc 100644
--- a/helpers/ChangeLog
+++ b/helpers/ChangeLog
@@ -1,3 +1,7 @@
+2014-03-08 Arnold D. Robbins <arnold@skeeve.com>
+
+ * quoteconvert2.sh, tryfmt.c, scanfmt.c: New files.
+
2013-12-21 Arnold D. Robbins <arnold@skeeve.com>
* testdfa.c: Fix some bugs and compiler warnings.
diff --git a/helpers/quoteconvert2.sh b/helpers/quoteconvert2.sh
new file mode 100755
index 00000000..e33a4d05
--- /dev/null
+++ b/helpers/quoteconvert2.sh
@@ -0,0 +1,49 @@
+#!/bin/sh
+
+# quoteconvert2.sh --- test locale dependent output of numbers
+# Michal Jaegermann, michal@harddata.com, 2014/Mar/1
+
+#AWK="../gawk"
+SCRIPT=`basename $0`
+
+if [ "$AWK" = "" ]
+then
+ echo $0: You must set AWK >&2
+ exit 1
+fi
+
+# The last entry on this list represents "a locale with a typo".
+
+llist="
+C
+en_US
+en_US.utf8
+de_DE
+de_DE.utf8
+fr_FR
+fr_FR.utf8
+pt_PT
+pt_PT.utf8
+pt_BR
+pt_BR.utf8
+ru_RU
+ru_RU.utf8
+pl_PX
+"
+
+error=0
+for lc in $llist ; do
+ wanted=`LC_ALL=$lc locale -c LC_NUMERIC 2>/dev/null | \
+ $AWK 'NR == 2 { decimal_point = $0 }
+ NR == 3 { thousands_sep = $0 }
+ END { printf("123%s456%s789%s15\n",
+ thousands_sep, thousands_sep, decimal_point)}'`
+ got=`LC_ALL=$lc $AWK "BEGIN {printf(\"%'.2f\n\",123456789.15)}"`
+ if [ "$wanted" != "$got" ] ; then
+ echo "$lc - unexpected output $got instead of $wanted"
+ error=1
+ fi
+done
+
+[ "$error" = 0 ] && echo ok || echo bummer
+exit $error
diff --git a/helpers/scanfmt.c b/helpers/scanfmt.c
new file mode 100644
index 00000000..2d7bd73a
--- /dev/null
+++ b/helpers/scanfmt.c
@@ -0,0 +1,22 @@
+/*
+ * Test out ' flag in different locales.
+ * Michal Jaegermann
+ * March, 2014
+ */
+
+#include <stdio.h>
+#include <locale.h>
+#include <stdlib.h>
+int
+main(int argc, char **argv)
+{
+ double t;
+
+ if (argc == 1)
+ return 1;
+
+ setlocale(LC_ALL, getenv("LC_ALL"));
+ sscanf(argv[1], "%lf", &t);
+ printf("%.2f\n", t);
+ return 0;
+}
diff --git a/helpers/tryfmt.c b/helpers/tryfmt.c
new file mode 100644
index 00000000..8166d3f1
--- /dev/null
+++ b/helpers/tryfmt.c
@@ -0,0 +1,23 @@
+/*
+ * Test out ' flag in different locales.
+ * Michal Jaegermann
+ * March, 2014
+ */
+
+#include <locale.h>
+#include <stdio.h>
+#include <stdlib.h>
+int
+main(int argc, char **argv)
+{
+ const char *fmt;
+ if (argc == 1)
+ fmt = "%'.2f";
+ else
+ fmt = argv[1];
+
+ setlocale(LC_ALL, getenv("LC_ALL"));
+ printf(fmt, 12456789.01);
+ printf("\n");
+ return 0;
+}
generated by cgit v1.2.3 (git 2.25.1) at 2025-05-06 01:04:37 +0000