Update doc on API memory allocation, add to NEWS.

5 files changed, 199 insertions, 146 deletions

diff --git a/NEWS b/NEWS
index eb7651b0..50b88a97 100644
--- a/NEWS
+++ b/NEWS
@@ -36,6 +36,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 085ba317..99b81306 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+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,
diff --git a/doc/gawk.info b/doc/gawk.info
index 799d1c11..9a569829 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -21783,6 +21783,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.
@@ -21838,8 +21840,8 @@ 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 calling the api-provided function pointers `api_malloc()',
-     `api_calloc()' or `api_realloc()' and is managed by `gawk' from
+     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
@@ -21913,7 +21915,7 @@ that use them.
      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 calling the
-     api-provided function pointers `api_malloc()', `api_calloc()', or
+     API-provided function pointers `api_malloc()', `api_calloc()', or
      `api_realloc()'!*
 
      As mentioned earlier, strings are maintained using the current
@@ -22058,7 +22060,7 @@ File: gawk.info,  Node: Memory Allocation Functions,  Next: Constructor Function
 ---------------------------------------------------------
 
 The API provides a number of "memory allocation" functions for
-allocating memory that can be passed to gawk, as well as a number of
+allocating memory that can be passed to `gawk', as well as a number of
 convenience macros.
 
 `void *gawk_malloc(size_t size);'
@@ -22078,8 +22080,14 @@ convenience macros.
      allocated with `gawk_malloc()', `gawk_calloc()' or
      `gawk_realloc()'.
 
+   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
+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.
@@ -22115,6 +22123,11 @@ not return a value.
      `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
 
