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>
This commit is contained in:
Michael Kerrisk 2010-09-10 06:33:31 +02:00
parent fbea0f8160
commit e417acb023
10 changed files with 55 additions and 17 deletions

View File

@ -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.

View File

@ -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).

View File

@ -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

View File

@ -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).

View File

@ -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

View File

@ -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).

View File

@ -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 .

View File

@ -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

View File

@ -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

View File

@ -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.