1feature_test_macros(7) Miscellaneous Information Manual feature_test_macros(7)
2
3
4

NAME

6       feature_test_macros - feature test macros
7

DESCRIPTION

9       Feature  test  macros  allow  the programmer to control the definitions
10       that are exposed by system header files when a program is compiled.
11
12       NOTE: In order to be effective, a feature test macro  must  be  defined
13       before including any header files.  This can be done either in the com‐
14       pilation command (cc -DMACRO=value) or by defining the macro within the
15       source  code  before  including  any headers.  The requirement that the
16       macro must be defined before including any header file  exists  because
17       header files may freely include one another.  Thus, for example, in the
18       following lines, defining the _GNU_SOURCE macro may have no effect  be‐
19       cause  the header <abc.h> itself includes <xyz.h> (POSIX explicitly al‐
20       lows this):
21
22           #include <abc.h>
23           #define _GNU_SOURCE
24           #include <xyz.h>
25
26       Some feature test macros are useful for creating portable applications,
27       by preventing nonstandard definitions from being exposed.  Other macros
28       can be used to expose nonstandard definitions that are not  exposed  by
29       default.
30
31       The  precise effects of each of the feature test macros described below
32       can be ascertained by inspecting the <features.h> header  file.   Note:
33       applications  do not need to directly include <features.h>; indeed, do‐
34       ing so is actively discouraged.  See NOTES.
35
36   Specification of feature test macro requirements in manual pages
37       When a function requires that a feature test macro is defined, the man‐
38       ual page SYNOPSIS typically includes a note of the following form (this
39       example from the acct(2) manual page):
40
41              #include <unistd.h>
42
43              int acct(const char *filename);
44
45          Feature Test Macro Requirements for glibc (see
46          feature_test_macros(7)):
47
48              acct(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
49
50       The || means that in order to obtain the declaration  of  acct(2)  from
51       <unistd.h>,  either of the following macro definitions must be made be‐
52       fore including any header files:
53
54           #define _BSD_SOURCE
55           #define _XOPEN_SOURCE        /* or any value < 500 */
56
57       Alternatively, equivalent definitions can be included in  the  compila‐
58       tion command:
59
60           cc -D_BSD_SOURCE
61           cc -D_XOPEN_SOURCE           # Or any value < 500
62
63       Note  that, as described below, some feature test macros are defined by
64       default, so that it may not always be necessary to  explicitly  specify
65       the feature test macro(s) shown in the SYNOPSIS.
66
67       In a few cases, manual pages use a shorthand for expressing the feature
68       test macro requirements (this example from readahead(2)):
69
70           #define _GNU_SOURCE