fcntl.2, intro.2, open.2, poll.2, ftw.3, intro.3, matherr.3, system.3, tmpnam.3, unix.7: Note that feature test macros must be defined before *any* includes

Programmers often make the mistake of including a feature test
macro only after having already included some header files.
This patch adds some text at opportune places to remind
programmers to do things the right way.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

10 files changed, 55 insertions, 17 deletions

diff --git a/man2/fcntl.2 b/man2/fcntl.2
index b01d3239..d096e06e 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -58,7 +58,7 @@
 .\" 2010-06-17, Michael Kerrisk
 .\"	Document F_SETPIPE_SZ and F_GETPIPE_SZ.
 .\"
-.TH FCNTL 2 2010-06-19 "Linux" "Linux Programmer's Manual"
+.TH FCNTL 2 2010-09-10 "Linux" "Linux Programmer's Manual"
 .SH NAME
 fcntl \- manipulate file descriptor
 .SH SYNOPSIS
@@ -947,7 +947,9 @@ The attributes of a file were changed (chown, chmod, utime[s]).
 .IP
 (In order to obtain these definitions, the
 .B _GNU_SOURCE
-feature test macro must be defined.)
+feature test macro must be defined before including
+.I any
+header files.)
 
 Directory notifications are normally "one-shot", and the application
 must reregister to receive further notifications.
diff --git a/man2/intro.2 b/man2/intro.2
index 10cf9163..7e4e669a 100644
--- a/man2/intro.2
+++ b/man2/intro.2
@@ -24,7 +24,7 @@
 .\"     new _syscall(2) page, and substantially enhanced and rewrote
 .\"     the remaining material on this page.
 .\"
-.TH INTRO 2 2010-02-03 "Linux" "Linux Programmer's Manual"
+.TH INTRO 2 2010-09-10 "Linux" "Linux Programmer's Manual"
 .SH NAME
 intro \- Introduction to system calls
 .SH DESCRIPTION
@@ -59,6 +59,9 @@ In some cases,
 the programmer must define a feature test macro in order to obtain
 the declaration of a system call from the header file specified
 in the man page SYNOPSIS section.
+(Where required, these feature test macros must be defined before including
+.I any
+header files.)
 In such cases, the required macro is described in the man page.
 For further information on feature test macros, see
 .BR feature_test_macros (7).
diff --git a/man2/open.2 b/man2/open.2
index a2fef475..33b9b5e7 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -48,7 +48,7 @@
 .\" O_TTYINIT.  Eventually these may need to be documented.  --mtk
 .\" FIXME Linux 2.6.33 has O_DSYNC, and a hiddden __O_SYNC.
 .\"
-.TH OPEN 2 2010-06-14 "Linux" "Linux Programmer's Manual"
+.TH OPEN 2 2010-09-10 "Linux" "Linux Programmer's Manual"
 .SH NAME
 open, creat \- open and possibly create a file or device
 .SH SYNOPSIS
@@ -364,7 +364,11 @@ Allow files whose sizes cannot be represented in an
 to be opened.
 The
 .B _LARGEFILE64_SOURCE
