2006-04-21 06:47:08 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-04-21 06:47:08 +00:00
|
|
|
.\" 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.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2006-04-21 06:47:08 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\"
|
2006-05-15 09:13:10 +00:00
|
|
|
.TH FEATURE_TEST_MACROS 7 2006-04-26 "Linux" "Linux Programmer's Manual"
|
2006-04-21 06:47:08 +00:00
|
|
|
.SH NAME
|
2006-05-15 09:13:10 +00:00
|
|
|
feature_test_macros \- feature test macros
|
2006-04-21 06:47:08 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <features.h>
|
|
|
|
.SH DESCRIPTION
|
|
|
|
Feature test macros allow the programmer to control the definitions that
|
|
|
|
are exposed by system header files when a program is compiled.
|
2007-04-12 22:42:49 +00:00
|
|
|
This can be useful for creating portable applications,
|
2006-04-21 06:47:08 +00:00
|
|
|
by preventing non-standard definitions from being exposed.
|
|
|
|
Other macros can be used to expose non-standard definitions that
|
|
|
|
are not exposed by default.
|
2007-04-12 22:42:49 +00:00
|
|
|
The precise effects of each of the feature test macros described below
|
2006-04-21 06:47:08 +00:00
|
|
|
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
|
2007-05-01 07:57:14 +00:00
|
|
|
.RI ( "cc \-DMACRO=value" )
|
2007-04-12 22:42:49 +00:00
|
|
|
or by defining the macro within the source code before
|
2006-04-21 06:47:08 +00:00
|
|
|
including any headers.
|
|
|
|
|
|
|
|
Linux/glibc understands the following feature test macros:
|
|
|
|
.TP
|
|
|
|
.B _POSIX_C_SOURCE
|
2007-04-12 22:42:49 +00:00
|
|
|
Defining this macro with the value 1 causes header files to expose
|
2006-04-21 06:47:08 +00:00
|
|
|
definitions conforming to POSIX.1-1990 and ISO C (1990).
|
2007-04-12 22:42:49 +00:00
|
|
|
Defining with the value 199309 or greater additionally exposes
|
2006-04-21 06:47:08 +00:00
|
|
|
definitions for POSIX.1b (real-time extensions).
|
2007-04-12 22:42:49 +00:00
|
|
|
Defining with the value 199506 or greater additionally exposes
|
2006-04-21 06:47:08 +00:00
|
|
|
definitions for POSIX.1c (threads).
|
2007-04-12 22:42:49 +00:00
|
|
|
Defining with the value 200112 exposes definitions corresponding
|
2006-04-21 06:47:08 +00:00
|
|
|
to the POSIX.1-2001 base specification (excluding the XSI extension).
|
2007-04-12 22:42:49 +00:00
|
|
|
.TP
|
2006-05-15 09:05:26 +00:00
|
|
|
.B _POSIX_SOURCE
|
2006-04-21 06:47:08 +00:00
|
|
|
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 with any value causes header files to expose
|
|
|
|
definitions conforming to POSIX.1, POSIX.2, and XPG4.
|
|
|
|
Defining with the value 500 or greater additionally exposes
|
|
|
|
definitions for SUSv2 (UNIX 98).
|
|
|
|
Defining with the value 600 or greater additionally exposes
|
2007-04-12 22:42:49 +00:00
|
|
|
definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification
|
2006-04-21 06:47:08 +00:00
|
|
|
plus the XSI extension) and C 99 definitions.
|
|
|
|
.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.
|
|
|
|
.TP
|
|
|
|
.B _ISOC99_SOURCE
|
2006-04-21 07:01:40 +00:00
|
|
|
Exposes C 99 extensions to ISO C (1990).
|
2006-04-21 06:47:08 +00:00
|
|
|
.TP
|
|
|
|
.B _LARGEFILE64_SOURCE
|
2007-04-12 22:42:49 +00:00
|
|
|
Expose definitions for the alternative API specified by the
|
|
|
|
LFS (Large File Summit) as a "transitional extension" to the
|
|
|
|
Single UNIX Specification.
|
2006-11-25 20:20:25 +00:00
|
|
|
(See http://opengroup.org/platform/lfs.html.)
|
2006-04-21 06:47:08 +00:00
|
|
|
.TP
|
|
|
|
.B _FILE_OFFSET_BITS
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2006-04-21 06:47:08 +00:00
|
|
|
their 64-bit counterparts.
|
|
|
|
This is useful for performing I/O on large files (> 2 Gigabytes)
|
|
|
|
on 32-bit systems.
|
|
|
|
.TP
|
|
|
|
.B _BSD_SOURCE
|
2007-04-12 22:42:49 +00:00
|
|
|
Defining this macro with any value cause header files to expose
|
2006-04-21 06:47:08 +00:00
|
|
|
BSD-derived definitions.
|
|
|
|
Defining this macro also causes BSD definitions to be preferred in
|
|
|
|
some situations where standards conflict.
|
|
|
|
.TP
|
|
|
|
.B _SVID_SOURCE
|
2007-04-12 22:42:49 +00:00
|
|
|
Defining this macro with any value cause header files to expose
|
|
|
|
System V-derived definitions.
|
2006-08-03 13:58:08 +00:00
|
|
|
(SVID == System V Interface Definition; see
|
|
|
|
.BR standards (7).)
|
2006-04-21 06:47:08 +00:00
|
|
|
.TP
|
|
|
|
.B _GNU_SOURCE
|
|
|
|
Defining this macro (with any value) is equivalent to defining
|
|
|
|
.BR _BSD_SOURCE ,
|
|
|
|
.BR _SVID_SOURCE ,
|
|
|
|
.BR _LARGEFILE64_SOURCE ,
|
|
|
|
.BR _ISOC99_SOURCE
|
|
|
|
.BR _POSIX_C_SOURCE
|
|
|
|
with the value 1999506,
|
|
|
|
and
|
|
|
|
.BR _XOPEN_SOURCE
|
|
|
|
with the value 600.
|
|
|
|
In addition, various GNU-specific extensions are also exposed.
|
2007-01-28 19:30:54 +00:00
|
|
|
.TP
|
|
|
|
.B _REENTRANT
|
|
|
|
Defining this macro exposes definitions of certain reentrant functions.
|
2007-02-01 06:11:02 +00:00
|
|
|
For multithreaded programs, use
|
2007-01-28 19:30:54 +00:00
|
|
|
.I "cc -pthread"
|
|
|
|
instead.
|
|
|
|
.TP
|
|
|
|
.B _THREAD_SAFE
|
2007-04-12 22:42:49 +00:00
|
|
|
Synonym for
|
2007-01-28 19:30:54 +00:00
|
|
|
.BR _REENTRANT ,
|
|
|
|
provided for compatibility with some other implementations.
|
|
|
|
.TP
|
|
|
|
.B _FORTIFY_SOURCE
|
|
|
|
.\" 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
|
2007-04-12 22:42:49 +00:00
|
|
|
calls to
|
2007-01-28 19:30:54 +00:00
|
|
|
.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),
|
2007-04-12 22:42:49 +00:00
|
|
|
and
|
2007-01-28 19:30:54 +00:00
|
|
|
.BR gets (3).
|
2007-04-12 22:42:49 +00:00
|
|
|
If
|
|
|
|
.B _FORTIFY_SOURCE
|
|
|
|
is set to 1, with compiler optimization level 1
|
2007-01-28 19:30:54 +00:00
|
|
|
.RI ( "gcc -O1" )
|
2007-06-08 09:56:56 +00:00
|
|
|
and above, checks that shouldn't change the behavior of
|
2007-01-28 19:30:54 +00:00
|
|
|
conforming programs are performed.
|
2007-04-12 22:42:49 +00:00
|
|
|
With
|
|
|
|
.B _FORTIFY_SOURCE
|
2007-01-28 19:30:54 +00:00
|
|
|
set to 2 some more checking is added, but
|
|
|
|
some conforming programs might fail.
|
2007-04-12 22:42:49 +00:00
|
|
|
Some of the checks can be performed at compile time,
|
|
|
|
and result in compiler warnings;
|
|
|
|
other checks take place at run time,
|
2007-01-28 19:30:54 +00:00
|
|
|
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.
|
2006-04-21 07:01:40 +00:00
|
|
|
.PP
|
|
|
|
When
|
|
|
|
.BR gcc (1)
|
2006-05-12 23:50:50 +00:00
|
|
|
is invoked, the following macros are defined by default:
|
2006-04-21 07:01:40 +00:00
|
|
|
.BR _BSD_SOURCE ,
|
|
|
|
.BR _SVID_SOURCE ,
|
|
|
|
.BR _POSIX_SOURCE ,
|
|
|
|
and
|
2006-12-27 04:35:02 +00:00
|
|
|
.BR _POSIX_C_SOURCE =199506.
|
2006-04-21 07:01:40 +00:00
|
|
|
If individual macros are defined, then other macros are disabled
|
2007-04-12 22:42:49 +00:00
|
|
|
unless they are also explicitly defined.
|
|
|
|
(Exception: if
|
2006-12-02 18:01:41 +00:00
|
|
|
.BR _POSIX_C_SOURCE
|
2007-04-12 22:42:49 +00:00
|
|
|
is not otherwise defined,
|
2006-12-02 18:01:41 +00:00
|
|
|
then it is always defined with the value 200112
|
|
|
|
(199506 in glibc versions before 2.4),
|
2007-06-08 11:56:22 +00:00
|
|
|
unless the compiler is invoked in one of its standard modes, for example, the
|
2006-04-21 07:01:40 +00:00
|
|
|
.I -std=c99
|
|
|
|
flag.)
|
|
|
|
Multiple macros can be defined; the results are additive.
|
2006-04-21 06:47:08 +00:00
|
|
|
.SH CONFORMING TO
|
|
|
|
POSIX.1 specifies
|
|
|
|
.BR _POSIX_C_SOURCE ,
|
|
|
|
.BR _POSIX_SOURCE ,
|
|
|
|
and
|
|
|
|
.BR _XOPEN_SOURCE .
|
|
|
|
.BR _XOPEN_SOURCE_EXTENDED
|
|
|
|
was specified by XPG4v2 (aka SUSv1).
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR _FILE_OFFSET_BITS
|
|
|
|
is not specified by any standard,
|
2006-04-21 06:47:08 +00:00
|
|
|
but is employed on some other implementations.
|
|
|
|
.BR _BSD_SOURCE ,
|
|
|
|
.BR _SVID_SOURCE ,
|
2007-01-28 19:30:54 +00:00
|
|
|
.BR _GNU_SOURCE ,
|
|
|
|
.BR _FORTIFY_SOURCE ,
|
|
|
|
.BR _REENTRANT ,
|
2006-04-21 06:47:08 +00:00
|
|
|
and
|
2007-01-28 19:30:54 +00:00
|
|
|
.BR _THREAD_SAFE
|
2006-04-21 06:47:08 +00:00
|
|
|
are Linux (glibc) specific.
|
|
|
|
.SH NOTES
|
|
|
|
.I <features.h>
|
|
|
|
is a Linux/glibc specific header file.
|
|
|
|
Other systems have an analogous file, but typically with a different name.
|
2007-04-12 22:42:49 +00:00
|
|
|
This header file is automatically included by other header files as
|
|
|
|
required: it is not necessary to explicitly include it in order to
|
2006-04-21 06:47:08 +00:00
|
|
|
employ feature test macros.
|
2007-01-28 17:44:00 +00:00
|
|
|
|
|
|
|
According to which of the above feature test macros are defined,
|
|
|
|
.I <features.h>
|
2007-04-12 22:42:49 +00:00
|
|
|
internally defines various other macros that are checked by
|
|
|
|
other glibc header files.
|
2007-01-28 17:44:00 +00:00
|
|
|
These macros have names prefixed by two underscores (e.g., __USE_MISC).
|
|
|
|
Programs should \fInever\fP define these macros directly:
|
2007-04-12 22:42:49 +00:00
|
|
|
instead, the appropriate feature test macro(s) from the
|
2007-01-28 17:44:00 +00:00
|
|
|
list above should be employed.
|