Added note about how feature test macros are specified in manual pages.

Other corrections, improvements, and additions.

man7/feature_test_macros.7

@@ -23,7 +23,7 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
 .\"
-.TH FEATURE_TEST_MACROS 7 2006-04-26 "Linux" "Linux Programmer's Manual"
+.TH FEATURE_TEST_MACROS 7 2006-07-26 "Linux" "Linux Programmer's Manual"
 .SH NAME
 feature_test_macros \- feature test macros
 .SH SYNOPSIS
@@ -47,18 +47,71 @@ This can either be done in the compilation command
 .RI ( "cc \-DMACRO=value" )
 or by defining the macro within the source code before
 including any headers.
+.SS Specification of feature test macro requirements in manual pages
+When a function requires that a feature test macro is defined,
+the manual page SYNOPSIS includes a note of the following form
+(this example from the
+.BR chmod (2)
+man page):
+.RS
+.sp
+.B #include <sys/stat.h>
+.sp
+.BI "int chmod(const char *" path ", mode_t " mode );
+.br
+.BI "int fchmod(int " fildes ", mode_t " mode );
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR fchmod ():
+_BSD_SOURCE || _XOPEN_SOURCE >= 500
+.RE
+.PP
+The \fB||\fP means that in order to obtain the declaration of
+.BR fchmod (2)
+from
+.IR <sys/stat.h> ,
+\fIeither\fP of the following macro
+definitions must be made before including any header files:
+.RS
+.nf							   
 
+.B #define _BSD_SOURCE
+.BR "#define _XOPEN_SOURCE 500" "     /* or any value > 500 */"
+.fi
+.RE
+.PP
+Alternatively, equivalent definitions can be included in the
+compilation command:
+.RS
+.nf							   
+
+cc -D_BSD_SOURCE
+cc -D_XOPEN_SOURCE=500        # Or any value > 500
+.fi
+.RE
+.PP
+Note that, as described below, some feature test macros are
+defined be default, so that it may not always be necessary to
+explicitly specify the feature test macro(s) shown
+in the SYNOPSIS.
+.SS Feature test macros understood by glibc
 Linux/glibc understands the following feature test macros:
 .\" FIXME ? add _ATFILE_SOURCE to this list
 .TP
 .B _POSIX_C_SOURCE
 Defining this macro with the value 1 causes header files to expose
 definitions conforming to POSIX.1-1990 and ISO C (1990).
-Defining with the value 199309 or greater additionally exposes
+Defining with the value L or greater additionally exposes
+definitions for POSIX.2-1992.
+Defining with the value 199309L or greater additionally exposes
 definitions for POSIX.1b (real-time extensions).
-Defining with the value 199506 or greater additionally exposes
+Defining with the value 199506L or greater additionally exposes
 definitions for POSIX.1c (threads).
-Defining with the value 200112 exposes definitions corresponding
+Defining with the value 200112L exposes definitions corresponding
 to the POSIX.1-2001 base specification (excluding the XSI extension).
 .TP
 .B _POSIX_SOURCE
@@ -74,12 +127,28 @@ definitions for SUSv2 (UNIX 98).
 Defining with the value 600 or greater additionally exposes
 definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification
 plus the XSI extension) and C 99 definitions.
+.IP
+Defining
+.B _XOPEN_SOURCE
+also implicitly defines
+.BR _POSIX_C_SOURCE :
+with the value 2, if
+.B _XOPEN_SOURCE
+is less than 500;
+with the value 199506L, if 500 <=
+.B _XOPEN_SOURCE
+< 600; or with the value 200112L if
+.B _XOPEN_SOURCE
+>= 600.
 .TP
 .B _XOPEN_SOURCE_EXTENDED
 If this macro is defined with the value 1, and the
 .BR _XOPEN_SOURCE
 is defined, then expose definitions corresponding to the XPG4v2
