1 files changed, 55 insertions, 5 deletions
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 8cd1efea..b06226df 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -930,6 +930,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.
 * Memory Allocation Functions::         Functions for allocating memory.
+* API Ownership of MPFR and GMP Values:: Managing MPFR and GMP Values.
 * Constructor Functions::               Functions for creating values.
 * Registration Functions::              Functions to register things with
                                         @command{gawk}.
@@ -33216,6 +33217,7 @@ This (rather large) @value{SECTION} describes the API in detail.
 * General Data Types::                   The data types.
 * Memory Allocation Functions::          Functions for allocating memory.
 * Constructor Functions::                Functions for creating values.
+* API Ownership of MPFR and GMP Values:: Managing MPFR and GMP Values.
 * Registration Functions::               Functions to register things with
                                          @command{gawk}.
 * Printing Messages::                    Functions for printing messages.
@@ -33359,11 +33361,20 @@ does not support this keyword, you should either place
 @item
 All pointers filled in by @command{gawk} point 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}
+read-only.
+
+Memory for @emph{all} strings passed into @command{gawk}
 from the extension @emph{must} come from calling one of
 @code{gawk_malloc()}, @code{gawk_calloc()}, or @code{gawk_realloc()},
 and is managed by @command{gawk} from then on.
 
+Memory for MPFR/GMP values that come from @command{gawk}
+should also be treated as read-only.  However, unlike strings,
+memory for MPFR/GMP values allocated by an extension and passed
+into @command{gawk} is @emph{copied} by @command{gawk}; the extension
+should then free the values itself to avoid memory leaks. This is
+discussed further in @strong{FIXME}.
+
 @item
 The API defines several simple @code{struct}s that map values as seen
 from @command{awk}.  A value can be a @code{double}, a string, or an
@@ -33531,7 +33542,7 @@ in data received from @command{gawk}. In addition, by examining the
 member is either a GMP integer (type @code{mpz_ptr}), or an MPFR
 floating-point value (type @code{mpfr_ptr_t}), and cast it appropriately.
 
-@quotation CAUTION:
+@quotation CAUTION
 Any MPFR or MPZ values that you create and pass to @command{gawk}
 to save are @emph{copied}. This means you are responsible to release
 the storage once you're done with it. See the sample @code{intdiv}
@@ -33787,14 +33798,11 @@ pointed to by @code{result}.
 This function creates a GMP number value in @code{result}.
 The @code{mpz} must be from a call to @code{get_mpz_ptr()}
 (and thus be of real underlying type @code{mpz_ptr}).
-@command{gawk} takes ownership of this memory.
 
 @item static inline awk_value_t *
 @itemx make_number_mpfr(void *mpfr, awk_value_t *result);
 This function creates an MPFR number value in @code{result}.
 The @code{mpfr} must be from a call to @code{get_mpfr_ptr()}.
-(and thus be of real underlying type @code{mpfr_ptr})
-@command{gawk} takes ownership of this memory.
 
 @item static inline awk_value_t *
 @itemx make_const_user_input(const char *string, size_t length, awk_value_t *result);
@@ -33822,6 +33830,48 @@ to be a @samp{char *} value pointing to data previously obtained from
 
 @end table
 
+@node API Ownership of MPFR and GMP Values
+@subsection Managing MPFR and GMP Values
+@cindex MPFR values, API ownership of
+@cindex GMP values, API ownership of
+@cindex API, ownership of MPFR and GMP values
+
+MPFR and GMP values are different from string values, where you can
+``take ownership'' of the value simply by assigning pointers. For example:
+
+@example
+char *p = gawk_malloc(42);      p @ii{``owns'' the memory}
+char *q = p;
+p = NULL;                       @ii{now} q @ii{``owns'' it}
+@end example
+
+MPFR and GMP objects are indeed allocated on the stack or dynamically,
+but the MPFR and GMP libraries treat these objects as values, the same way that
+you would pass an @code{int} or a @code{double} by value.  There is no
+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_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 *).
+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);
+
+return result;
+@end example
+
 @node Registration Functions
 @subsection Registration Functions
 @cindex register loadable extension