diff mbox

manual: Document missing feature test macros.

Message ID 20170727093729.30796-1-ricaljasan@pacific.net
State New
Headers show

Commit Message

Rical Jasan July 27, 2017, 9:37 a.m. UTC
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.
---
 manual/creature.texi | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

Comments

Joseph Myers July 28, 2017, 12:38 a.m. UTC | #1
On Thu, 27 Jul 2017, Rical Jasan wrote:

> +If you define this macro to a value greater than or equal to
> +@code{200112L}, then the functionality from the 2004 edition of the
> +POSIX standard (IEEE Standard 1003.1-2004) is made available.
> +
> +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.

This description is inconsistent.

Both the 2001 and 2008 editions of POSIX had subsequent corrected editions 
incorporating TCs, and the corrections are not distinguished by 
_POSIX_C_SOURCE versions (such bug-fixes to the standard are applied 
unconditionally).  But you're referencing the 2004 corrected version of 
the 2001 edition of POSIX, together with the original 2008 edition rather 
than the 2013 or 2016 bug-fix versions of it.

I think referencing the 2001 and 2008 editions rather than the subsequent 
bug-fix versions is most appropriate (if you want to say the bug-fixes are 
applied, do so separately).

>  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} will
> +include definitions from the sixth revision, and @math{700} will
> +include definitions from the seventh revision.
>  @end defvr

I think this should be "includes" as for the value 500, not "will 
include".
Michael Kerrisk \(man-pages\) Aug. 15, 2017, 6:41 p.m. UTC | #2
On 07/28/2017 02:38 AM, Joseph Myers wrote:
> On Thu, 27 Jul 2017, Rical Jasan wrote:
[...]

>>  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} will
>> +include definitions from the sixth revision, and @math{700} will
>> +include definitions from the seventh revision.
>>  @end defvr
> 
> I think this should be "includes" as for the value 500, not "will 
> include".

Also, this text is inconsistent. On the one hand, it talks about SUSv2,
then it talks about the "sixth revision" and the "seventh revision",
without explaining what those terms mean. Best to rewrite using 
"Single Unix Specification, @w{version 3}" and
"Single Unix Specification, @w{version 4}", I'd say.

Cheers,

Michael
diff mbox

Patch

diff --git a/manual/creature.texi b/manual/creature.texi
index eb30b0118d..37b0fd89d1 100644
--- a/manual/creature.texi
+++ b/manual/creature.texi
@@ -61,6 +61,18 @@  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 2004 edition of the
+POSIX standard (IEEE Standard 1003.1-2004) is made available.
+
+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.
+
 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 +99,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} will
+include definitions from the sixth revision, and @math{700} will
+include definitions from the seventh revision.
 @end defvr
 
 @defvr Macro _LARGEFILE_SOURCE
@@ -156,6 +170,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 +228,19 @@  enables those features even when the other options would otherwise
 cause them to be disabled.
 @end defvr
 
+@defvr Macro _ATFILE_SOURCE
+@standards{???, (none)}
+If this macro is defined, additional @code{*at} interfaces are
+included.
+@end defvr
+
+@defvr Macro _FORTIFY_SOURCE
+@standards{???, (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
 @standardsx{_REENTRANT, GNU, (none)}