]> Savannah Git Hosting - gnulib.git/commitdiff
doc: mention intptr_t etc. and IBM i
authorPaul Eggert <eggert@cs.ucla.edu>
Sat, 5 Dec 2020 19:27:13 +0000 (11:27 -0800)
committerPaul Eggert <eggert@cs.ucla.edu>
Sat, 5 Dec 2020 19:27:58 +0000 (11:27 -0800)
* doc/gnulib-readme.texi (Other portability assumptions):
Mention intptr_t and uintptr_t, and that arithmetic on them
works in the usual way.
(Exotic platforms): New section, containing material from
the old 'Integer Portability' section.  Also mention IBM i.
* doc/intprops.texi (Wraparound Arithmetic):
Say that the macros work on unsigned integers too.
(Integer Portability): Remove.

ChangeLog
doc/gnulib-readme.texi
doc/intprops.texi

index 3de636895915cb17806b62ac792496ecdb34e839..0bc0a23c18b5aaee07a4e48610f11b376e451b45 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2020-12-05  Paul Eggert  <eggert@cs.ucla.edu>
+
+       doc: mention intptr_t etc. and IBM i
+       * doc/gnulib-readme.texi (Other portability assumptions):
+       Mention intptr_t and uintptr_t, and that arithmetic on them
+       works in the usual way.
+       (Exotic platforms): New section, containing material from
+       the old 'Integer Portability' section.  Also mention IBM i.
+       * doc/intprops.texi (Wraparound Arithmetic):
+       Say that the macros work on unsigned integers too.
+       (Integer Portability): Remove.
+
 2020-12-04  Bruno Haible  <bruno@clisp.org>
 
        utime: Fix a test failure on macOS 10.13.
index 45b7484f4d196209e86620dea85fd7566f75eb02..8a5a56f891f42b8cb18011cbdaa24cdbdd492cda 100644 (file)
@@ -308,6 +308,7 @@ general Gnulib portability guidelines.
 * C99 features assumed::
 * C99 features avoided::
 * Other portability assumptions::
+* Exotic platforms::
 @end menu
 
 @node C language versions
@@ -462,6 +463,12 @@ All practical Gnulib targets use two's complement.
 @item
 There are no ``holes'' in integer values: all the bits of an integer
 contribute to its value in the usual way.
+In particular, an unsigned type and its signed counterpart have the
+same number of bits when you count the latter's sign bit.
+
+@item
+The types @code{intptr_t} and @code{uintptr_t} exist, and pointers
+can be converted to and from these types without loss of information.
 
 @item
 Addresses and sizes behave as if objects reside in a flat address space.
@@ -478,6 +485,20 @@ A pointer @var{P} points within an object @var{O} if and only if
 @code{(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} <
 (char *) (&@var{O} + 1)}.
 
+@item
+Arithmetic on a valid pointer is equivalent to the same arithmetic on
+the pointer converted to @code{uintptr_t}, except that offsets are
+multiplied by the size of the pointed-to objects.
+For example, if @code{P + I} is a valid expression involving a pointer
+@var{P} and an integer @var{I}, then @code{(uintptr_t) (P + I) ==
+(uintptr_t) ((uintptr_t) P + I * sizeof *P)}.
+Similar arithmetic can be done with @code{intptr_t}, although more
+care must be taken in case of integer overflow or negative integers.
+
+@item
+A pointer @code{P} has alignment @code{A} if and only if
+@code{(uintptr_t) P % A} is zero, and similarly for @code{intptr_t}.
+
 @item
 If an existing object has size @var{S}, and if @var{T} is sufficiently
 small (e.g., 8 KiB), then @code{@var{S} + @var{T}} cannot overflow.
@@ -496,12 +517,53 @@ For example, @code{0 + (char *) NULL == (char *) NULL}.
 @end itemize
 @end itemize
 
-The above assumptions are not required by the C or POSIX standards but
-hold on all practical porting targets that we're familiar with.  If
-you have a porting target where these assumptions are not true, we'd
-appreciate hearing of any fixes.  We need fixes that do not increase
-runtime overhead on standard hosts and that are relatively easy to
-maintain.
+@node Exotic platforms
+@subsection Exotic platforms
+
+@cindex integer arithmetic portability
+@cindex portability, integer arithmetic
+
+Gnulib's portability assumptions are not required by the C or POSIX
+standards but hold on almost all practical porting targets.  If you
+need to port Gnulib code to a platform where these assumptions are not
+true, we would appreciate hearing of any fixes.  We need fixes that do
+not increase runtime overhead on standard hosts and that are
+relatively easy to maintain.
+
+A few practical platforms violate the @code{intprops} assumptions
+and are therefore not porting targets for Gnulib.  Three 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 IBM i's pointers are 128 bits wide and it lacks the two types
+@code{intptr_t} and @code{uintptr_t}, which are optional in the C and
+POSIX standards.  However, these two types are required for the XSI
+extension to POSIX, and many Gnulib modules use them.  To work around
+this compatibility problem, Gnulib-using applications can be run on
+the IBM i's emulation environment PASE.  The IBM i's architecture
+descends from the System/38 (1978).
+
+@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
 
 @node High Quality
 @section High Quality
index e2ed4351c6e048e885bfa25017feaa45223fd470..294c235f5fe43efd4296c198c1394e25e935ad39 100644 (file)
@@ -42,9 +42,9 @@ 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.
+module assumes that integers use a two's complement representation,
+but it does not assume that signed integer arithmetic wraps around.
+@xref{Other portability assumptions}.
 
 @menu
 * Arithmetic Type Properties::  Determining properties of arithmetic types.
@@ -52,7 +52,6 @@ implementation is portable to almost all practical C platforms.
 * 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
@@ -152,7 +151,7 @@ in_off_t_range (intmax_t a)
 @end example
 
 @node Wraparound Arithmetic
-@subsection Wraparound Arithmetic with Signed Integers
+@subsection Wraparound Arithmetic with Integers
 
 @cindex wraparound integer arithmetic
 
@@ -194,7 +193,10 @@ print_product (long int a, long int b)
 @}
 @end example
 
-@noindent
+These macros work for both signed and unsigned integers, so they can
+be used with integer types like @code{time_t} that may or may not be
+signed, depending on the platform.
+
 These macros have the following restrictions:
 
 @itemize @bullet
@@ -476,45 +478,3 @@ 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.