[PATCH] intprops: update doc and mention Unisys

[Paul Eggert]

* doc/gnulib-readme.texi (Other portability assumptions):
Also mention ptrdiff_t when talking about widths and overflow.
* doc/intprops.texi (Integer Properties): Summarize new section.
(Arithmetic Type Properties): Document that EXPR_SIGNED no longer
evaluates its argument.
(Integer Bounds): Fix typo.
(Wraparound Arithmetic): Remove obsolete comment about efficiency.
Document that the _WRAPV macros now support pointers to unsigned
integers.
(Integer Range Overflow): Update SEI CERT citation.
(Integer Portability): New subsection, which mentions
the oddball Unisys platforms as non-Gnulib targets.
---
 ChangeLog              | 16 ++++++++++
 doc/gnulib-readme.texi |  8 +++--
 doc/intprops.texi      | 68 ++++++++++++++++++++++++++++++++++--------
 3 files changed, 77 insertions(+), 15 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 711294c32..5c19598b4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2020-12-04  Paul Eggert  <eggert@cs.ucla.edu>
+
+       intprops: update doc and mention Unisys
+       * doc/gnulib-readme.texi (Other portability assumptions):
+       Also mention ptrdiff_t when talking about widths and overflow.
+       * doc/intprops.texi (Integer Properties): Summarize new section.
+       (Arithmetic Type Properties): Document that EXPR_SIGNED no longer
+       evaluates its argument.
+       (Integer Bounds): Fix typo.
+       (Wraparound Arithmetic): Remove obsolete comment about efficiency.
+       Document that the _WRAPV macros now support pointers to unsigned
+       integers.
+       (Integer Range Overflow): Update SEI CERT citation.
+       (Integer Portability): New subsection, which mentions
+       the oddball Unisys platforms as non-Gnulib targets.
+
 2020-12-03  Bruno Haible  <bruno@clisp.org>
 
        idx: Clarify that idx_t always behaves like a signed type.
diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi
index beb0ca9b6..45b7484f4 100644
--- a/doc/gnulib-readme.texi
+++ b/doc/gnulib-readme.texi
@@ -427,7 +427,8 @@ Comments beginning with @samp{//}.  This is mostly for 
style reasons.
 @subsection Other portability assumptions made by Gnulib
 
 The GNU coding standards allow one departure from strict C: Gnulib
-code can assume that standard internal types like @code{size_t} are no
+code can assume that standard internal types like
+@code{ptrdiff_t} and @code{size_t} are no
 wider than @code{long}.  POSIX requires implementations to support at
 least one programming environment where this is true, and such
 environments are recommended for Gnulib-using applications.  When it
@@ -447,7 +448,7 @@ and the GNU coding standards both require this.
 @item
 Signed integer arithmetic is two's complement.
 
-Previously, Gnulib code sometimes assumed that signed integer
+Previously, Gnulib code sometimes also assumed that signed integer
 arithmetic wraps around, but modern compiler optimizations
 sometimes do not guarantee this, and Gnulib code with this
 assumption is now considered to be questionable.
@@ -469,7 +470,8 @@ In particular:
 @itemize
 @item
 If two nonoverlapping objects have sizes @var{S} and @var{T} represented as
-@code{size_t} values, then @code{@var{S} + @var{T}} cannot overflow.
+@code{ptrdiff_t} or @code{size_t} values, then @code{@var{S} + @var{T}}
+cannot overflow.
 
 @item
 A pointer @var{P} points within an object @var{O} if and only if
diff --git a/doc/intprops.texi b/doc/intprops.texi
index 24d192181..e2ed4351c 100644
--- a/doc/intprops.texi
+++ b/doc/intprops.texi
@@ -41,12 +41,18 @@ are two families of precondition tests: the first, for 
integer types,
 is easier to use, while the second, for integer ranges, has a simple
 and straightforward portable implementation.
 
+Like other Gnulib modules, the implementation of the @code{intprops}
+module assumes that integers use a two's complement representation but
+does not assume that signed integer arithmetic wraps around.  The
+implementation is portable to almost all practical C platforms.
+
 @menu
 * Arithmetic Type Properties::  Determining properties of arithmetic types.
 * Integer Bounds::              Bounds on integer values and representations.
 * Wraparound Arithmetic::       Well-defined behavior on signed overflow.
 * Integer Type Overflow::       General integer overflow checking.
 * Integer Range Overflow::      Integer overflow checking if bounds are known.
+* Integer Portability::         Portability assumptions of Gnulib integer code.
 @end menu
 
 @node Arithmetic Type Properties
@@ -67,8 +73,8 @@ is an integer constant expression.
 @code{EXPR_SIGNED (@var{e})} is 1 if the real expression @var{e}
 has a signed integer type or a floating type.  If @var{e} is an
 integer constant expression or an arithmetic constant expression,
-@code{EXPR_SIGNED (@var{e})} is likewise.  Although @var{e} is
-evaluated, if @var{e} is free of side effects then @code{EXPR_SIGNED
+@code{EXPR_SIGNED (@var{e})} is likewise.  The expression
+@var{e} is not evaluated, and @code{EXPR_SIGNED
 (@var{e})} is typically optimized to a constant.
 
 Example usage:
@@ -100,7 +106,7 @@ CLOCKS_PER_SEC_is_signed (void)
 expression that is a bound on the size of the string representing an
 integer type or expression @var{t} in decimal notation, including the
 terminating null character and any leading @code{-} character.  For
-example, if @code{INT_STRLEN_BOUND (int)} is 12, any value of type
+example, if @code{INT_BUFSIZE_BOUND (int)} is 12, any value of type
 @code{int} can be represented in 12 bytes or less, including the
 terminating null.  The bound is not necessarily tight.
 
@@ -165,9 +171,8 @@ The following macros work around this problem by storing the
 wraparound value, i.e., the low-order bits of the correct answer, and
 by returning an overflow indication.  For example, if @code{i} is of
 type @code{int}, @code{INT_ADD_WRAPV (INT_MAX, 1, &i)} sets @code{i}
-to @code{INT_MIN} and returns 1 on a two's complement machine.  On
-newer platforms, these macros are typically more efficient than the
-overflow-checking macros.  @xref{Integer Type Overflow}.
+to @code{INT_MIN} and returns 1 on a two's complement machine.
+@xref{Integer Type Overflow}.
 
 Example usage:
 
@@ -197,10 +202,7 @@ These macros have the following restrictions:
 Their first two arguments must be integer expressions.
 
 @item
-Their last argument must be a non-null pointer to a signed integer.
-To calculate a wraparound unsigned integer you can use ordinary C
-arithmetic; to tell whether it overflowed, you can use the
-overflow-checking macros.
+Their last argument must be a non-null pointer to an integer.
 
 @item
 They may evaluate their arguments zero or multiple times, so the
@@ -365,8 +367,8 @@ harder to use than the integer type overflow macros.  
@xref{Integer
 Type Overflow}.
 
 Although the implementation of these macros is similar to that
-suggested in Seacord R, The CERT C Secure Coding Standard (2009,
-revised 2011), in its two sections
+suggested in the SEI CERT C Secure Coding Standard,
+in its two sections
 
``@url{https://www.securecoding.cert.org/confluence/display/c/INT30-C.+Ensure+that+unsigned+integer+operations+do+not+wrap,
 INT30-C@. Ensure that unsigned integer operations do not wrap}'' and
 
``@url{https://www.securecoding.cert.org/confluence/display/c/INT32-C.+Ensure+that+operations+on+signed+integers+do+not+result+in+overflow,
@@ -474,3 +476,45 @@ where @var{w} is @var{a}'s word width, and that when 
@var{a} is negative
 then @code{@var{a} << @var{b}} has undefined behavior, but this macro
 does not check these other restrictions.
 @end table
+
+@node Integer Portability
+@subsection Integer Portability
+
+@cindex integer arithmetic portability
+@cindex portability, integer arithmetic
+
+Like other Gnulib modules, the implementation of the @code{intprops}
+modules assumes that integers use a two's complement representation
+with no padding bits in a machine word.  The implementation does not
+assume that signed integer arithmetic wraps around; however, it does
+assume that an unsigned type and its signed counterpart have the same
+number of bits when you count the latter's sign bit.
+
+Two known practical platforms violate the @code{intprops} assumptions
+and are therefore not porting targets for Gnulib.  They are listed
+below to illustrate problems that Gnulib and Gnulib-using code would
+have if it were intended to be portable to all practical POSIX or C
+platforms.
+
+@itemize @bullet
+@item
+The Unisys ClearPath Libra's machine word is 48 bits.  Its
+@code{unsigned int} uses the low-order 40 bits of the word, and
+@code{int} uses the low-order 41 bits of the word with a
+signed-magnitude representation.  On these machines, @code{INT_MAX ==
+UINT_MAX}, @code{INT_MIN == -INT_MAX}, and @code{sizeof (int) == 6}.
+This platform's architecture descends from the Burroughs B5000 (1961).
+
+@item
+The Unisys ClearPath Dorado's machine word is 36 bits.  Its signed
+integers use a ones'-complement representation.  On these machines,
+@code{CHAR_BIT == 9} and @code{INT_MIN == -INT_MAX}.  By default
+@code{UINT_MAX} is @math{2^{36} - 2}, which does not conform to the C
+requirement that it be one less than a power of two.  Although
+compiler options can raise @code{UINT_MAX} to be @math{2^{36} - 1},
+this can break system code that uses @math{-0} as a flag value.
+This platform's architecture descends from the UNIVAC 1107 (1962).
+@end itemize
+
+@noindent
+Fortunately, these platforms are now quite rare.
-- 
2.27.0