Doc that API get_mpfr and get_mpz are obsolete.

8 files changed, 207 insertions, 175 deletions

diff --git a/ChangeLog b/ChangeLog
index 24e3186c..bcad5f82 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,6 +3,10 @@
 	* awkgram.c, command.c: Regenerated with Bison 3.7.
 	* NEWS: Updated.
 
+	Unrelated:
+
+	* gawkapi.h (api_get_mpfr, api_get_mpz): Mark as obsolete.
+
 2020-07-22         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* Makefile.in: Regenerated.
diff --git a/doc/ChangeLog b/doc/ChangeLog
index ba4a3886..f40c6b8b 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,9 @@
+2020-07-26         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in: Document that get_mpfr and get_mpz are obsolete
+	and revise doc on handling MPFR and GMP values from an
+	extension function.
+
 2020-07-15         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Document how to handle MPFR and GMP values
diff --git a/doc/gawk.info b/doc/gawk.info
index 5b731a68..49825017 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -25076,7 +25076,13 @@ value:
      macro.
 
    Two additional functions allocate MPFR and GMP objects for use by
-extension functions that need to create and then return such values:
+extension functions that need to create and then return such values.
+
+     NOTE: These functions are obsolete.  Extension functions that need
+     local MPFR and GMP values should simply allocate them on the stack
+     and clear them, as any other code would.
+
+The functions are:
 
 'void *get_mpfr_ptr();'
      Allocate and initialize an MPFR object and return a pointer to it.
@@ -25097,6 +25103,9 @@ included from '<mpfr.h>').  The actual return values are of types
 values appropriately before assigning the results to variables of the
 correct types.
 
+   The memory allocated by these functions should be freed with
+'gawk_free()'.
+
    ---------- Footnotes ----------
 
    (1) This is more common on MS-Windows systems, but it can happen on
@@ -25196,22 +25205,18 @@ values, the same way that you would pass an 'int' or a 'double' by
 value.  There is no way to "transfer ownership" of MPFR and GMP objects.
 Thus, code in an extension should look like this:
 
-     part1 = get_mpz_ptr();                  have gawk allocate a GMP value
-     part2 = get_mpz_ptr();
-     answer = get_mpz_ptr();
+     mpz_t part1, part2, answer;             declare local values
 
      mpz_set_si(part1, 21);                  do some computations
      mpz_set_si(part2, 21);
      mpz_add(answer, part1, part2);
      ...
-     // assume that result is a parameter of type (awk_value_t *).
+     /* assume that result is a parameter of type (awk_value_t *). */
      make_number_mpz(answer, & result);      set it with final GMP value
 
      mpz_clear(part1);                       release intermediate values
-     gawk_free(part1);                       and free memory
-
      mpz_clear(part2);
-     gawk_free(part2);
+     mpz_clear(answer);
 
      return result;
 
@@ -37845,143 +37850,143 @@ Ref: table-api-std-headers1001730
 Node: General Data Types1005943
 Ref: General Data Types-Footnote-11014573
 Node: Memory Allocation Functions1014872
