* doc/gnulib-readme.texi:
Prefer “null pointer” to “@code{NULL}” since C23 has nullptr.
(Portability guidelines): Mention C99 instead of C89 for what
Gnulib assumes of headers.
(C99 features avoided): Mention CHERI issue with intptr_t etc.
(Other portability assumptions): Say that C23 requires two’s
complement. Mention CHERI’s holes.
---
ChangeLog | 11 ++++++++++
doc/gnulib-readme.texi | 46 ++++++++++++++++++++++++++----------------
2 files changed, 40 insertions(+), 17 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index b48c7912e9..c713de7b42 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2023-12-01 Paul Eggert <egg...@cs.ucla.edu>
+
+ Update portability doc for CHERI, C23
+ * doc/gnulib-readme.texi:
+ Prefer “null pointer” to “@code{NULL}” since C23 has nullptr.
+ (Portability guidelines): Mention C99 instead of C89 for what
+ Gnulib assumes of headers.
+ (C99 features avoided): Mention CHERI issue with intptr_t etc.
+ (Other portability assumptions): Say that C23 requires two’s
+ complement. Mention CHERI’s holes.
+
2023-12-01 Bruno Haible <br...@clisp.org>
obstack: Avoid undefined behaviour.
diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi
index a08d3c0100..b111216db5 100644
--- a/doc/gnulib-readme.texi
+++ b/doc/gnulib-readme.texi
@@ -288,7 +288,7 @@ platform is not the latest version. @xref{Target
Platforms}.
Many Gnulib modules exist so that applications need not worry about
undesirable variability in implementations. For example, an
application that uses the @code{malloc} module need not worry about
-@code{malloc@ (0)} returning @code{NULL} on some Standard C
+@code{malloc@ (0)} returning a null pointer on some Standard C
platforms; and @code{glob} users need not worry about @code{glob}
silently omitting symbolic links to nonexistent files on some
platforms that do not conform to POSIX.
@@ -336,8 +336,8 @@ forever.
Even if the include files exist, they may not conform to the C standard.
However, GCC has a @command{fixincludes} script that attempts to fix most
-C89-conformance problems. Gnulib currently assumes include files
-largely conform to C89 or better. People still using ancient hosts
+conformance problems. Gnulib currently assumes include files
+largely conform to C99 or better. People still using ancient hosts
should use fixincludes or fix their include files manually.
Even if the include files conform, the library itself may not.
@@ -424,6 +424,14 @@ and to avoid large stack usage that may have security
implications.
variably modified types, such as array declarations in function
prototype scope.
+@item
+Converting to pointers via integer types other than @code{intptr_t} or
+@code{uintptr_t}. Although the C standard says that values of these
+integer types, if they exist, should be convertible to and from
+@code{intmax_t} and @code{uintmax_t} without loss of information, on
+CHERI platforms such conversions result in integers that, if converted
+back to a pointer, cannot be dereferenced.
+
@item
@code{extern inline} functions, without checking whether they are
supported. @xref{extern inline}.
@@ -445,10 +453,14 @@ Comments beginning with @samp{//}. This is mostly for
style reasons.
@node Other portability assumptions
@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{ptrdiff_t} and @code{size_t} are no
-wider than @code{long}. POSIX requires implementations to support at
+Gnulib code makes the following assumptions
+that go beyond what C and POSIX require:
+
+@itemize
+@item
+Standard internal types like @code{ptrdiff_t} and @code{size_t} are no
+wider than @code{long}. The GNU coding standards allow code to make
+this assumption, 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
is easy to port to non-POSIX platforms like MinGW where these types
@@ -457,9 +469,6 @@ using @code{ptrdiff_t} instead of @code{long}. However, it
is not
always that easy, and no effort has been made to check that all Gnulib
modules work on MinGW-like environments.
-Gnulib code makes the following additional assumptions:
-
-@itemize
@item
@code{int} and @code{unsigned int} are at least 32 bits wide. POSIX
and the GNU coding standards both require this.
@@ -473,21 +482,24 @@ sometimes do not guarantee this, and Gnulib code with this
assumption is now considered to be questionable.
@xref{Integer Properties}.
-Although some Gnulib modules contain explicit support for the other signed
-integer representations allowed by the C standard (ones' complement and signed
-magnitude), these modules are the exception rather than the rule.
-All practical Gnulib targets use two's complement.
+Although some Gnulib modules contain explicit support for
+ones' complement and signed magnitude integer representations,
+which are allowed by C17 and earlier,
+these modules are the exception rather than the rule.
+All practical Gnulib targets use two's complement, which is required by C23.
@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.
+(As an exception, Gnulib code is portable to CHERI platforms
+even though this assumption is false for CHERI.)
@item
-Objects with all bits zero are treated as 0 or NULL@. For example,
-@code{memset@ (A, 0, sizeof@ A)} initializes an array @code{A} of
-pointers to NULL.
+Objects with all bits zero are treated as zero or as null pointers.
+For example, @code{memset@ (A, 0, sizeof@ A)} initializes an array
+@code{A} of pointers to null pointers.
@item
The types @code{intptr_t} and @code{uintptr_t} exist, and pointers
--
2.40.1
