diff options
Diffstat (limited to 'man/man7/feature_test_macros.7')
| -rw-r--r-- | man/man7/feature_test_macros.7 | 937 |
1 files changed, 937 insertions, 0 deletions
diff --git a/man/man7/feature_test_macros.7 b/man/man7/feature_test_macros.7 new file mode 100644 index 0000000..591c139 --- /dev/null +++ b/man/man7/feature_test_macros.7 @@ -0,0 +1,937 @@ +.\" This manpage is Copyright (C) 2006, Michael Kerrisk +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH feature_test_macros 7 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +feature_test_macros \- feature test macros +.SH DESCRIPTION +Feature test macros allow the programmer to control the definitions that +are exposed by system header files when a program is compiled. +.P +.B NOTE: +In order to be effective, a feature test macro +.IR "must be defined before including any header files" . +This can be done either in the compilation command +.RI ( "cc \-DMACRO=value" ) +or by defining the macro within the source code before +including any headers. +The requirement that the macro must be defined before including any +header file exists because header files may freely include one another. +Thus, for example, in the following lines, defining the +.B _GNU_SOURCE +macro may have no effect because the header +.I <abc.h> +itself includes +.I <xyz.h> +(POSIX explicitly allows this): +.P +.in +4n +.EX +#include <abc.h> +#define _GNU_SOURCE +#include <xyz.h> +.EE +.in +.P +Some feature test macros are useful for creating portable applications, +by preventing nonstandard definitions from being exposed. +Other macros can be used to expose nonstandard definitions that +are not exposed by default. +.P +The precise effects of each of the feature test macros described below +can be ascertained by inspecting the +.I <features.h> +header file. +.BR Note : +applications do +.I not +need to directly include +.IR <features.h> ; +indeed, doing so is actively discouraged. +See NOTES. +.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 acct (2) +manual page): +.P +.RS +.B #include <unistd.h> +.P +.BI "int acct(const char *" filename ); +.P +.RS -4 +.EX +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.EE +.RE +.P +.BR acct (): +_BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) +.RE +.P +The +.B || +means that in order to obtain the declaration of +.BR acct (2) +from +.IR <unistd.h> , +.I either +of the following macro +definitions must be made before including any header files: +.P +.in +4n +.EX +#define _BSD_SOURCE +#define _XOPEN_SOURCE /* or any value < 500 */ +.EE +.in +.P +Alternatively, equivalent definitions can be included in the +compilation command: +.P +.in +4n +.EX +cc \-D_BSD_SOURCE +cc \-D_XOPEN_SOURCE # Or any value < 500 +.EE +.in +.P +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. +.P +In a few cases, manual pages use a shorthand for expressing the +feature test macro requirements (this example from +.BR readahead (2)): +.P +.RS +4 +.EX +.B #define _GNU_SOURCE +.B #define _FILE_OFFSET_BITS 64 +.B #include <fcntl.h> +.P +.BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); +.EE +.RE +.P +This format is employed when the feature test macros ensure +that the proper function declarations are visible, +and the macros are not defined by default. +.SS Feature test macros understood by glibc +The paragraphs below explain how feature test macros are handled +in glibc 2.\fIx\fP, +.I x +> 0. +.P +First, though, a summary of a few details for the impatient: +.IP \[bu] 3 +The macros that you most likely need to use in modern source code are +.B _POSIX_C_SOURCE +(for definitions from various versions of POSIX.1), +.B _XOPEN_SOURCE +(for definitions from various versions of SUS), +.B _GNU_SOURCE +(for GNU and/or Linux specific stuff), and +.B _DEFAULT_SOURCE +(to get definitions that would normally be provided by default). +.IP \[bu] +Certain macros are defined with default values. +Thus, although one or more macros may be indicated as being +required in the SYNOPSIS of a man page, +it may not be necessary to define them explicitly. +Full details of the defaults are given later in this man page. +.IP \[bu] +Defining +.B _XOPEN_SOURCE +with a value of 600 or greater produces the same effects as defining +.B _POSIX_C_SOURCE +with a value of 200112L or greater. +Where one sees +.IP +.in +4n +.EX +_POSIX_C_SOURCE >= 200112L +.EE +.in +.IP +in the feature test macro requirements in the SYNOPSIS of a man page, +it is implicit that the following has the same effect: +.IP +.in +4n +.EX +_XOPEN_SOURCE >= 600 +.EE +.in +.IP \[bu] +Defining +.B _XOPEN_SOURCE +with a value of 700 or greater produces the same effects as defining +.B _POSIX_C_SOURCE +with a value of 200809L or greater. +Where one sees +.IP +.in +4n +.EX +_POSIX_C_SOURCE >= 200809L +.EE +.in +.IP +in the feature test macro requirements in the SYNOPSIS of a man page, +it is implicit that the following has the same effect: +.IP +.in +4n +.EX +_XOPEN_SOURCE >= 700 +.EE +.in +.\" 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. +.P +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 available only 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 additionally exposes definitions corresponding +to the POSIX.1-2001 base specification (excluding the XSI extension). +This value also causes C95 (since glibc 2.12) and +C99 (since glibc 2.10) features to be exposed +(in other words, the equivalent of defining +.BR _ISOC99_SOURCE ). +.IP \[bu] +(Since glibc 2.10) +The value 200809L or greater additionally exposes definitions corresponding +to the POSIX.1-2008 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. +.IP +Since this macro is obsolete, +its usage is generally not documented when discussing +feature test macro requirements in the man pages. +.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. +.IP \[bu] +(Since glibc 2.10) The value 700 or greater additionally exposes +definitions for SUSv4 (i.e., the POSIX.1-2008 base specification +plus the XSI extension). +.RE +.IP +If +.B __STRICT_ANSI__ +is not defined, or +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 500 +.I and +neither +.B _POSIX_SOURCE +nor +.B _POSIX_C_SOURCE +is explicitly defined, then +the following macros are implicitly defined: +.RS +.IP \[bu] 3 +.B _POSIX_SOURCE +is defined with the value 1. +.IP \[bu] +.B _POSIX_C_SOURCE +is defined, according to the value of +.BR _XOPEN_SOURCE : +.RS +.TP +.BR _XOPEN_SOURCE " < 500" +.B _POSIX_C_SOURCE +is defined with the value 2. +.TP +.RB "500 <= " _XOPEN_SOURCE " < 600" +.B _POSIX_C_SOURCE +is defined with the value 199506L. +.TP +.RB "600 <= " _XOPEN_SOURCE " < 700" +.B _POSIX_C_SOURCE +is defined with the value 200112L. +.TP +.RB "700 <= " _XOPEN_SOURCE " (since glibc 2.10)" +.B _POSIX_C_SOURCE +is defined with the value 200809L. +.RE +.RE +.IP +In addition, defining +.B _XOPEN_SOURCE +with a value of 500 or greater produces the same effects as defining +.BR _XOPEN_SOURCE_EXTENDED . +.TP +.B _XOPEN_SOURCE_EXTENDED +If this macro is defined, +.I and +.B _XOPEN_SOURCE +is defined, then expose definitions corresponding to the XPG4v2 +(SUSv1) UNIX extensions (UNIX 95). +Defining +.B _XOPEN_SOURCE +with a value of 500 or more also produces the same effect as defining +.BR _XOPEN_SOURCE_EXTENDED . +Use of +.B _XOPEN_SOURCE_EXTENDED +in new source code should be avoided. +.IP +Since defining +.B _XOPEN_SOURCE +with a value of 500 or more has the same effect as defining +.BR _XOPEN_SOURCE_EXTENDED , +the latter (obsolete) feature test macro is generally not described in the +SYNOPSIS in man pages. +.TP +.BR _ISOC99_SOURCE " (since glibc 2.1.3)" +Exposes declarations consistent with the ISO C99 standard. +.IP +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 this macro is obsolete, glibc continues +to recognize it for backward compatibility. +.IP +Defining +.B _ISOC99_SOURCE +also exposes ISO C (1990) Amendment 1 ("C95") definitions. +(The primary change in C95 was support for international character sets.) +.IP +Invoking the C compiler with the option +.I \-std=c99 +produces the same effects as defining this macro. +.TP +.BR _ISOC11_SOURCE " (since glibc 2.16)" +Exposes declarations consistent with the ISO C11 standard. +Defining this macro also enables C99 and C95 features (like +.BR _ISOC99_SOURCE ). +.IP +Invoking the C compiler with the option +.I \-std=c11 +produces the same effects as defining this macro. +.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 +.UR http:\:/\:/opengroup.org\:/platform\:/lfs.html +.UE .) +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 macro; instead +.I _FILE_OFFSET_BITS=64 +should be employed. +.TP +.B _LARGEFILE_SOURCE +This macro was historically used to expose certain functions (specifically +.BR fseeko (3) +and +.BR ftello (3)) +that address limitations of earlier APIs +.RB ( fseek (3) +and +.BR ftell (3)) +that use +.I long +for file offsets. +This macro is implicitly defined if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 500. +New programs should not employ this macro; +defining +.B _XOPEN_SOURCE +as just described or defining +.B _FILE_OFFSET_BITS +with the value 64 is the preferred mechanism to achieve the same result. +.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 filesystem operations into references to +their 64-bit counterparts. +This is useful for performing I/O on large files (> 2 Gigabytes) +on 32-bit systems. +It is also useful when calling functions like +.BR copy_file_range (2) +that were added more recently and that come only in 64-bit flavors. +(Defining this macro permits correctly written programs to use +large files with only a recompilation being required.) +.IP +64-bit systems naturally permit file sizes greater than 2 Gigabytes, +and on those systems this macro has no effect. +.TP +.B _TIME_BITS +Defining this macro with the value 64 +changes the width of +.BR time_t (3type) +to 64-bit which allows handling of timestamps beyond +2038. +It is closely related to +.B _FILE_OFFSET_BITS +and depending on implementation, may require it set. +This macro is available as of glibc 2.34. +.TP +.BR _BSD_SOURCE " (deprecated since glibc 2.20)" +Defining this macro with any value causes header files to expose +BSD-derived definitions. +.IP +In glibc versions up to and including 2.18, +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. +Since glibc 2.19, +.B _BSD_SOURCE +no longer causes BSD definitions to be preferred in case of conflicts. +.IP +Since glibc 2.20, this macro is deprecated. +.\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 +.\" commit 498afc54dfee41d33ba519f496e96480badace8e +.\" commit acd7f096d79c181866d56d4aaf3b043e741f1e2c +It now has the same effect as defining +.BR _DEFAULT_SOURCE , +but generates a compile-time warning (unless +.B _DEFAULT_SOURCE +.\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78 +is also defined). +Use +.B _DEFAULT_SOURCE +instead. +To allow code that requires +.B _BSD_SOURCE +in glibc 2.19 and earlier and +.B _DEFAULT_SOURCE +in glibc 2.20 and later to compile without warnings, define +.I both +.B _BSD_SOURCE +and +.BR _DEFAULT_SOURCE . +.TP +.BR _SVID_SOURCE " (deprecated since glibc 2.20)" +Defining this macro with any value causes header files to expose +System V-derived definitions. +(SVID == System V Interface Definition; see +.BR standards (7).) +.IP +Since glibc 2.20, this macro is deprecated in the same fashion as +.BR _BSD_SOURCE . +.TP +.BR _DEFAULT_SOURCE " (since glibc 2.19)" +This macro can be defined to ensure that the "default" +definitions are provided even when the defaults would otherwise +be disabled, +as happens when individual macros are explicitly defined, +or the compiler is invoked in one of its "standard" modes (e.g., +.IR cc\~\-std=c99 ). +Defining +.B _DEFAULT_SOURCE +without defining other individual macros +or invoking the compiler in one of its "standard" modes has no effect. +.IP +The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, +as well as various definitions originally derived from BSD and System V. +On glibc 2.19 and earlier, these defaults were approximately equivalent +to explicitly defining the following: +.IP +.in +4n +.EX +cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 +.EE +.in +.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). +Since glibc 2.10, this macro is also implicitly defined if +.B _POSIX_C_SOURCE +is defined with a value greater than or equal to 200809L. +.TP +.B _GNU_SOURCE +Defining this macro (with any value) implicitly defines +.BR _ATFILE_SOURCE , +.BR _LARGEFILE64_SOURCE , +.BR _ISOC99_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +.BR _POSIX_SOURCE , +.B _POSIX_C_SOURCE +with the value 200809L +(200112L before glibc 2.10; +199506L before glibc 2.5; +199309L before glibc 2.1) +and +.B _XOPEN_SOURCE +with the value 700 +(600 before glibc 2.10; +500 before glibc 2.2). +In addition, various GNU-specific extensions are also exposed. +.IP +Since glibc 2.19, defining +.B _GNU_SOURCE +also has the effect of implicitly defining +.BR _DEFAULT_SOURCE . +Before glibc 2.20, defining +.B _GNU_SOURCE +also had the effect of implicitly defining +.B _BSD_SOURCE +and +.BR _SVID_SOURCE . +.TP +.B _REENTRANT +Historically, on various C libraries +it was necessary to define this macro in all +multithreaded code. +.\" Zack Weinberg +.\" There did once exist C libraries where it was necessary. The ones +.\" I remember were proprietary Unix vendor libcs from the mid-1990s +.\" You would get completely unlocked stdio without _REENTRANT. +(Some C libraries may still require this.) +In glibc, +this macro also exposed definitions of certain reentrant functions. +.IP +However, glibc has been thread-safe by default for many years; +since glibc 2.3, the only effect of defining +.B _REENTRANT +has been to enable one or two of the same declarations that +are also enabled by defining +.B _POSIX_C_SOURCE +with a value of 199606L or greater. +.IP +.B _REENTRANT +is now obsolete. +In glibc 2.25 and later, defining +.B _REENTRANT +is equivalent to defining +.B _POSIX_C_SOURCE +with the value 199606L. +If a higher POSIX conformance level is +selected by any other means (such as +.B _POSIX_C_SOURCE +itself, +.BR _XOPEN_SOURCE , +.BR _DEFAULT_SOURCE , +or +.BR _GNU_SOURCE ), +then defining +.B _REENTRANT +has no effect. +.IP +This macro is automatically defined if one compiles with +.IR cc\~\-pthread . +.TP +.B _THREAD_SAFE +Synonym for the (deprecated) +.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 (for example, +.BR memcpy (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), +.BR gets (3), +and wide character variants thereof). +For some functions, argument consistency is checked; +for example, a check is made that +.BR open (2) +has been supplied with a +.I mode +argument when the specified flags include +.BR O_CREAT . +Not all problems are detected, just some common cases. +.\" Look for __USE_FORTIFY_LEVEL in the header files +.IP +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. +.\" For example, given the following code +.\" int d; +.\" char buf[1000], buf[1000]; +.\" strcpy(fmt, "Hello world\n%n"); +.\" snprintf(buf, sizeof(buf), fmt, &d); +.\" +.\" Compiling with "gcc -D_FORTIFY_SOURCE=2 -O1" and then running will +.\" cause the following diagnostic at run time at the snprintf() call +.\" +.\" *** %n in writable segment detected *** +.\" Aborted (core dumped) +.\" +.IP +Some of the checks can be performed at compile time +(via macros logic implemented in header files), +and result in compiler warnings; +other checks take place at run time, +and result in a run-time error if the check fails. +.IP +With +.B _FORTIFY_SOURCE +set to 3, additional checking is added to intercept +some function calls used with an argument of variable size +where the compiler can deduce an upper bound for its value. +For example, a program where +.BR malloc (3)'s +size argument is variable +can now be fortified. +.IP +Use of this macro requires compiler support, available since +gcc 4.0 and clang 2.6. +Use of +.B _FORTIFY_SOURCE +set to 3 requires gcc 12.0 or later, or clang 9.0 or later, +in conjunction with glibc 2.33 or later. +.\" glibc is not an absolute requirement (gcc has libssp; NetBSD/newlib +.\" and Darwin each have their own implementation), but let's keep it +.\" simple. +.SS Default definitions, implicit definitions, and combining definitions +If no feature test macros are explicitly defined, +then the following feature test macros are defined by default: +.B _BSD_SOURCE +(in glibc 2.19 and earlier), +.B _SVID_SOURCE +(in glibc 2.19 and earlier), +.B _DEFAULT_SOURCE +(since glibc 2.19), +.BR _POSIX_SOURCE , +and +.BR _POSIX_C_SOURCE =200809L +(200112L before glibc 2.10; +199506L before glibc 2.4; +199309L before glibc 2.1). +.P +If any of +.BR __STRICT_ANSI__ , +.BR _ISOC99_SOURCE , +.B _ISOC11_SOURCE +(since glibc 2.18), +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.B _XOPEN_SOURCE_EXTENDED +(in glibc 2.11 and earlier), +.B _BSD_SOURCE +(in glibc 2.19 and earlier), +or +.B _SVID_SOURCE +(in glibc 2.19 and earlier) +is explicitly defined, then +.BR _BSD_SOURCE , +.BR _SVID_SOURCE , +and +.B _DEFAULT_SOURCE +are not defined by default. +.P +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 +.IP \[bu] 3 +.B _POSIX_SOURCE +is defined with the value 1; and +.IP \[bu] +.B _POSIX_C_SOURCE +is defined with one of the following values: +.RS +.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] +(since glibc 2.4) 200112L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 600 and less than 700. +.IP \[bu] +(Since glibc 2.10) +200809L, +if +.B _XOPEN_SOURCE +is defined with a value greater than or equal to 700. +.IP \[bu] +Older versions of glibc do not know about the values +200112L and 200809L for +.BR _POSIX_C_SOURCE , +and the setting of this macro will depend on the glibc version. +.IP \[bu] +If +.B _XOPEN_SOURCE +is undefined, then the setting of +.B _POSIX_C_SOURCE +depends on the glibc version: +199506L, before glibc 2.4; +200112L, since glibc 2.4 to glibc 2.9; and +200809L, since glibc 2.10. +.RE +.P +Multiple macros can be defined; the results are additive. +.SH STANDARDS +POSIX.1 specifies +.BR _POSIX_C_SOURCE , +.BR _POSIX_SOURCE , +and +.BR _XOPEN_SOURCE . +.P +.B _FILE_OFFSET_BITS +is not specified by any standard, +but is employed on some other implementations. +.P +.BR _BSD_SOURCE , +.BR _SVID_SOURCE , +.BR _DEFAULT_SOURCE , +.BR _ATFILE_SOURCE , +.BR _GNU_SOURCE , +.BR _FORTIFY_SOURCE , +.BR _REENTRANT , +and +.B _THREAD_SAFE +are specific to glibc. +.SH HISTORY +.B _XOPEN_SOURCE_EXTENDED +was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later. +.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. +.P +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 +.I never +define these macros directly: +instead, the appropriate feature test macro(s) from the +list above should be employed. +.SH EXAMPLES +The program below can be used to explore how the various +feature test macros are set depending on the glibc version +and what feature test macros are explicitly set. +The following shell session, on a system with glibc 2.10, +shows some examples of what we would see: +.P +.in +4n +.EX +$ \fBcc ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 200809L +_BSD_SOURCE defined +_SVID_SOURCE defined +_ATFILE_SOURCE defined +$ \fBcc \-D_XOPEN_SOURCE=500 ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 199506L +_XOPEN_SOURCE defined: 500 +$ \fBcc \-D_GNU_SOURCE ftm.c\fP +$ \fB./a.out\fP +_POSIX_SOURCE defined +_POSIX_C_SOURCE defined: 200809L +_ISOC99_SOURCE defined +_XOPEN_SOURCE defined: 700 +_XOPEN_SOURCE_EXTENDED defined +_LARGEFILE64_SOURCE defined +_BSD_SOURCE defined +_SVID_SOURCE defined +_ATFILE_SOURCE defined +_GNU_SOURCE defined +.EE +.in +.SS Program source +\& +.EX +/* ftm.c */ +\& +#include <stdint.h> +#include <stdio.h> +#include <unistd.h> +#include <stdlib.h> +\& +int +main(int argc, char *argv[]) +{ +#ifdef _POSIX_SOURCE + printf("_POSIX_SOURCE defined\en"); +#endif +\& +#ifdef _POSIX_C_SOURCE + printf("_POSIX_C_SOURCE defined: %jdL\en", + (intmax_t) _POSIX_C_SOURCE); +#endif +\& +#ifdef _ISOC99_SOURCE + printf("_ISOC99_SOURCE defined\en"); +#endif +\& +#ifdef _ISOC11_SOURCE + printf("_ISOC11_SOURCE defined\en"); +#endif +\& +#ifdef _XOPEN_SOURCE + printf("_XOPEN_SOURCE defined: %d\en", _XOPEN_SOURCE); +#endif +\& +#ifdef _XOPEN_SOURCE_EXTENDED + printf("_XOPEN_SOURCE_EXTENDED defined\en"); +#endif +\& +#ifdef _LARGEFILE64_SOURCE + printf("_LARGEFILE64_SOURCE defined\en"); +#endif +\& +#ifdef _FILE_OFFSET_BITS + printf("_FILE_OFFSET_BITS defined: %d\en", _FILE_OFFSET_BITS); +#endif +\& +#ifdef _TIME_BITS + printf("_TIME_BITS defined: %d\en", _TIME_BITS); +#endif +\& +#ifdef _BSD_SOURCE + printf("_BSD_SOURCE defined\en"); +#endif +\& +#ifdef _SVID_SOURCE + printf("_SVID_SOURCE defined\en"); +#endif +\& +#ifdef _DEFAULT_SOURCE + printf("_DEFAULT_SOURCE defined\en"); +#endif +\& +#ifdef _ATFILE_SOURCE + printf("_ATFILE_SOURCE defined\en"); +#endif +\& +#ifdef _GNU_SOURCE + printf("_GNU_SOURCE defined\en"); +#endif +\& +#ifdef _REENTRANT + printf("_REENTRANT defined\en"); +#endif +\& +#ifdef _THREAD_SAFE + printf("_THREAD_SAFE defined\en"); +#endif +\& +#ifdef _FORTIFY_SOURCE + printf("_FORTIFY_SOURCE defined\en"); +#endif +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR libc (7), +.BR standards (7), +.BR system_data_types (7) +.P +The section "Feature Test Macros" under +.IR "info libc" . +.\" But beware: the info libc document is out of date (Jul 07, mtk) +.P +.I /usr/include/features.h |