-Ref: Memory Allocation Functions-Footnote-11019082
-Node: Constructor Functions1019181
-Node: API Ownership of MPFR and GMP Values1022647
-Node: Registration Functions1024085
-Node: Extension Functions1024785
-Node: Exit Callback Functions1030107
-Node: Extension Version String1031357
-Node: Input Parsers1032020
-Node: Output Wrappers1044741
-Node: Two-way processors1049253
-Node: Printing Messages1051518
-Ref: Printing Messages-Footnote-11052689
-Node: Updating ERRNO1052842
-Node: Requesting Values1053581
-Ref: table-value-types-returned1054318
-Node: Accessing Parameters1055254
-Node: Symbol Table Access1056491
-Node: Symbol table by name1057003
-Ref: Symbol table by name-Footnote-11060027
-Node: Symbol table by cookie1060155
-Ref: Symbol table by cookie-Footnote-11064340
-Node: Cached values1064404
-Ref: Cached values-Footnote-11067940
-Node: Array Manipulation1068093
-Ref: Array Manipulation-Footnote-11069184
-Node: Array Data Types1069221
-Ref: Array Data Types-Footnote-11071879
-Node: Array Functions1071971
-Node: Flattening Arrays1076469
-Node: Creating Arrays1083445
-Node: Redirection API1088212
-Node: Extension API Variables1091045
-Node: Extension Versioning1091756
-Ref: gawk-api-version1092185
-Node: Extension GMP/MPFR Versioning1093916
-Node: Extension API Informational Variables1095544
-Node: Extension API Boilerplate1096617
-Node: Changes from API V11100591
-Node: Finding Extensions1102163
-Node: Extension Example1102722
-Node: Internal File Description1103520
-Node: Internal File Ops1107600
-Ref: Internal File Ops-Footnote-11118950
-Node: Using Internal File Ops1119090
-Ref: Using Internal File Ops-Footnote-11121473
-Node: Extension Samples1121747
-Node: Extension Sample File Functions1123276
-Node: Extension Sample Fnmatch1130925
-Node: Extension Sample Fork1132412
-Node: Extension Sample Inplace1133630
-Node: Extension Sample Ord1137255
-Node: Extension Sample Readdir1138091
-Ref: table-readdir-file-types1138980
-Node: Extension Sample Revout1140047
-Node: Extension Sample Rev2way1140636
-Node: Extension Sample Read write array1141376
-Node: Extension Sample Readfile1143318
-Node: Extension Sample Time1144413
-Node: Extension Sample API Tests1146165
-Node: gawkextlib1146657
-Node: Extension summary1149575
-Node: Extension Exercises1153277
-Node: Language History1154519
-Node: V7/SVR3.11156175
-Node: SVR41158327
-Node: POSIX1159761
-Node: BTL1161142
-Node: POSIX/GNU1161871
-Node: Feature History1167649
-Node: Common Extensions1183968
-Node: Ranges and Locales1185251
-Ref: Ranges and Locales-Footnote-11189867
-Ref: Ranges and Locales-Footnote-21189894
-Ref: Ranges and Locales-Footnote-31190129
-Node: Contributors1190352
-Node: History summary1196349
-Node: Installation1197729
-Node: Gawk Distribution1198673
-Node: Getting1199157
-Node: Extracting1200120
-Node: Distribution contents1201758
-Node: Unix Installation1208238
-Node: Quick Installation1208920
-Node: Shell Startup Files1211334
-Node: Additional Configuration Options1212423
-Node: Configuration Philosophy1214738
-Node: Non-Unix Installation1217107
-Node: PC Installation1217567
-Node: PC Binary Installation1218405
-Node: PC Compiling1218840
-Node: PC Using1219957
-Node: Cygwin1223510
-Node: MSYS1224734
-Node: VMS Installation1225336
-Node: VMS Compilation1226127
-Ref: VMS Compilation-Footnote-11227356
-Node: VMS Dynamic Extensions1227414
-Node: VMS Installation Details1229099
-Node: VMS Running1231352
-Node: VMS GNV1235631
-Node: VMS Old Gawk1236366
-Node: Bugs1236837
-Node: Bug address1237500
-Node: Usenet1240482
-Node: Maintainers1241486
-Node: Other Versions1242671
-Node: Installation summary1249759
-Node: Notes1250968
-Node: Compatibility Mode1251762
-Node: Additions1252544
-Node: Accessing The Source1253469
-Node: Adding Code1254906
-Node: New Ports1261125
-Node: Derived Files1265500
-Ref: Derived Files-Footnote-11271160
-Ref: Derived Files-Footnote-21271195
-Ref: Derived Files-Footnote-31271793
-Node: Future Extensions1271907
-Node: Implementation Limitations1272565
-Node: Extension Design1273775
-Node: Old Extension Problems1274919
-Ref: Old Extension Problems-Footnote-11276437
-Node: Extension New Mechanism Goals1276494
-Ref: Extension New Mechanism Goals-Footnote-11279858
-Node: Extension Other Design Decisions1280047
-Node: Extension Future Growth1282160
-Node: Notes summary1282766
-Node: Basic Concepts1283924
-Node: Basic High Level1284605
-Ref: figure-general-flow1284887
-Ref: figure-process-flow1285572
-Ref: Basic High Level-Footnote-11288873
-Node: Basic Data Typing1289058
-Node: Glossary1292386
-Node: Copying1324271
-Node: GNU Free Documentation License1361814
-Node: Index1386934
+Ref: Memory Allocation Functions-Footnote-11019373
+Node: Constructor Functions1019472
+Node: API Ownership of MPFR and GMP Values1022938
+Node: Registration Functions1024251
+Node: Extension Functions1024951
+Node: Exit Callback Functions1030273
+Node: Extension Version String1031523
+Node: Input Parsers1032186
+Node: Output Wrappers1044907
+Node: Two-way processors1049419
+Node: Printing Messages1051684
+Ref: Printing Messages-Footnote-11052855
+Node: Updating ERRNO1053008
+Node: Requesting Values1053747
+Ref: table-value-types-returned1054484
+Node: Accessing Parameters1055420
+Node: Symbol Table Access1056657
+Node: Symbol table by name1057169
+Ref: Symbol table by name-Footnote-11060193
+Node: Symbol table by cookie1060321
+Ref: Symbol table by cookie-Footnote-11064506
+Node: Cached values1064570
+Ref: Cached values-Footnote-11068106
+Node: Array Manipulation1068259
+Ref: Array Manipulation-Footnote-11069350
+Node: Array Data Types1069387
+Ref: Array Data Types-Footnote-11072045
+Node: Array Functions1072137
+Node: Flattening Arrays1076635
+Node: Creating Arrays1083611
+Node: Redirection API1088378
+Node: Extension API Variables1091211
+Node: Extension Versioning1091922
+Ref: gawk-api-version1092351
+Node: Extension GMP/MPFR Versioning1094082
+Node: Extension API Informational Variables1095710
+Node: Extension API Boilerplate1096783
+Node: Changes from API V11100757
+Node: Finding Extensions1102329
+Node: Extension Example1102888
+Node: Internal File Description1103686
+Node: Internal File Ops1107766
+Ref: Internal File Ops-Footnote-11119116
+Node: Using Internal File Ops1119256
+Ref: Using Internal File Ops-Footnote-11121639
+Node: Extension Samples1121913
+Node: Extension Sample File Functions1123442
+Node: Extension Sample Fnmatch1131091
+Node: Extension Sample Fork1132578
+Node: Extension Sample Inplace1133796
+Node: Extension Sample Ord1137421
+Node: Extension Sample Readdir1138257
+Ref: table-readdir-file-types1139146
+Node: Extension Sample Revout1140213
+Node: Extension Sample Rev2way1140802
+Node: Extension Sample Read write array1141542
+Node: Extension Sample Readfile1143484
+Node: Extension Sample Time1144579
+Node: Extension Sample API Tests1146331
+Node: gawkextlib1146823
+Node: Extension summary1149741
+Node: Extension Exercises1153443
+Node: Language History1154685
+Node: V7/SVR3.11156341
+Node: SVR41158493
+Node: POSIX1159927
+Node: BTL1161308
+Node: POSIX/GNU1162037
+Node: Feature History1167815
+Node: Common Extensions1184134
+Node: Ranges and Locales1185417
+Ref: Ranges and Locales-Footnote-11190033
+Ref: Ranges and Locales-Footnote-21190060
+Ref: Ranges and Locales-Footnote-31190295
+Node: Contributors1190518
+Node: History summary1196515
+Node: Installation1197895
+Node: Gawk Distribution1198839
+Node: Getting1199323
+Node: Extracting1200286
+Node: Distribution contents1201924
+Node: Unix Installation1208404
+Node: Quick Installation1209086
+Node: Shell Startup Files1211500
+Node: Additional Configuration Options1212589
+Node: Configuration Philosophy1214904
+Node: Non-Unix Installation1217273
+Node: PC Installation1217733
+Node: PC Binary Installation1218571
+Node: PC Compiling1219006
+Node: PC Using1220123
+Node: Cygwin1223676
+Node: MSYS1224900
+Node: VMS Installation1225502
+Node: VMS Compilation1226293
+Ref: VMS Compilation-Footnote-11227522
+Node: VMS Dynamic Extensions1227580
+Node: VMS Installation Details1229265
+Node: VMS Running1231518
+Node: VMS GNV1235797
+Node: VMS Old Gawk1236532
+Node: Bugs1237003
+Node: Bug address1237666
+Node: Usenet1240648
+Node: Maintainers1241652
+Node: Other Versions1242837
+Node: Installation summary1249925
+Node: Notes1251134
+Node: Compatibility Mode1251928
+Node: Additions1252710
+Node: Accessing The Source1253635
+Node: Adding Code1255072
+Node: New Ports1261291
+Node: Derived Files1265666
+Ref: Derived Files-Footnote-11271326
+Ref: Derived Files-Footnote-21271361
+Ref: Derived Files-Footnote-31271959
+Node: Future Extensions1272073
+Node: Implementation Limitations1272731
+Node: Extension Design1273941
+Node: Old Extension Problems1275085
+Ref: Old Extension Problems-Footnote-11276603
+Node: Extension New Mechanism Goals1276660
+Ref: Extension New Mechanism Goals-Footnote-11280024
+Node: Extension Other Design Decisions1280213
+Node: Extension Future Growth1282326
+Node: Notes summary1282932
+Node: Basic Concepts1284090
+Node: Basic High Level1284771
+Ref: figure-general-flow1285053
+Ref: figure-process-flow1285738
+Ref: Basic High Level-Footnote-11289039
+Node: Basic Data Typing1289224
+Node: Glossary1292552
+Node: Copying1324437
+Node: GNU Free Documentation License1361980
+Node: Index1387100
 
 End Tag Table
 
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 86f334c1..6d7694a2 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -34764,7 +34764,16 @@ The arguments are the same as for the @code{emalloc()} macro.
 
 Two additional functions allocate MPFR and GMP objects for use
 by extension functions that need to create and then return such