-UNIX extensions.
+(SUSv1) UNIX extensions (UNIX 95).
+This macro is also implicitly defined if
+.B _XOPEN_SOURCE
+is defined with a value of 500 or more.
 .TP
 .B _ISOC99_SOURCE
 Exposes C 99 extensions to ISO C (1990).
@@ -89,6 +158,19 @@ Expose definitions for the alternative API specified by the
 LFS (Large File Summit) as a "transitional extension" to the
 Single UNIX Specification.
 (See http://opengroup.org/platform/lfs.html.)
+The alternative API consists of a set of new objects
+(i.e., functions and types) whose names are suffixed with "64"
+(e.g.,
+.I off64_t
+versus
+.IR off_t ,
+.BR lseek64 ()
+versus
+.BR lseek (),
+etc.).
+New programs should not employ this interface; instead
+.IR _FILE_OFFSET_BITS=64
+should be employed.
 .TP
 .B _FILE_OFFSET_BITS
 Defining this macro with the value 64
@@ -97,12 +179,24 @@ related to file I/O and file system operations into references to
 their 64-bit counterparts.
 This is useful for performing I/O on large files (> 2 Gigabytes)
 on 32-bit systems.
+(Defining this macro permits correctly written programs to use
+large files with only a recompilation being required.)
+64-bit systems naturally permit file sizes greater than 2 Gigabytes,
+and on those systems this macro has no effect.
 .TP
 .B _BSD_SOURCE
 Defining this macro with any value cause header files to expose
 BSD-derived definitions.
 Defining this macro also causes BSD definitions to be preferred in
-some situations where standards conflict.
+some situations where standards conflict, unless one or more of
+.BR _SVID_SOURCE ,
+.BR _POSIX_SOURCE ,
+.BR _POSIX_C_SOURCE ,
+.BR _XOPEN_SOURCE ,
+.BR _XOPEN_SOURCE_EXTENDED ,
+or
+.BR _GNU_SOURCE
+is defined, in which case BSD definitions are disfavored.
 .TP
 .B _SVID_SOURCE
 Defining this macro with any value cause header files to expose
@@ -117,11 +211,11 @@ Defining this macro (with any value) is equivalent to defining
 .BR _LARGEFILE64_SOURCE ,
 .BR _ISOC99_SOURCE
 .BR _POSIX_C_SOURCE
-with the value 1999506,
-and
+with the value 200112L, and
 .BR _XOPEN_SOURCE
 with the value 600.
 In addition, various GNU-specific extensions are also exposed.
+Where standards conflict, BSD definitions are disfavored.
 .TP
 .B _REENTRANT
 Defining this macro exposes definitions of certain reentrant functions.
@@ -187,14 +281,14 @@ is invoked, the following macros are defined by default:
 .BR _SVID_SOURCE ,
 .BR _POSIX_SOURCE ,
 and
-.BR _POSIX_C_SOURCE =199506.
+.BR _POSIX_C_SOURCE =199506L.
 If individual macros are defined, then other macros are disabled
 unless they are also explicitly defined.
 (Exception: if
 .BR _POSIX_C_SOURCE
 is not otherwise defined,
-then it is always defined with the value 200112
-(199506 in glibc versions before 2.4),
+then it is always defined with the value 200112L
+(199506L in glibc versions before 2.4),
 unless the compiler is invoked in one of its standard modes, for example, the
 .I -std=c99
 flag.)
@@ -218,6 +312,7 @@ but is employed on some other implementations.
 and
 .BR _THREAD_SAFE
 are Linux (glibc) specific.
+.\" FIXME ? add _ATFILE_SOURCE to this list
 .SH NOTES
 .I <features.h>
 is a Linux/glibc specific header file.
@@ -236,3 +331,9 @@ instead, the appropriate feature test macro(s) from the
 list above should be employed.
 .SH SEE ALSO
 .BR standards (7)
+.sp
+The section "Feature Test Macros" under
+.IR "info libc" .
+.\" But beware: the info libc document is out of date (Jul 07, mtk)
+.sp
+.I /usr/include/features.h