mirror of https://github.com/mkerrisk/man-pages
444 lines
13 KiB
Groff
444 lines
13 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" This manpage is Copyright (C) 2006, Michael Kerrisk
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.\"
|
|
.TH FEATURE_TEST_MACROS 7 2006-07-26 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
feature_test_macros \- feature test macros
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <features.h>
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Feature test macros allow the programmer to control the definitions that
|
|
are exposed by system header files when a program is compiled.
|
|
This can be useful for creating portable applications,
|
|
by preventing non-standard definitions from being exposed.
|
|
Other macros can be used to expose non-standard definitions that
|
|
are not exposed by default.
|
|
The precise effects of each of the feature test macros described below
|
|
can be ascertained by inspecting the
|
|
.I <features.h>
|
|
header file.
|
|
|
|
In order to be effective, a feature test macro
|
|
.IR "must be defined before including any header files" .
|
|
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 typically includes a note of the following form
|
|
(this example from the
|
|
.BR chmod (2)
|
|
manual page):
|
|
.RS
|
|
.sp
|
|
.B #include <sys/stat.h>
|
|
.sp
|
|
.BI "int chmod(const char *" path ", mode_t " mode );
|
|
.br
|
|
.BI "int fchmod(int " fd ", 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
|
|
|
|
#define _BSD_SOURCE
|
|
#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,
|
|
.BR "some feature test macros are defined by default" ,
|
|
so that it may not always be necessary to
|
|
explicitly specify the feature test macro(s) shown in the
|
|
SYNOPSIS.
|
|
|
|
In a few cases, manual pages use a shorthand for expressing the
|
|
feature test macro requirements (this example from
|
|
.BR readahead (2)):
|
|
.RS
|
|
.nf
|
|
|
|
.B #define _GNU_SOURCE
|
|
.B #include <fcntl.h>
|
|
.sp
|
|
.BI "ssize_t readahead(int " fd ", off64_t *" offset ", size_t " count );
|
|
.fi
|
|
.RE
|
|
.PP
|
|
This format is employed in cases where only a single
|
|
feature test macro can be used to expose the function
|
|
declaration, and that macro is not defined by default.
|
|
.SS Feature test macros understood by glibc
|
|
The following paragraphs explain how feature test macros are handled
|
|
in Linux glibc 2.\fIx\fP, \fIx\fP > 0.
|
|
.\" The details in glibc 2.0 are simpler, but combining a
|
|
.\" a description of them with the details in later glibc versions
|
|
.\" would make for a complicated description.
|
|
|
|
Linux glibc understands the following feature test macros:
|
|
.TP
|
|
.B __STRICT_ANSI__
|
|
ISO Standard C.
|
|
This macro is implicitly defined by
|
|
.BR gcc (1)
|
|
when invoked with, for example, the
|
|
.I -std=c99
|
|
or
|
|
.I -ansi
|
|
flag.
|
|
.TP
|
|
.B _POSIX_C_SOURCE
|
|
Defining this macro causes header files to expose definitions as follows:
|
|
.RS
|
|
.IP \(bu 3
|
|
The value 1 exposes definitions conforming to POSIX.1-1990 and
|
|
ISO C (1990).
|
|
.IP \(bu
|
|
The value 2 or greater additionally exposes
|
|
definitions for POSIX.2-1992.
|
|
.IP \(bu
|
|
The value 199309L or greater additionally exposes
|
|
definitions for POSIX.1b (real-time extensions).
|
|
.\" 199506L functionality is only available since glibc 2.1
|
|
.IP \(bu
|
|
The value 199506L or greater additionally exposes
|
|
definitions for POSIX.1c (threads).
|
|
.IP \(bu
|
|
(Since glibc 2.3.3)
|
|
The value 200112L or greater exposes definitions corresponding
|
|
to the POSIX.1-2001 base specification (excluding the XSI extension).
|
|
.RE
|
|
.TP
|
|
.B _POSIX_SOURCE
|
|
Defining this obsolete macro with any value is equivalent to defining
|
|
.B _POSIX_C_SOURCE
|
|
with the value 1.
|
|
.TP
|
|
.B _XOPEN_SOURCE
|
|
Defining this macro causes header files to expose definitions as follows:
|
|
.RS
|
|
.IP \(bu 3
|
|
Defining with any value exposes
|
|
definitions conforming to POSIX.1, POSIX.2, and XPG4.
|
|
.IP \(bu
|
|
The value 500 or greater additionally exposes
|
|
definitions for SUSv2 (UNIX 98).
|
|
.IP \(bu
|
|
(Since glibc 2.2) 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 C99 definitions.
|
|
.RE
|
|
.TP
|
|
.B _XOPEN_SOURCE_EXTENDED
|
|
If this macro is defined, and
|
|
.B _XOPEN_SOURCE
|
|
is defined, then expose definitions corresponding to the XPG4v2
|
|
(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 C99 extensions to ISO C (1990).
|
|
This macro is recognized since glibc 2.1.3;
|
|
earlier glibc 2.1.x versions recognized an equivalent macro named
|
|
.B _ISOC9X_SOURCE
|
|
(because the C99 standard had not then been finalized).
|
|
Although the use of the latter macro is obsolete, glibc continues
|
|
to recognize it for backwards compatibility.
|
|
.TP
|
|
.B _LARGEFILE64_SOURCE
|
|
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
|
|
.I _FILE_OFFSET_BITS=64
|
|
should be employed.
|
|
.TP
|
|
.B _FILE_OFFSET_BITS
|
|
Defining this macro with the value 64
|
|
automatically converts references to 32-bit functions and data types
|
|
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 causes header files to expose
|
|
BSD-derived definitions.
|
|
Defining this macro also causes BSD definitions to be preferred in
|
|
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
|
|
.B _GNU_SOURCE
|
|
is defined, in which case BSD definitions are disfavored.
|
|
.TP
|
|
.B _SVID_SOURCE
|
|
Defining this macro with any value causes header files to expose
|
|
System V-derived definitions.
|
|
(SVID == System V Interface Definition; see
|
|
.BR standards (7).)
|
|
.TP
|
|
.BR _ATFILE_SOURCE " (since glibc 2.4)"
|
|
Defining this macro with any value causes header files to expose
|
|
declarations of a range of functions with the suffix "at";
|
|
see
|
|
.BR openat (2).
|
|
.TP
|
|
.B _GNU_SOURCE
|
|
Defining this macro (with any value) is equivalent to defining
|
|
.BR _BSD_SOURCE ,
|
|
.BR _SVID_SOURCE ,
|
|
.BR _ATFILE_SOURCE ,
|
|
.BR _LARGEFILE64_SOURCE ,
|
|
.BR _ISOC99_SOURCE ,
|
|
.BR _XOPEN_SOURCE_EXTENDED ,
|
|
.BR _POSIX_SOURCE ,
|
|
.B _POSIX_C_SOURCE
|
|
with the value 200112L (199506L in glibc versions before 2.5),
|
|
.\" 199309L in glibc versions before 2.1
|
|
and
|
|
.B _XOPEN_SOURCE
|
|
with the value 600 (500 in glibc versions before 2.2).
|
|
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.
|
|
For multithreaded programs, use
|
|
.I "cc -pthread"
|
|
instead.
|
|
.TP
|
|
.B _THREAD_SAFE
|
|
Synonym for
|
|
.BR _REENTRANT ,
|
|
provided for compatibility with some other implementations.
|
|
.TP
|
|
.BR _FORTIFY_SOURCE " (since glibc 2.3.4)"
|
|
.\" For more detail, see:
|
|
.\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html
|
|
.\" [PATCH] Object size checking to prevent (some) buffer overflows
|
|
.\" * From: Jakub Jelinek <jakub at redhat dot com>
|
|
.\" * To: gcc-patches at gcc dot gnu dot org
|
|
.\" * Date: Tue, 21 Sep 2004 04:16:40 -0400
|
|
Defining this macro causes some lightweight checks to be performed
|
|
to detect some buffer overflow errors when employing
|
|
various string and memory manipulation functions.
|
|
Not all buffer overflows are detected, just some common cases.
|
|
In the current implementation checks are added for
|
|
calls to
|
|
.BR memcpy (3),
|
|
.BR mempcpy (3),
|
|
.BR memmove (3),
|
|
.BR memset (3),
|
|
.BR stpcpy (3),
|
|
.BR strcpy (3),
|
|
.BR strncpy (3),
|
|
.BR strcat (3),
|
|
.BR strncat (3),
|
|
.BR sprintf (3),
|
|
.BR snprintf (3),
|
|
.BR vsprintf (3),
|
|
.BR vsnprintf (3),
|
|
and
|
|
.BR gets (3).
|
|
If
|
|
.B _FORTIFY_SOURCE
|
|
is set to 1, with compiler optimization level 1
|
|
.RI ( "gcc -O1" )
|
|
and above, checks that shouldn't change the behavior of
|
|
conforming programs are performed.
|
|
With
|
|
.B _FORTIFY_SOURCE
|
|
set to 2 some more checking is added, but
|
|
some conforming programs might fail.
|
|
Some of the checks can be performed at compile time,
|
|
and result in compiler warnings;
|
|
other checks take place at run time,
|
|
and result in a run-time error if the check fails.
|
|
Use of this macro requires compiler support, available with
|
|
.BR gcc (1)
|
|
since version 4.0.
|
|
.SS Default definitions, implicit definitions, and combining definitions
|
|
.PP
|
|
If no feature test macros are explicitly defined,
|
|
then the following feature test macros are defined by default:
|
|
.BR _BSD_SOURCE ,
|
|
.BR _SVID_SOURCE ,
|
|
.BR _POSIX_SOURCE ,
|
|
and
|
|
.BR _POSIX_C_SOURCE =200112L
|
|
(199506L in glibc versions before 2.4).
|
|
.\" 199309L in glibc versions before 2.1.
|
|
.PP
|
|
If any of
|
|
.BR __STRICT_ANSI__ ,
|
|
.BR _ISOC99_SOURCE ,
|
|
.BR _POSIX_SOURCE ,
|
|
.BR _POSIX_C_SOURCE ,
|
|
.BR _XOPEN_SOURCE ,
|
|
.BR _XOPEN_SOURCE_EXTENDED ,
|
|
.BR _BSD_SOURCE ,
|
|
or
|
|
.B _SVID_SOURCE
|
|
is explicitly defined, then
|
|
.BR _BSD_SOURCE ,
|
|
and
|
|
.B _SVID_SOURCE
|
|
are not defined by default.
|
|
|
|
If
|
|
.B _POSIX_SOURCE
|
|
and
|
|
.B _POSIX_C_SOURCE
|
|
are not explicitly defined,
|
|
and either
|
|
.B __STRICT_ANSI__
|
|
is not defined or
|
|
.B _XOPEN_SOURCE
|
|
is defined with a value of 500 or more, then
|
|
.RS 6
|
|
.IP * 3
|
|
.B _POSIX_SOURCE
|
|
is defined with the value 1; and
|
|
.IP *
|
|
.B _POSIX_C_SOURCE
|
|
is defined with one of the following values:
|
|
.RS 6
|
|
.IP \(bu 3
|
|
2,
|
|
if
|
|
.B XOPEN_SOURCE
|
|
is defined with a value less than 500;
|
|
.IP \(bu
|
|
199506L,
|
|
if
|
|
.B XOPEN_SOURCE
|
|
is defined with a value greater than or equal to 500 and less than 600;
|
|
or
|
|
.IP \(bu
|
|
200112L (199506L in glibc versions before 2.4),
|
|
if
|
|
.B XOPEN_SOURCE
|
|
is undefined, or
|
|
is defined with a value greater than or equal to 600.
|
|
.RE
|
|
.RE
|
|
.PP
|
|
Multiple macros can be defined; the results are additive.
|
|
.SH CONFORMING TO
|
|
POSIX.1 specifies
|
|
.BR _POSIX_C_SOURCE ,
|
|
.BR _POSIX_SOURCE ,
|
|
and
|
|
.BR _XOPEN_SOURCE .
|
|
.B _XOPEN_SOURCE_EXTENDED
|
|
was specified by XPG4v2 (aka SUSv1).
|
|
|
|
.B _FILE_OFFSET_BITS
|
|
is not specified by any standard,
|
|
but is employed on some other implementations.
|
|
|
|
.BR _BSD_SOURCE ,
|
|
.BR _SVID_SOURCE ,
|
|
.BR _ATFILE_SOURCE ,
|
|
.BR _GNU_SOURCE ,
|
|
.BR _FORTIFY_SOURCE ,
|
|
.BR _REENTRANT ,
|
|
and
|
|
.B _THREAD_SAFE
|
|
are specific to Linux (glibc).
|
|
.SH NOTES
|
|
.I <features.h>
|
|
is a Linux/glibc-specific header file.
|
|
Other systems have an analogous file, but typically with a different name.
|
|
This header file is automatically included by other header files as
|
|
required: it is not necessary to explicitly include it in order to
|
|
employ feature test macros.
|
|
|
|
According to which of the above feature test macros are defined,
|
|
.I <features.h>
|
|
internally defines various other macros that are checked by
|
|
other glibc header files.
|
|
These macros have names prefixed by two underscores (e.g.,
|
|
.BR __USE_MISC ).
|
|
Programs should \fInever\fP define these macros directly:
|
|
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
|