[v2] manual: Document missing feature test macros.
Commit Message
Several feature test macros are documented in features.h but absent in
the manual, and some documented macros accept undocumented values.
This commit updates the manual to mention all the accepted macros,
along with any values that hold special meaning.
* manual/creature.texi (_POSIX_C_SOURCE): Document special
values of 199606L, 200112L, and 200809L.
(_XOPEN_SOURCE): Document special values of 600 and 700.
(_ISOC11_SOURCE): Document macro.
(_ATFILE_SOURCE): Likewise.
(_FORTIFY_SOURCE): Likewise.
---
Changes in v2:
* Refer to base editions of POSIX standards, and mention
supported subsequent bug-fix editions explicitly.
* Set @standards for _ATFILE_SOURCE and _FORTIFY_SOURCE to
GNU.
* Minor wording changes
* Rebase to master (post-88f9e739).
---
manual/creature.texi | 36 +++++++++++++++++++++++++++++++++++-
1 file changed, 35 insertions(+), 1 deletion(-)
Comments
Ping
On 07/27/2017 08:43 PM, Rical Jasan wrote:
> Several feature test macros are documented in features.h but absent in
> the manual, and some documented macros accept undocumented values.
> This commit updates the manual to mention all the accepted macros,
> along with any values that hold special meaning.
>
> * manual/creature.texi (_POSIX_C_SOURCE): Document special
> values of 199606L, 200112L, and 200809L.
> (_XOPEN_SOURCE): Document special values of 600 and 700.
> (_ISOC11_SOURCE): Document macro.
> (_ATFILE_SOURCE): Likewise.
> (_FORTIFY_SOURCE): Likewise.
>
> ---
> Changes in v2:
> * Refer to base editions of POSIX standards, and mention
> supported subsequent bug-fix editions explicitly.
> * Set @standards for _ATFILE_SOURCE and _FORTIFY_SOURCE to
> GNU.
> * Minor wording changes
> * Rebase to master (post-88f9e739).
>
> ---
> manual/creature.texi | 36 +++++++++++++++++++++++++++++++++++-
> 1 file changed, 35 insertions(+), 1 deletion(-)
OK, but suggested followups:
* In the description of _DEFAULT_SOURCE, note that features from the C
standard version used by the compiler are also enabled by default. (With
GCC 5 and later, which defaults to -std=gnu11, that means C11 features are
enabled, but unlike C99 they aren't part of the 2008 edition of POSIX, so
aren't already included in the description of default features.)
* Remove the statement about C99 not being widely adopted from the
description of _ISOC99_SOURCE. By now, C99 is widely adopted (in the Unix
world; I'm not sure about the state of Microsoft's compiler in that
regard, they've historically been better at keeping up with C++ than with
C).
* Consider obsoleting _ATFILE_SOURCE and making it into an alias for
_POSIX_C_SOURCE = 200809L if _POSIX_C_SOURCE is undefined or has a lower
value (similar to the _REENTRANT obsoletion); I don't think we really need
a separate feature test macro for this subset of POSIX features.
On 08/10/2017 03:26 PM, Joseph Myers wrote:
> OK, but suggested followups:
>
> * In the description of _DEFAULT_SOURCE, note that features from the C
> standard version used by the compiler are also enabled by default. (With
> GCC 5 and later, which defaults to -std=gnu11, that means C11 features are
> enabled, but unlike C99 they aren't part of the 2008 edition of POSIX, so
> aren't already included in the description of default features.)
How would you like that said? That whole paragraph refers to /either/
feature test macros /or/ compiler options, and uses examples of the
latter, so I already read it as implying if you use a specific compiler
option such as -std=gnu11, you get what it entails, along with anything
that is "default":
"defining it together with other feature test macros, or when options
such as @option{-ansi} are used, enables those features even when the
other options would otherwise cause them to be disabled."
Documenting the compiler's defaults is probably out of scope.
> * Remove the statement about C99 not being widely adopted from the
> description of _ISOC99_SOURCE. By now, C99 is widely adopted (in the Unix
> world; I'm not sure about the state of Microsoft's compiler in that
> regard, they've historically been better at keeping up with C++ than with
> C).
How is this:
"@Theglibc{} has a complete implementation of the @w{ISO C99} standard,
and to enable its features, the macro @code{_ISOC99_SOURCE} should be
defined."
> * Consider obsoleting _ATFILE_SOURCE and making it into an alias for
> _POSIX_C_SOURCE = 200809L if _POSIX_C_SOURCE is undefined or has a lower
> value (similar to the _REENTRANT obsoletion); I don't think we really need
> a separate feature test macro for this subset of POSIX features.
As this requires more extensive changes throughout, I'll do this
separately, but I think the other issues can be incorporated in a v3.
Rical
On Fri, 11 Aug 2017, Rical Jasan wrote:
> On 08/10/2017 03:26 PM, Joseph Myers wrote:
> > OK, but suggested followups:
> >
> > * In the description of _DEFAULT_SOURCE, note that features from the C
> > standard version used by the compiler are also enabled by default. (With
> > GCC 5 and later, which defaults to -std=gnu11, that means C11 features are
> > enabled, but unlike C99 they aren't part of the 2008 edition of POSIX, so
> > aren't already included in the description of default features.)
>
> How would you like that said? That whole paragraph refers to /either/
> feature test macros /or/ compiler options, and uses examples of the
> latter, so I already read it as implying if you use a specific compiler
> option such as -std=gnu11, you get what it entails, along with anything
> that is "default":
I read the existing text as saying that certain strict conformance options
*disable* features that would otherwise be enabled by default; nothing
about compiler options serving to *enable* visibility of features not
otherwise listed as present by default.
Maybe more of a rework is needed in this area. It's also the case that
this section of the manual is preferentially referring to the old -ansi
option, when I'd think -std=c11 would be a better example of a standards
conformance option in most places (de-emphasising the use of options for
old standards). Information to include (some is already present)
includes:
* Features from the compiler's language version are enabled, regardless of
any feature test macros passed.
* If you use a strict conformance option, this disables features beyond
those from the compiler's language version, and feature test macros need
to be used to enable them.
* If you don't use a strict conformance option, but you use any C/POSIX
feature test macros, this overrides the default enabling of POSIX.1-2008
features. (The logic for this in features.h actually checks for
_ISOC99_SOURCE but not _ISOC11_SOURCE. That inconsistency should be
fixed, presumably by adding _ISOC99_SOURCE to the conditionals.)
* _ISOC99_SOURCE and _ISOC11_SOURCE are not generally needed; they are
only relevant if you specifically want to add those newer library features
on top of an older language version (e.g. -std=c90 -D_ISOC99_SOURCE).
> "@Theglibc{} has a complete implementation of the @w{ISO C99} standard,
> and to enable its features, the macro @code{_ISOC99_SOURCE} should be
> defined."
I think we only need to comment on the state of the glibc implementation
when it's significantly incomplete (as for various __STDC_WANT_*). It's
more relevant to point out here that there is no need for this macro if
your compiler (+ options) uses C99 or later.
@@ -61,6 +61,20 @@ If you define this macro to a value greater than or equal to @code{199309L},
then the functionality from the 1993 edition of the POSIX.1b standard
(IEEE Standard 1003.1b-1993) is made available.
+If you define this macro to a value greater than or equal to
+@code{199506L}, then the functionality from the 1995 edition of the
+POSIX.1c standard (IEEE Standard 1003.1c-1995) is made available.
+
+If you define this macro to a value greater than or equal to
+@code{200112L}, then the functionality from the 2001 edition of the
+POSIX standard (IEEE Standard 1003.1-2001) is made available, as well
+as bug-fixes from the 2004 edition (IEEE Standard 1003.1-2004).
+
+If you define this macro to a value greater than or equal to
+@code{200809L}, then the functionality from the 2008 edition of the
+POSIX standard (IEEE Standard 1003.1-2008) is made available, as well
+as bug-fixes from the 2013 and 2016 editions.
+
Greater values for @code{_POSIX_C_SOURCE} will enable future extensions.
The POSIX standards process will define these values as necessary, and
@theglibc{} should support them some time after they become standardized.
@@ -87,7 +101,9 @@ available which are necessary for the X/Open Unix brand.
If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes
all functionality described so far plus some new definitions from the
-Single Unix Specification, @w{version 2}.
+Single Unix Specification, @w{version 2}. The value @math{600}
+includes definitions from the sixth revision, and @math{700} includes
+definitions from the seventh revision.
@end defvr
@defvr Macro _LARGEFILE_SOURCE
@@ -156,6 +172,11 @@ implementation of the new standard and to enable the new features the
macro @code{_ISOC99_SOURCE} should be defined.
@end defvr
+@defvr Macro _ISOC11_SOURCE
+@standards{C11, (none)}
+If this macro is defined, ISO C11 extensions to ISO C99 are included.
+@end defvr
+
@defvr Macro __STDC_WANT_LIB_EXT2__
@standards{ISO, (none)}
If you define this macro to the value @code{1}, features from ISO/IEC
@@ -209,6 +230,19 @@ enables those features even when the other options would otherwise
cause them to be disabled.
@end defvr
+@defvr Macro _ATFILE_SOURCE
+@standards{GNU, (none)}
+If this macro is defined, additional @code{*at} interfaces are
+included.
+@end defvr
+
+@defvr Macro _FORTIFY_SOURCE
+@standards{GNU, (none)}
+If this macro is defined to @math{1}, security hardening is added to
+various library functions. If defined to @math{2}, even stricter
+checks are applied.
+@end defvr
+
@defvr Macro _REENTRANT
@defvrx Macro _THREAD_SAFE
@standards{Obsolete, (none)}