From 6f2aadd731d1c5c524437683a4a3135aed3fba0b Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Fri, 11 Nov 2022 00:28:49 -0800 Subject: [PATCH] Modernize and regularize doc for C89 etc. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In documentation and comments, prefer the more-common “C89” to the equivalent “C90”, and use 2-digit years for C standards as that’s common usage. Remove some confusing old doc for pre-C89 systems, as Autoconf assumes C89 or later. Mention C17 and C23 briefly. Improve doc for malloc, realloc. --- NEWS | 2 +- doc/autoconf.texi | 159 +++++++++++++--------------------------- lib/autoconf/headers.m4 | 14 ++-- 3 files changed, 57 insertions(+), 118 deletions(-) diff --git a/NEWS b/NEWS index d17e339a..1f687a8b 100644 --- a/NEWS +++ b/NEWS @@ -53,7 +53,7 @@ GNU Autoconf NEWS - User visible changes. These macros are now obsolescent, as programs can simply include stdbool.h unconditionally. If you use these macros, they now accept a stdbool.h that exists but does nothing, so long as ‘bool’, ‘true’, - and ‘false’ work anyway. This is for compatibility with C 2023 and + and ‘false’ work anyway. This is for compatibility with C23 and with C++. *** AC_PROG_MKDIR_P now falls back on plain 'mkdir -p'. diff --git a/doc/autoconf.texi b/doc/autoconf.texi index ed337fd6..7ae8ca64 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -4044,7 +4044,7 @@ previous tests, so for example one may write if @file{sys/time.h} has already been tested for. All hosted environments that are still of interest for portable code -provide all of the headers specified in ISO C90 (as amended in 1995): +provide all of the headers specified in C89 (as amended in 1995): @file{assert.h}, @file{ctype.h}, @file{errno.h}, @file{float.h}, @file{iso646.h}, @file{limits.h}, @file{locale.h}, @file{math.h}, @file{setjmp.h}, @file{signal.h}, @file{stdarg.h}, @file{stddef.h}, @@ -4052,13 +4052,14 @@ provide all of the headers specified in ISO C90 (as amended in 1995): @file{wchar.h}, and @file{wctype.h}. Most programs can safely include these headers unconditionally. All other headers, including all headers from later revisions of the C standard, need to be tested for +if your program is intended to be portable to C89 (@pxref{Header Files}). If your program needs to be portable to a @emph{freestanding} environment, such as an embedded OS that doesn't provide all of the -facilities of the C90 standard library, you may need to test for some of +facilities of the C89 standard library, you may need to test for some of the above headers as well. Note that many Autoconf macros internally -assume that the complete set of C90 headers are available. +assume that the complete set of C89 headers are available. Most generic macros use the following macro to provide a default set of includes: @@ -4834,12 +4835,6 @@ declared, due to C++ problems of some sort or another. For this reason we suggest that test programs not invoke @code{exit}, but return from @code{main} instead. -@item @code{free} -@c @fuindex free -@prindex @code{free} -The C standard says a call @code{free (NULL)} does nothing, but -some old systems don't support this (e.g., NextStep). - @item @code{isinf} @itemx @code{isnan} @c @fuindex isinf @@ -4899,7 +4894,7 @@ anyway, so it's probably not worth worrying about. @item @code{malloc} @c @fuindex malloc @prindex @code{malloc} -The C standard says a call @code{malloc (0)} is implementation +The C standard says a successful call @code{malloc (0)} is implementation dependent. It can return either @code{NULL} or a new non-null pointer. The latter is more common (e.g., the GNU C Library) but is by no means universal. @code{AC_FUNC_MALLOC} @@ -4927,25 +4922,20 @@ environment, rather than inserting it with an empty value. @item @code{realloc} @c @fuindex realloc @prindex @code{realloc} -The C standard says a call @code{realloc (NULL, size)} is equivalent -to @code{malloc (size)}, but some old systems don't support this (e.g., -NextStep). +It is problematic to call @code{realloc} with a zero size. +The C standard says @code{realloc (NULL, 0)} is equivalent to +@code{malloc (0)}, which means one cannot portably tell whether the call +has succeeded if it returns a null pointer. If @code{ptr} is non-null, +the C standard says @code{realloc (ptr, 0)} has undefined behavior. + +The @code{AC_FUNC_REALLOC} macro avoids some of these portability issues, +and the Gnulib module @code{realloc-gnu} avoids more of them. +@xref{Particular Functions}. @item @code{signal} handler @c @fuindex signal @prindex @code{signal} @prindex @code{sigaction} -Normally @code{signal} takes a handler function with a return type of -@code{void}, but some old systems required @code{int} instead. Any -actual @code{int} value returned is not used; this is only a -difference in the function prototype demanded. - -All systems we know of in current use return @code{void}. The -@code{int} was to support K&R C, where of course @code{void} is not -available. The obsolete macro @code{AC_TYPE_SIGNAL} -(@pxref{AC_TYPE_SIGNAL}) can be used to establish the correct type in -all cases. - In most cases, it is more robust to use @code{sigaction} when it is available, rather than @code{signal}. @@ -4957,34 +4947,22 @@ available, rather than @code{signal}. In C99 and later, if the output array isn't big enough and if no other errors occur, @code{snprintf} and @code{vsnprintf} truncate the output and return the number of bytes that ought to have -been produced. Some older systems return the truncated length (e.g., +been produced. Some ancient systems returned the truncated length (e.g., GNU C Library 2.0.x or IRIX 6.5), and some a negative value (e.g., earlier GNU C Library versions). -@item @code{sscanf} -@c @fuindex sscanf -@prindex @code{sscanf} -On various old systems, e.g., HP-UX 9, @code{sscanf} requires -that its -input string be writable (though it doesn't actually change it). This -can be a problem when using @command{gcc} since it normally puts -constant strings in read-only memory (@pxref{Incompatibilities, -Incompatibilities of GCC, , gcc, Using and -Porting the GNU Compiler Collection}). Apparently in some cases even -having format strings read-only can be a problem. - @item @code{strerror_r} @c @fuindex strerror_r @prindex @code{strerror_r} Posix specifies that @code{strerror_r} returns an @code{int}, but many -systems (e.g., GNU C Library version 2.2.4) provide a +systems (e.g., GNU C Library version 2.36) provide a different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R} can detect which is in use (@pxref{Particular Functions}). @item @code{strnlen} @c @fuindex strnlen @prindex @code{strnlen} -AIX 4.3 provides a broken version which produces the +AIX 4.3 provided a broken version which produces the following results: @example @@ -5046,9 +5024,8 @@ value back in the caller (e.g., @code{vsnprintf} in the GNU C Library @item Signed @code{>>} Normally the C @code{>>} right shift of a signed type replicates the high bit, giving a so-called ``arithmetic'' shift. But care should be -taken since Standard C doesn't require that behavior. On those -few processors without a native arithmetic shift (for instance Cray -vector systems) zero bits may be shifted in, the same as a shift of an +taken since Standard C doesn't require that behavior. On a few platforms +(e.g., Cray C by default) zero bits are shifted in, the same as a shift of an unsigned type. @item Integer @code{/} @@ -5280,8 +5257,7 @@ and also contains workarounds for other portability problems of @c @fuindex getgroups @prindex @code{getgroups} @caindex func_getgroups_works -If the @code{getgroups} function is available and works (unlike on -Ultrix 4.3 and NeXTstep 3.2, where @samp{getgroups (0, 0)} always fails), +If the @code{getgroups} function is available and works, define @code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}. @@ -6109,7 +6085,7 @@ and cache the result in the @code{ac_cv_header_stdbool_h} variable. If the type @code{_Bool} is defined, define @code{HAVE__BOOL} to 1. This macro is obsolescent, as all current C compilers have @file{stdbool.h}, -a header that is itself obsolescent as of C 2023. +a header that is itself obsolescent as of C23. This macro is intended for use by Gnulib (@pxref{Gnulib}) and other packages that supply a substitute @file{stdbool.h} on platforms lacking @@ -6276,40 +6252,11 @@ If @file{stdbool.h} exists and conforms to C99 or later, define @code{HAVE__BOOL} to 1. This macro is obsolescent, as all current C compilers have -@file{stdbool.h}, a header that is itself obsolescent as of C 2023. +@file{stdbool.h}, a header that is itself obsolescent as of C23. Nowadays programs that need @code{bool}, @code{true} and @code{false} can include @file{stdbool.h} unconditionally, without using @code{AC_HEADER_STDBOOL}, and if such a program needs to be portable -only to C 2023 or later it need not even include @file{stdbool.h}. - -This macro was originally intended for programs that needed to be -portable to C89. These obsolete programs could use the following code, -so long as they assigned only 0 or 1 to @code{bool} variables: - -@example -@group -#ifdef HAVE_STDBOOL_H -# include -#else -# ifndef HAVE__BOOL -# ifdef __cplusplus -typedef bool _Bool; -# else -# define _Bool signed char -# endif -# endif -# define bool _Bool -# define false 0 -# define true 1 -# define __bool_true_false_are_defined 1 -#endif -@end group -@end example - -Alternatively if you still need portability to C89 you can use the -@samp{stdbool} package of Gnulib (@pxref{Gnulib}). It lets code say just -@code{#include }, and it adds support for less-common -platforms. +only to C23 or later it need not even include @file{stdbool.h}. This macro caches its result in the @code{ac_cv_header_stdbool_h} variable. @@ -6327,10 +6274,10 @@ does not. This macro is obsolescent. Its sole effect is to make sure that all the headers that are included by @code{AC_INCLUDES_DEFAULT} (@pxref{Default -Includes}), but not part of ISO C90, have been checked for. +Includes}), but not part of C89, have been checked for. All hosted environments that are still of interest for portable code -provide all of the headers specified in ISO C90 (as amended in 1995). +provide all of the headers specified in C89 (as amended in 1995). @end defmac @defmac AC_HEADER_SYS_WAIT @@ -6852,7 +6799,7 @@ If @file{stdint.h} or @file{inttypes.h} does not define the type integer type that is exactly 8 bits wide and that uses two's complement representation, if such a type exists. If you are worried about porting to hosts that lack such a type, you can -use the results of this macro in C89-or-later code as follows: +use the results of this macro as follows: @example #if HAVE_STDINT_H @@ -7276,8 +7223,7 @@ suitable for a variable name mapped to underscores. Store into the shell variable @var{var} the value of the integer @var{expression}. The value should fit in an initializer in a C variable of type @code{signed -long}. To support cross compilation (in which case, the macro only works on -hosts that use twos-complement arithmetic), it should be possible to evaluate +long}. To support cross compilation, it should be possible to evaluate the expression at compile-time. If no @var{includes} are specified, the default includes are used (@pxref{Default Includes}). @@ -7475,8 +7421,9 @@ person building the package. @xref{Preset Output Variables}.) If necessary, options are added to @code{CC} to enable support for ISO Standard C features with extensions, preferring the newest edition -of the C standard that is supported. Currently the newest edition -Autoconf knows how to detect support for is ISO C 2011. After calling +of the C standard for which detection is supported. Currently the +newest edition Autoconf knows how to detect support for is C11, as there is +little reason to prefer C17 to C11, and C23 is still too new. After calling this macro you can check whether the C compiler has been set to accept standard C by inspecting the shell variable @code{ac_prog_cc_stdc}. Its value will be @samp{c11}, @samp{c99}, or @samp{c89}, respectively, @@ -7874,7 +7821,7 @@ person building the package. @xref{Preset Output Variables}.) If necessary, options are added to @code{CXX} to enable support for ISO Standard C++ features with extensions, preferring the newest edition of the C++ standard that is supported. Currently the newest edition -Autoconf knows how to detect support for is ISO C++ 2011. After calling +Autoconf knows how to detect support for is C++11. After calling this macro, you can check whether the C++ compiler has been set to accept standard C++ by inspecting the shell variable @code{ac_prog_cxx_stdcxx}. Its value will be @samp{cxx11} or @samp{cxx98}, respectively, @@ -9403,8 +9350,8 @@ after running test programs and if the script is interrupted. @node Test Functions @subsection Test Functions -These days it's safe to assume support for function prototypes -(introduced in C89). +Functions in test code should use function prototypes, introduced in C89 +and required in C23. Functions that test programs declare should also be conditionalized for C++, which requires @samp{extern "C"} prototypes. Make sure to not @@ -19210,10 +19157,10 @@ The default executable, produced by @samp{cc foo.c}, can be @end itemize The C compiler's traditional name is @command{cc}, but other names like -@command{gcc} are common. Posix 1003.1-2001 and 1003.1-2008 specify the +@command{gcc} are common. Posix 1003.1-2001 through 1003.1-2017 specify the name @command{c99}, but older Posix editions specified @command{c89}, future POSIX standards will likely specify -@command{c11}, and anyway these standard names are rarely used in +other commands, and anyway these standard names are rarely used in practice. Typically the C compiler is invoked from makefiles that use @samp{$(CC)}, so the value of the @samp{CC} make variable selects the compiler name. @@ -21665,9 +21612,14 @@ GCC, gcc, Using the GNU Compiler Collection for a list of C-related standards. Many programs also assume the @uref{https://@/en.wikipedia.org/@/wiki/@/POSIX, Posix standard}. -Some old code is written to be portable to K&R C, which predates any C +@cindex K&R C +@cindex C89, C99, C11, C17, and C23 +The first widely used C variant was K&R C, which predates any C standard. K&R C compilers are no longer of practical interest, though, -and the rest of section assumes at least C89, the first C standard. +and Autoconf assumes at least C89, the first C standard, +which is sometimes called ``C90'' due to a delay in standardization. +C has since gone through the standards C99, C11, C17, and C23, and +Autoconf is compatible with all these standards. Program portability is a huge topic, and this section can only briefly introduce common pitfalls. @xref{System Portability, , Portability @@ -21776,9 +21728,9 @@ especially when optimization is enabled. If you assume a GCC-like compiler, you can work around the problems by compiling with GCC's @code{-fwrapv} option; however, this is not portable. -For historical reasons the C standard also allows implementations with -ones' complement or signed magnitude arithmetic, but it is safe to -assume two's complement nowadays. +For historical reasons C17 and earlier also allowed implementations with +ones' complement or signed magnitude arithmetic, but C23 requires +two's complement and it is safe to assume two's complement nowadays. Also, overflow can occur when converting an out-of-range value to a signed integer type. Here a standard implementation must define what @@ -24369,7 +24321,7 @@ issue. @defmac AC_RETSIGTYPE @acindex{RETSIGTYPE} Replaced by @code{AC_TYPE_SIGNAL} (@pxref{AC_TYPE_SIGNAL}), which itself -is obsolete when assuming C89 or better. +is obsolete. @end defmac @defmac AC_RSH @@ -24424,7 +24376,7 @@ Replaced by @code{AC_HEADER_STAT} (@pxref{AC_HEADER_STAT}). @defmac AC_STDC_HEADERS @acindex{STDC_HEADERS} Replaced by @code{AC_HEADER_STDC} (@pxref{AC_HEADER_STDC}), which -is itself obsolete. Nowadays it is safe to assume the facilities of C90 +is itself obsolete. Nowadays it is safe to assume the facilities of C89 exist. @end defmac @@ -24643,19 +24595,6 @@ function returning @code{void}, define @code{RETSIGTYPE} to be @code{void}; otherwise, define it to be @code{int}. These days, it is portable to assume C89, and that signal handlers return @code{void}, without needing to use this macro or @code{RETSIGTYPE}. - -When targeting older K&R C, it is possible to define signal handlers as -returning type @code{RETSIGTYPE}, and omit a return statement: - -@example -@group -RETSIGTYPE -hup_handler () -@{ -@dots{} -@} -@end group -@end example @end defmac @defmac AC_UID_T @@ -24677,7 +24616,7 @@ unnecessary to write explicitly. Define @code{USG} if the BSD string functions (@code{bcopy}, @code{bzero}, @code{index}, @code{rindex}, etc) are @emph{not} defined in @file{strings.h}. Modern code should assume @file{string.h} exists -and should use the ISO C string functions (@code{memmove}, @code{memset}, +and should use the standard C string functions (@code{memmove}, @code{memset}, @code{strchr}, @code{strrchr}, etc) unconditionally. @file{strings.h} may be the only header that declares @code{strcasecmp}, @@ -27350,7 +27289,7 @@ introduced in this document. @c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy @c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD @c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX -@c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof +@c LocalWords: isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof @c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW @c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef @c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC diff --git a/lib/autoconf/headers.m4 b/lib/autoconf/headers.m4 index caf36fa4..5fde7f5a 100644 --- a/lib/autoconf/headers.m4 +++ b/lib/autoconf/headers.m4 @@ -328,7 +328,7 @@ m4_map_args([_AC_CHECK_HEADER_ONCE], [strings.h], [sys/stat.h], [sys/types.h], [unistd.h])]dnl [AS_IF([test $ac_cv_header_stdlib_h = yes && test $ac_cv_header_string_h = yes], [AC_DEFINE([STDC_HEADERS], [1], - [Define to 1 if all of the C90 standard headers exist + [Define to 1 if all of the C89 standard headers exist (not just the ones required in a freestanding environment). This macro is provided for backward compatibility; new code need not use it.])])]) @@ -356,7 +356,7 @@ AC_DEFUN([AC_INCLUDES_DEFAULT], ## ------------------------------------------- ## # There is no longer any need to check for headers that are part of -# ISO C90 (as amended): assert.h, ctype.h, errno.h, float.h, iso646.h, +# C89 (as amended): assert.h, ctype.h, errno.h, float.h, iso646.h, # limits.h, locale.h, math.h, setjmp.h, signal.h, stdarg.h, stddef.h, # stdio.h, stdlib.h, string.h, time.h, wchar.h, wctype.h. @@ -588,10 +588,10 @@ AC_DEFUN([AC_CHECK_HEADER_STDBOOL], integer constant expressions, and "bool" should be a valid type name. - Although C 1999 requires bool, true, and false to be macros, - C 2023 and C++ 2011 overrule that, so do not test for that. - Although C 1999 requires __bool_true_false_are_defined and - _Bool, C 2023 says they are obsolescent, so do not require + Although C99 requires bool, true, and false to be macros, + C23 and C++11 overrule that, so do not test for that. + Although C99 requires __bool_true_false_are_defined and + _Bool, C23 says they are obsolescent, so do not require them. */ #if !true @@ -668,7 +668,7 @@ AC_PROG_EGREP ], [The preprocessor macro 'STDC_HEADERS' is obsolete. Except in unusual embedded environments, you can safely include all - ISO C90 headers unconditionally.]) + C89 headers unconditionally.]) # AC_HEADER_SYS_WAIT # ------------------ -- 2.37.2