@@ -33226,130 +33239,131 @@ 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
+Node: General Data Types883465
+Ref: General Data Types-Footnote-1889160
+Node: Requesting Values889459
+Ref: table-value-types-returned890196
+Node: Memory Allocation Functions891150
+Ref: Memory Allocation Functions-Footnote-1893896
+Node: Constructor Functions893992
+Node: Registration Functions895750
+Node: Extension Functions896435
+Node: Exit Callback Functions898737
+Node: Extension Version String899986
+Node: Input Parsers900636
+Node: Output Wrappers910393
+Node: Two-way processors914903
+Node: Printing Messages917111
+Ref: Printing Messages-Footnote-1918188
+Node: Updating `ERRNO'918340
+Node: Accessing Parameters919079
+Node: Symbol Table Access920309
+Node: Symbol table by name920823
+Node: Symbol table by cookie922572
+Ref: Symbol table by cookie-Footnote-1926704
+Node: Cached values926767
+Ref: Cached values-Footnote-1930257
+Node: Array Manipulation930348
+Ref: Array Manipulation-Footnote-1931446
+Node: Array Data Types931485
+Ref: Array Data Types-Footnote-1934188
+Node: Array Functions934280
+Node: Flattening Arrays938116
+Node: Creating Arrays944968
+Node: Extension API Variables949693
+Node: Extension Versioning950329
+Node: Extension API Informational Variables952230
+Node: Extension API Boilerplate953316
+Node: Finding Extensions957120
+Node: Extension Example957680
+Node: Internal File Description958410
+Node: Internal File Ops962501
+Ref: Internal File Ops-Footnote-1974010
+Node: Using Internal File Ops974150
+Ref: Using Internal File Ops-Footnote-1976503
+Node: Extension Samples976769
+Node: Extension Sample File Functions978293
+Node: Extension Sample Fnmatch986778
+Node: Extension Sample Fork988547
+Node: Extension Sample Inplace989760
+Node: Extension Sample Ord991538
+Node: Extension Sample Readdir992374
+Node: Extension Sample Revout993906
+Node: Extension Sample Rev2way994499
+Node: Extension Sample Read write array995189
+Node: Extension Sample Readfile997072
+Node: Extension Sample API Tests997890
+Node: Extension Sample Time998415
+Node: gawkextlib999779
+Node: Language History1002560
+Node: V7/SVR3.11004153
+Node: SVR41006473
+Node: POSIX1007915
+Node: BTL1009301
+Node: POSIX/GNU1010035
+Node: Feature History1015634
+Node: Common Extensions1028610
+Node: Ranges and Locales1029922
+Ref: Ranges and Locales-Footnote-11034539
+Ref: Ranges and Locales-Footnote-21034566
+Ref: Ranges and Locales-Footnote-31034800
+Node: Contributors1035021
+Node: Installation1040166
+Node: Gawk Distribution1041060
+Node: Getting1041544
+Node: Extracting1042370
+Node: Distribution contents1044062
+Node: Unix Installation1049767
+Node: Quick Installation1050384
+Node: Additional Configuration Options1052830
+Node: Configuration Philosophy1054566
+Node: Non-Unix Installation1056920
+Node: PC Installation1057378
+Node: PC Binary Installation1058677
+Node: PC Compiling1060525
+Node: PC Testing1063469
+Node: PC Using1064645
+Node: Cygwin1068813
+Node: MSYS1069622
+Node: VMS Installation1070136
+Node: VMS Compilation1070900
+Ref: VMS Compilation-Footnote-11072152
+Node: VMS Dynamic Extensions1072210
+Node: VMS Installation Details1073583
+Node: VMS Running1075834
+Node: VMS GNV1078668
+Node: VMS Old Gawk1079391
+Node: Bugs1079861
+Node: Other Versions1083779
+Node: Notes1089863
+Node: Compatibility Mode1090663
+Node: Additions1091446
+Node: Accessing The Source1092373
+Node: Adding Code1093813
+Node: New Ports1099858
+Node: Derived Files1103993
+Ref: Derived Files-Footnote-11109314
+Ref: Derived Files-Footnote-21109348
+Ref: Derived Files-Footnote-31109948
+Node: Future Extensions1110046
+Node: Implementation Limitations1110629
+Node: Extension Design1111881
+Node: Old Extension Problems1113035
+Ref: Old Extension Problems-Footnote-11114543
+Node: Extension New Mechanism Goals1114600
+Ref: Extension New Mechanism Goals-Footnote-11117965
+Node: Extension Other Design Decisions1118151
+Node: Extension Future Growth1120257
+Node: Old Extension Mechanism1121093
+Node: Basic Concepts1122833
+Node: Basic High Level1123514
+Ref: figure-general-flow1123785
+Ref: figure-process-flow1124384
+Ref: Basic High Level-Footnote-11127613
+Node: Basic Data Typing1127798
+Node: Glossary1131153
+Node: Copying1156615
+Node: GNU Free Documentation License1194172
+Node: Index1219309
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index f0c7d6e6..09beef82 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -29632,6 +29632,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.
@@ -29701,8 +29704,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 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.
+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
@@ -29784,7 +29788,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 calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!}
+@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.
@@ -29950,7 +29955,8 @@ value type, as appropriate.  This behavior is summarized in
 @subsection Memory Allocation Functions and Convenience Macros
 
 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.
+allocating memory that can be passed to @command{gawk}, as well as a number of
+convenience macros.
 
 @table @code
 @item void *gawk_malloc(size_t size);
@@ -29970,10 +29976,19 @@ 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 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
+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
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 3720a0dc..6d7c5055 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -28773,6 +28773,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.
@@ -28842,8 +28845,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 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.
+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
@@ -28925,7 +28929,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 calling the api-provided function pointers @code{api_malloc()}, @code{api_calloc()}, or @code{api_realloc()}!}
+@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.
@@ -29091,7 +29096,8 @@ value type, as appropriate.  This behavior is summarized in
 @subsection Memory Allocation Functions and Convenience Macros
 
 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.
+allocating memory that can be passed to @command{gawk}, as well as a number of
+convenience macros.
 
 @table @code
 @item void *gawk_malloc(size_t size);
@@ -29111,10 +29117,19 @@ 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 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
+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