From 8b6463a2aabc288e0a8ea40f67840a601d843e87 Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 + + 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 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