Message ID | 20170728034305.13389-1-ricaljasan@pacific.net |
---|---|
State | New |
Headers | show |
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.
diff --git a/manual/creature.texi b/manual/creature.texi index 96f8ee0a0c..b8c194f87c 100644 --- a/manual/creature.texi +++ b/manual/creature.texi @@ -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)}