Invalid read in mpz_sub

[Vincent Lefevre]

On 2016-04-07 10:58:13 +0200, Torbjörn Granlund wrote:
> I agree this should be made explicit; users should not need to worry
> about the inner workings of our types (such as the fact that they
> contain a pointer).
> 
> Would you want to contribute a patch for our manual?

I propose the attached patch. I think that 3.4 Variable Conventions
is the best section for such information. So, I've moved a part of
the paragraph in 3.5 Parameter Conventions to a new paragraph in 3.4
with more information, and I've shortened the paragraph in 3.5 to
make it deal with only parameter conventions.

-- 
Vincent Lefèvre <vincent at vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)
-------------- next part --------------
diff -r 8ccd8e7de27b doc/gmp.texi
--- a/doc/gmp.texi	Sun Apr 03 16:50:36 2016 +0200
+++ b/doc/gmp.texi	Thu Apr 07 13:07:28 2016 +0200
@@ -2070,6 +2070,18 @@
 @}
 @end example
 
+Such GMP types like @code{mpz_t} are implemented as one-element arrays
+of certain structures.  Declaring a variable creates an object with the
+fields GMP needs, but variables are normally manipulated by using the
+pointer to the object.  For both behavior and efficiency reasons, it is
+discouraged to make copies of the GMP object itself (either directly or
+via aggregate objects containing such GMP objects).  If copies are done,
+all of them must be used read-only; using a copy as the output of some
+function will invalidate all the other copies.  Note that the actual
+fields in each @code{mpz_t} etc are for internal use only and should not
+be accessed directly by code that expects to be compatible with future
+GMP releases.
+
 
 @node Parameter Conventions, Memory Management, Variable Conventions, GMP Basics
 @section Parameter Conventions
@@ -2118,12 +2130,9 @@
 sometimes it's tricky to make that work, and an application might not want to
 bother supporting that sort of thing.
 
-For interest, the GMP types @code{mpz_t} etc are implemented as one-element
-arrays of certain structures.  This is why declaring a variable creates an
-object with the fields GMP needs, but then using it as a parameter passes a
-pointer to the object.  Note that the actual fields in each @code{mpz_t} etc
-are for internal use only and should not be accessed directly by code that
-expects to be compatible with future GMP releases.
+Since GMP types are implemented as one-element arrays, using a GMP
+variable as a parameter passes a pointer to the object. Hence the
+call-by-reference.
 
 
 @need 1000