-values:
+values.
+
+@quotation NOTE
+These functions are obsolete. Extension functions that need local MPFR
+and GMP values should simply allocate them on the stack and clear them,
+as any other code would.
+@end quotation
+
+@noindent
+The functions are:
 
 @table @code
 @item void *get_mpfr_ptr();
@@ -34787,6 +34796,9 @@ types @code{mpfr_ptr} and @code{mpz_ptr} respectively, and you should cast
 the return values appropriately before assigning the results to variables
 of the correct types.
 
+The memory allocated by these functions should be freed with
+@code{gawk_free()}.
+
 @node Constructor Functions
 @subsection Constructor Functions
 
@@ -34881,22 +34893,18 @@ way to ``transfer ownership'' of MPFR and GMP objects.  Thus, code in
 an extension should look like this:
 
 @example
-part1 = get_mpz_ptr();                  @ii{have} gawk @ii{allocate a GMP value}
-part2 = get_mpz_ptr();
-answer = get_mpz_ptr();
+mpz_t part1, part2, answer;             @ii{declare local values}
 
 mpz_set_si(part1, 21);                  @ii{do some computations}
 mpz_set_si(part2, 21);
 mpz_add(answer, part1, part2);
 @dots{}
-// assume that result is a parameter of type (awk_value_t *).
+/* assume that result is a parameter of type (awk_value_t *). */
 make_number_mpz(answer, & result);      @ii{set it with final GMP value}
 
 mpz_clear(part1);                       @ii{release intermediate values}
