On 12/4/20 12:47 PM, Bruno Haible wrote:
The currently sold Unisys ClearPath Dorado
machines contain Xeon processors.
They're Xeon processors but they come with Unisys-supplied firmware that emulate
the older architectures, which means that C programs on these platforms should
follow the old rules. Five or ten years ago Unisys found that this performed
better than the chips they were designing themselves. Unisys did this for both
their Dorado and Libra mainframes (quite different ISAs: the former is
ones'-complement, the latter signed-magnitude), at about the same time.
Come to think of it, IBM has also done something similar, for its IBM i
(formerly AS/400, formerly System/38) line, which originally used 48-bit words.
Starting around 2000 they switched it to use IBM's POWER chips with 64-bit
words. A difference is that IBM i programs have always been translated as needed
by the runtime from a machine-independent format, instead of being interpreted
by an emulator.
From a Gnulib viewpoint, the main problem with IBM i C is that the preferred
pointers size is 128 bits and there is no intptr_t type; although POSIX and the
C standard allow this, it'd break a lot of GNU code. In practice, anybody
running GNUish code on the IBM i would run it under PASE, which can execute AIX
programs in a mostly binary-compatible way (with 64-bit pointers and with intptr_t).
We might as well document this, if only to state more clearly what platforms
Gnulib (and most GNU apps) clearly don't support. I installed the attached,
which adds a section "Exotic platforms" and documents the IBM i and the two
Unisys platforms. I didn't bother mentioning platforms like the old x86 where
int is 16 bits and there are near and far pointers, as the GNU coding standards
explicitly reject tiny-int platforms.
From 8b6463a2aabc288e0a8ea40f67840a601d843e87 Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@cs.ucla.edu>
Date: Sat, 5 Dec 2020 11:27:13 -0800
Subject: [PATCH] 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.
---
ChangeLog | 12 +++++++
doc/gnulib-readme.texi | 74 ++++++++++++++++++++++++++++++++++++++----
doc/intprops.texi | 56 +++++---------------------------
3 files changed, 88 insertions(+), 54 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 3de636895..0bc0a23c1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2020-12-05 Paul Eggert <egg...@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 <br...@clisp.org>
utime: Fix a test failure on macOS 10.13.
diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi
index 45b7484f4..8a5a56f89 100644
--- a/doc/gnulib-readme.texi
+++ b/doc/gnulib-readme.texi
@@ -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
diff --git a/doc/intprops.texi b/doc/intprops.texi
index e2ed4351c..294c235f5 100644
--- a/doc/intprops.texi
+++ b/doc/intprops.texi
@@ -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.
--
2.27.0