-macro must be defined in order to obtain this definition.
+macro must be defined
+(before including
+.I any
+header files)
+in order to obtain this definition.
 Setting the
 .B _FILE_OFFSET_BITS
 feature test macro to 64 (rather than using
@@ -602,6 +606,9 @@ and
 .B O_NOFOLLOW
 flags are Linux-specific, and one may need to define
 .B _GNU_SOURCE
+(before including
+.I any
+header files)
 to obtain their definitions.
 
 The
@@ -612,6 +619,9 @@ but is specified in POSIX.1-2008.
 .B O_DIRECT
 is not specified in POSIX; one has to define
 .B _GNU_SOURCE
+(before including
+.I any
+header files)
 to get its definition.
 .SH NOTES
 Under Linux, the
diff --git a/man2/poll.2 b/man2/poll.2
index a3bd6205..5e37e43c 100644
--- a/man2/poll.2
+++ b/man2/poll.2
@@ -133,7 +133,11 @@ Stream socket peer closed connection,
 or shut down writing half of connection.
 The
 .B _GNU_SOURCE
-feature test macro must be defined in order to obtain this definition.
+feature test macro must be defined
+(before including
+.I any
+header files)
+in order to obtain this definition.
 .TP
 .B POLLERR
 Error condition (output only).
diff --git a/man3/ftw.3 b/man3/ftw.3
index 7ab9c18e..f3f06886 100644
--- a/man3/ftw.3
+++ b/man3/ftw.3
@@ -202,7 +202,11 @@ Other return values could be associated with new actions in the future;
 
 The feature test macro
 .B _GNU_SOURCE
-must be defined in order to
+must be defined
+(before including
+.I any
+header files)
+in order to
 obtain the definition of \fBFTW_ACTIONRETVAL\fP from \fI<ftw.h>\fP.
 .RE
 .TP
diff --git a/man3/intro.3 b/man3/intro.3
index 119bc5b5..fe681177 100644
--- a/man3/intro.3
+++ b/man3/intro.3
@@ -21,7 +21,7 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
 .\" 2007-10-23 mtk, Nearly a complete rewrite of the earlier page.
-.TH INTRO 3 2010-02-03 "Linux" "Linux Programmer's Manual"
+.TH INTRO 3 2010-09-10 "Linux" "Linux Programmer's Manual"
 .SH NAME
 intro \- Introduction to library functions
 .SH DESCRIPTION
@@ -50,6 +50,9 @@ In some cases,
 the programmer must define a feature test macro in order to obtain
 the declaration of a function from the header file specified
 in the man page SYNOPSIS section.
+(Where required, these feature test macros must be defined before including
+.I any
+header files.)
 In such cases, the required macro is described in the man page.
 For further information on feature test macros, see
 .BR feature_test_macros (7).
diff --git a/man3/matherr.3 b/man3/matherr.3
index 5b94f167..9155271b 100644
--- a/man3/matherr.3
+++ b/man3/matherr.3
@@ -22,7 +22,7 @@
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
 .\"
-.TH MATHERR 3 2008-07-21 "Linux" "Linux Programmer's Manual"
+.TH MATHERR 3 2010-09-10 "Linux" "Linux Programmer's Manual"
 .SH NAME
 matherr \- SVID math library exception handling
 .SH SYNOPSIS
@@ -62,7 +62,11 @@ To employ
 .BR matherr (),
 the programmer must define the
 .B _SVID_SOURCE
-feature test macro, and assign the value
+feature test macro
+(before including
+.I any
+header files),
+and assign the value
 .B _SVID_
 to the external variable
 .BR _LIB_VERSION .
diff --git a/man3/system.3 b/man3/system.3
index fc5512a4..ee1edfc9 100644
--- a/man3/system.3
+++ b/man3/system.3
@@ -25,7 +25,7 @@
 .\" Modified 14 May 2001, 23 Sep 2001 by aeb
 .\" 2004-12-20, mtk
 .\"
-.TH SYSTEM 3  2004-12-20 "" "Linux Programmer's Manual"
+.TH SYSTEM 3  2010-09-10 "" "Linux Programmer's Manual"
 .SH NAME
 system \- execute a shell command
 .SH SYNOPSIS
@@ -79,7 +79,11 @@ C89, C99, POSIX.1-2001.
 .PP
 If the
 .B _XOPEN_SOURCE
-feature test macro is defined, then the macros described in
+feature test macro is defined
+(before including
+.I any
+header files),
+then the macros described in
 .BR wait (2)
 .RB ( WEXITSTATUS (),
 etc.) are made available when including
diff --git a/man3/tmpnam.3 b/man3/tmpnam.3
index 7f29e366..82234aae 100644
--- a/man3/tmpnam.3
+++ b/man3/tmpnam.3
@@ -22,7 +22,7 @@
 .\"
 .\" 2003-11-15, aeb, added tmpnam_r
 .\"
-.TH TMPNAM 3  2008-08-06 "" "Linux Programmer's Manual"
+.TH TMPNAM 3  2010-09-10 "" "Linux Programmer's Manual"
 .SH NAME
 tmpnam, tmpnam_r \- create a name for a temporary file
 .SH SYNOPSIS
@@ -132,13 +132,15 @@ tmpnam_r(char *s)
 .sp
 apparently as a warning not to use NULL.
 A few systems implement it.
-To get a glibc prototype for this function,
+To get a glibc prototype for this function from
+.IR <stdio.h> ,
 define
 .B _SVID_SOURCE
 or
 .B _BSD_SOURCE
-before including
-.IR <stdio.h> .
+(before including
+.I any
+header file).
 .SH BUGS
 Never use this function.
 Use
diff --git a/man7/unix.7 b/man7/unix.7
index b891905d..a397a9df 100644
--- a/man7/unix.7
+++ b/man7/unix.7
@@ -235,7 +235,9 @@ struct ucred {
 
 Since glibc 2.8, the
 .B _GNU_SOURCE
-feature test macro must be defined in order to obtain the definition
+feature test macro must be defined (before including
+.I any
+header files) in order to obtain the definition
 of this structure.
 
 The credentials which the sender specifies are checked by the kernel.