-gawk_free(part1);                       @ii{and free memory}
-
 mpz_clear(part2);
-gawk_free(part2);
+mpz_clear(answer);
 
 return result;
 @end example
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index b06226df..e41fe930 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -33735,7 +33735,16 @@ The arguments are the same as for the @code{emalloc()} macro.
 
 Two additional functions allocate MPFR and GMP objects for use
 by extension functions that need to create and then return such
-values:
+values.
+
+@quotation NOTE
+These functions are obsolete. Extension functions that need local MPFR
+and GMP values should simply allocate them on the stack and clear them,
+as any other code would.
+@end quotation
+
+@noindent
+The functions are:
 
 @table @code
 @item void *get_mpfr_ptr();
@@ -33758,6 +33767,9 @@ types @code{mpfr_ptr} and @code{mpz_ptr} respectively, and you should cast
 the return values appropriately before assigning the results to variables
 of the correct types.
 
+The memory allocated by these functions should be freed with
+@code{gawk_free()}.
+
 @node Constructor Functions
 @subsection Constructor Functions
 
@@ -33852,22 +33864,18 @@ way to ``transfer ownership'' of MPFR and GMP objects.  Thus, code in
 an extension should look like this:
 
 @example
-part1 = get_mpz_ptr();                  @ii{have} gawk @ii{allocate a GMP value}
-part2 = get_mpz_ptr();
-answer = get_mpz_ptr();
+mpz_t part1, part2, answer;             @ii{declare local values}
 
 mpz_set_si(part1, 21);                  @ii{do some computations}
 mpz_set_si(part2, 21);
 mpz_add(answer, part1, part2);
 @dots{}
-// assume that result is a parameter of type (awk_value_t *).
+/* assume that result is a parameter of type (awk_value_t *). */
 make_number_mpz(answer, & result);      @ii{set it with final GMP value}
 
 mpz_clear(part1);                       @ii{release intermediate values}
-gawk_free(part1);                       @ii{and free memory}
-
 mpz_clear(part2);
-gawk_free(part2);
+mpz_clear(answer);
 
 return result;
 @end example
diff --git a/extension/ChangeLog b/extension/ChangeLog
index 7b924399..1a018897 100644
--- a/extension/ChangeLog
+++ b/extension/ChangeLog
@@ -1,3 +1,8 @@
+2020-07-26         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* intdiv.c (do_intdiv): Change quotient and remainder to
+	local variables. No need to allocate/free them via the API.
+
 2020-07-22         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* configure.ac: Use parent directory's m4 and build-aux.
diff --git a/extension/intdiv.c b/extension/intdiv.c
index 34b19a02..94c970ed 100644
--- a/extension/intdiv.c
+++ b/extension/intdiv.c
@@ -191,7 +191,7 @@ do_intdiv(int nargs, awk_value_t *result, struct awk_ext_func *unused)
 		/* extended precision */
 		mpz_ptr numer, denom;
 		mpz_t numer_tmp, denom_tmp;
-		mpz_ptr quotient, remainder;
+		mpz_t quotient, remainder;
 
 		/* convert numerator and denominator to integer */
 		if (!(numer = mpz_conv(&nv, numer_tmp))) {
@@ -213,9 +213,8 @@ do_intdiv(int nargs, awk_value_t *result, struct awk_ext_func *unused)
 			return make_number(-1, result);
 		}
 
-		/* ask gawk to allocate return values for us */
-		quotient = get_mpz_ptr();
-		remainder = get_mpz_ptr();
+		mpz_init(quotient);
+		mpz_init(remainder);
 
 		/* do the division */
 		mpz_tdiv_qr(quotient, remainder, numer, denom);
@@ -223,12 +222,8 @@ do_intdiv(int nargs, awk_value_t *result, struct awk_ext_func *unused)
 		array_set_mpz(array, "quotient", 8, quotient);
 		array_set_mpz(array, "remainder", 9, remainder);
 
-		/* values were copied, so release out local ones */
 		mpz_clear(quotient);
-		gawk_free(quotient);
-
 		mpz_clear(remainder);
-		gawk_free(remainder);
 
 		/* release temporary variables */
 		if (numer == numer_tmp)
diff --git a/gawkapi.h b/gawkapi.h
index 6bf1c40d..c0d90621 100644
--- a/gawkapi.h
+++ b/gawkapi.h
@@ -782,16 +782,16 @@ typedef struct gawk_api {
 	void (*api_free)(void *ptr);
 
 	/*
-	 * A function that returns mpfr data should call this function
-	 * to allocate and initialize an mpfr_ptr for use in an
-	 * awk_value_t structure that will be handed to gawk.
+	 * Obsolete function, should not be used. It remains only
+	 * for binary compatibility.  Any value it returns should be
+	 * freed via api_free.
 	 */
 	void *(*api_get_mpfr)(awk_ext_id_t id);
 
 	/*
-	 * A function that returns mpz data should call this function
-	 * to allocate and initialize an mpz_ptr for use in an
-	 * awk_value_t structure that will be handed to gawk.
+	 * Obsolete function, should not be used. It remains only
+	 * for binary compatibility.  Any value it returns should be
+	 * freed via api_free.
 	 */
 	void *(*api_get_mpz)(awk_ext_id_t id);
 
@@ -935,6 +935,7 @@ typedef struct gawk_api {
 #define get_file(name, namelen, filetype, fd, ibuf, obuf) \
 	(api->api_get_file(ext_id, name, namelen, filetype, fd, ibuf, obuf))
 
+/* These two are obsolete and should not be used. */
 #define get_mpfr_ptr() (api->api_get_mpfr(ext_id))
 #define get_mpz_ptr() (api->api_get_mpz(ext_id))