1FEATURE_TEST_MACROS(7) Linux Programmer's Manual FEATURE_TEST_MACROS(7)
2
6 feature_test_macros - feature test macros
7
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 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
19 because the header <abc.h> itself includes <xyz.h> (POSIX explicitly
20 allows this):
21 #include <abc.h>
23 #define _GNU_SOURCE
24 #include <xys.h>
25 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 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,
34 doing so is actively discouraged. See NOTES.
35 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 #include <unistd.h>
42 int acct(const char *filename);
44 Feature Test Macro Requirements for glibc (see
46 feature_test_macros(7)):
47 acct(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500)
49 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
52 before including any header files:
53 #define _BSD_SOURCE
55 #define _XOPEN_SOURCE /* or any value < 500 */
56 Alternatively, equivalent definitions can be included in the compila‐
58 tion command:
59 cc -D_BSD_SOURCE
61 cc -D_XOPEN_SOURCE # Or any value < 500
62 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 In a few cases, manual pages use a shorthand for expressing the feature
68 test macro requirements (this example from readahead(2)):
69 #define _GNU_SOURCE
71 #include <fcntl.h>
72 ssize_t readahead(int fd, off64_t *offset, size_t count);
74 This format is employed in cases where only a single feature test macro
76 can be used to expose the function declaration, and that macro is not
77 defined by default.
78 Feature test macros understood by glibc
80 The paragraphs below explain how feature test macros are handled in
81 Linux glibc 2.x, x > 0.
82 First, though a summary of a few details for the impatient:
84 * The macros that you most likely need to use in modern source code
86 are _POSIX_C_SOURCE (for definitions from various versions of
87 POSIX.1), _XOPEN_SOURCE (for definitions from various versions of
88 SUS), _GNU_SOURCE (for GNU and/or Linux specific stuff), and
89 _DEFAULT_SOURCE (to get definitions that would normally be provided
90 by default).
91 * Certain macros are defined with default values. Thus, although one
93 or more macros may be indicated as being required in the SYNOPSIS of
94 a man page, it may not be necessary to define them explicitly. Full
95 details of the defaults are given later in this man page.
96 * Defining _XOPEN_SOURCE with a value of 600 or greater produces the
98 same effects as defining _POSIX_C_SOURCE with a value of 200112L or
99 greater. Where one sees
100 _POSIX_C_SOURCE >= 200112L
102 in the feature test macro requirements in the SYNOPSIS of a man
104 page, it is implicit that the following has the same effect:
105 _XOPEN_SOURCE >= 600
107 * Defining _XOPEN_SOURCE with a value of 700 or greater produces the
109 same effects as defining _POSIX_C_SOURCE with a value of 200809L or
110 greater. Where one sees
111 _POSIX_C_SOURCE >= 200809L
113 in the feature test macro requirements in the SYNOPSIS of a man
115 page, it is implicit that the following has the same effect:
116 _XOPEN_SOURCE >= 700
118 Linux glibc understands the following feature test macros:
120 __STRICT_ANSI__
122 ISO Standard C. This macro is implicitly defined by gcc(1)
123 when invoked with, for example, the -std=c99 or -ansi flag.
124 _POSIX_C_SOURCE
126 Defining this macro causes header files to expose definitions
127 as follows:
128 · The value 1 exposes definitions conforming to POSIX.1-1990
130 and ISO C (1990).
131 · The value 2 or greater additionally exposes definitions for
133 POSIX.2-1992.
134 · The value 199309L or greater additionally exposes defini‐
136 tions for POSIX.1b (real-time extensions).
137 · The value 199506L or greater additionally exposes defini‐
139 tions for POSIX.1c (threads).
140 · (Since glibc 2.3.3) The value 200112L or greater addition‐
142 ally exposes definitions corresponding to the POSIX.1-2001
143 base specification (excluding the XSI extension). This
144 value also causes C95 (since glibc 2.12) and C99 (since
145 glibc 2.10) features to be exposed (in other words, the
146 equivalent of defining _ISOC99_SOURCE).
147 · (Since glibc 2.10) The value 200809L or greater additionally
149 exposes definitions corresponding to the POSIX.1-2008 base
150 specification (excluding the XSI extension).
151 _POSIX_SOURCE
153 Defining this obsolete macro with any value is equivalent to
154 defining _POSIX_C_SOURCE with the value 1.
155 Since this macro is obsolete, its usage is generally not docu‐
157 mented when discussing feature test macro requirements in the
158 man pages.
159 _XOPEN_SOURCE
161 Defining this macro causes header files to expose definitions
162 as follows:
163 · Defining with any value exposes definitions conforming to
165 POSIX.1, POSIX.2, and XPG4.
166 · The value 500 or greater additionally exposes definitions
168 for SUSv2 (UNIX 98).
169 · (Since glibc 2.2) The value 600 or greater additionally
171 exposes definitions for SUSv3 (UNIX 03; i.e., the
172 POSIX.1-2001 base specification plus the XSI extension) and
173 C99 definitions.
174 · (Since glibc 2.10) The value 700 or greater additionally
176 exposes definitions for SUSv4 (i.e., the POSIX.1-2008 base
177 specification plus the XSI extension).
178 If __STRICT_ANSI__ is not defined, or _XOPEN_SOURCE is defined
180 with a value greater than or equal to 500 and neither
181 _POSIX_SOURCE nor _POSIX_C_SOURCE is explicitly defined, then
182 the following macros are implicitly defined:
183 · _POSIX_SOURCE is defined with the value 1.
185 · _POSIX_C_SOURCE is defined, according to the value of
187 _XOPEN_SOURCE:
188 _XOPEN_SOURCE < 500
190 _POSIX_C_SOURCE is defined with the value 2.
191 500 <= _XOPEN_SOURCE < 600
193 _POSIX_C_SOURCE is defined with the value 199506L.
194 600 <= _XOPEN_SOURCE < 700
196 _POSIX_C_SOURCE is defined with the value 200112L.
197 700 <= _XOPEN_SOURCE (since glibc 2.10)
199 _POSIX_C_SOURCE is defined with the value 200809L.
200 In addition, defining _XOPEN_SOURCE with a value of 500 or
202 greater produces the same effects as defining
203 _XOPEN_SOURCE_EXTENDED.
204 _XOPEN_SOURCE_EXTENDED
206 If this macro is defined, and _XOPEN_SOURCE is defined, then
207 expose definitions corresponding to the XPG4v2 (SUSv1) UNIX
208 extensions (UNIX 95). Defining _XOPEN_SOURCE with a value of
209 500 or more also produces the same effect as defining
210 _XOPEN_SOURCE_EXTENDED. Use of _XOPEN_SOURCE_EXTENDED in new
211 source code should be avoided.
212 Since defining _XOPEN_SOURCE with a value of 500 or more has
214 the same effect as defining _XOPEN_SOURCE_EXTENDED, the latter
215 (obsolete) feature test macro is generally not described in the
216 SYNOPSIS in man pages.
217 _ISOC99_SOURCE (since glibc 2.1.3)
219 Exposes declarations consistent with the ISO C99 standard.
220 Earlier glibc 2.1.x versions recognized an equivalent macro
222 named _ISOC9X_SOURCE (because the C99 standard had not then
223 been finalized). Although the use of this macro is obsolete,
224 glibc continues to recognize it for backward compatibility.
225 Defining _ISOC99_SOURCE also exposes ISO C (1990) Amendment 1
227 ("C95") definitions. (The primary change in C95 was support
228 for international character sets.)
229 Invoking the C compiler with the option -std=c99 produces the
231 same effects as defining this macro.
232 _ISOC11_SOURCE (since glibc 2.16)
234 Exposes declarations consistent with the ISO C11 standard.
235 Defining this macro also enables C99 and C95 features (like
236 _ISOC99_SOURCE).
237 Invoking the C compiler with the option -std=c11 produces the
239 same effects as defining this macro.
240 _LARGEFILE64_SOURCE
242 Expose definitions for the alternative API specified by the LFS
243 (Large File Summit) as a "transitional extension" to the Single
244 UNIX Specification. (See ⟨http://opengroup.org/platform
245 /lfs.html⟩.) The alternative API consists of a set of new
246 objects (i.e., functions and types) whose names are suffixed
247 with "64" (e.g., off64_t versus off_t, lseek64() versus
248 lseek(), etc.). New programs should not employ this macro;
249 instead _FILE_OFFSET_BITS=64 should be employed.
250 _LARGEFILE_SOURCE
252 This macro was historically used to expose certain functions
253 (specifically fseeko(3) and ftello(3)) that address limitations
254 of earlier APIs (fseek(3) and ftell(3)) that use long int for
255 file offsets. This macro is implicitly defined if
256 _XOPEN_SOURCE is defined with a value greater than or equal to
257 500. New programs should not employ this macro; defining
258 _XOPEN_SOURCE as just described or defining _FILE_OFFSET_BITS
259 with the value 64 is the preferred mechanism to achieve the
260 same result.
261 _FILE_OFFSET_BITS
263 Defining this macro with the value 64 automatically converts
264 references to 32-bit functions and data types related to file
265 I/O and filesystem operations into references to their 64-bit
266 counterparts. This is useful for performing I/O on large files
267 (> 2 Gigabytes) on 32-bit systems. (Defining this macro per‐
268 mits correctly written programs to use large files with only a
269 recompilation being required.)
270 64-bit systems naturally permit file sizes greater than 2 Giga‐
272 bytes, and on those systems this macro has no effect.
273 _BSD_SOURCE (deprecated since glibc 2.20)
275 Defining this macro with any value causes header files to
276 expose BSD-derived definitions.
277 In glibc versions up to and including 2.18, defining this macro
279 also causes BSD definitions to be preferred in some situations
280 where standards conflict, unless one or more of _SVID_SOURCE,
281 _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE,
282 _XOPEN_SOURCE_EXTENDED, or _GNU_SOURCE is defined, in which
283 case BSD definitions are disfavored. Since glibc 2.19,
284 _BSD_SOURCE no longer causes BSD definitions to be preferred in
285 case of conflicts.
286 Since glibc 2.20, this macro is deprecated. It now has the
288 same effect as defining _DEFAULT_SOURCE, but generates a com‐
289 pile-time warning (unless _DEFAULT_SOURCE is also defined).
290 Use _DEFAULT_SOURCE instead. To allow code that requires
291 _BSD_SOURCE in glibc 2.19 and earlier and _DEFAULT_SOURCE in
292 glibc 2.20 and later to compile without warnings, define both
293 _BSD_SOURCE and _DEFAULT_SOURCE.
294 _SVID_SOURCE (deprecated since glibc 2.20)
296 Defining this macro with any value causes header files to
297 expose System V-derived definitions. (SVID == System V Inter‐
298 face Definition; see standards(7).)
299 Since glibc 2.20, this macro is deprecated in the same fashion
301 as _BSD_SOURCE.
302 _DEFAULT_SOURCE (since glibc 2.19)
304 This macro can be defined to ensure that the "default" defini‐
305 tions are provided even when the defaults would otherwise be
306 disabled, as happens when individual macros are explicitly
307 defined, or the compiler is invoked in one of its "standard"
308 modes (e.g., cc -std=c99). Defining _DEFAULT_SOURCE without
309 defining other individual macros or invoking the compiler in
310 one of its "standard" modes has no effect.
311 The "default" definitions comprise those required by
313 POSIX.1-2008 and ISO C99, as well as various definitions origi‐
314 nally derived from BSD and System V. On glibc 2.19 and ear‐
315 lier, these defaults were approximately equivalent to explic‐
316 itly defining the following:
317 cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809
319 _ATFILE_SOURCE (since glibc 2.4)
321 Defining this macro with any value causes header files to
322 expose declarations of a range of functions with the suffix
323 "at"; see openat(2). Since glibc 2.10, this macro is also
324 implicitly defined if _POSIX_C_SOURCE is defined with a value
325 greater than or equal to 200809L.
326 _GNU_SOURCE
328 Defining this macro (with any value) implicitly defines
329 _ATFILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE,
330 _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE with the
331 value 200809L (200112L in glibc versions before 2.10; 199506L
332 in glibc versions before 2.5; 199309L in glibc versions before
333 2.1) and _XOPEN_SOURCE with the value 700 (600 in glibc ver‐
334 sions before 2.10; 500 in glibc versions before 2.2). In addi‐
335 tion, various GNU-specific extensions are also exposed.
336 Since glibc 2.19, defining _GNU_SOURCE also has the effect of
338 implicitly defining _DEFAULT_SOURCE. In glibc versions before
339 2.20, defining _GNU_SOURCE also had the effect of implicitly
340 defining _BSD_SOURCE and _SVID_SOURCE.
341 _REENTRANT
343 Historically, on various C libraries it was necessary to define
344 this macro in all multithreaded code. (Some C libraries may
345 still require this.) In glibc, this macro also exposed defini‐
346 tions of certain reentrant functions.
347 However, glibc has been thread-safe by default for many years;
349 since glibc 2.3, the only effect of defining _REENTRANT has
350 been to enable one or two of the same declarations that are
351 also enabled by defining _POSIX_C_SOURCE with a value of
352 199606L or greater.
353 _REENTRANT is now obsolete. In glibc 2.25 and later, defining
355 _REENTRANT is equivalent to defining _POSIX_C_SOURCE with the
356 value 199606L. If a higher POSIX conformance level is selected
357 by any other means (such as _POSIX_C_SOURCE itself,
358 _XOPEN_SOURCE, _DEFAULT_SOURCE, or _GNU_SOURCE), then defining
359 _REENTRANT has no effect.
360 This macro is automatically defined if one compiles with
362 cc -pthread.
363 _THREAD_SAFE
365 Synonym for the (deprecated) _REENTRANT, provided for compati‐
366 bility with some other implementations.
367 _FORTIFY_SOURCE (since glibc 2.3.4)
369 Defining this macro causes some lightweight checks to be per‐
370 formed to detect some buffer overflow errors when employing
371 various string and memory manipulation functions (for example,
372 memcpy(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), str‐
373 cat(3), strncat(3), sprintf(3), snprintf(3), vsprintf(3),
374 vsnprintf(3), gets(3), and wide character variants thereof).
375 For some functions, argument consistency is checked; for exam‐
376 ple, a check is made that open(2) has been supplied with a mode
377 argument when the specified flags include O_CREAT. Not all
378 problems are detected, just some common cases.
379 If _FORTIFY_SOURCE is set to 1, with compiler optimization
381 level 1 (gcc -O1) and above, checks that shouldn't change the
382 behavior of conforming programs are performed. With _FOR‐
383 TIFY_SOURCE set to 2, some more checking is added, but some
384 conforming programs might fail.
385 Some of the checks can be performed at compile time (via macros
387 logic implemented in header files), and result in compiler
388 warnings; other checks take place at run time, and result in a
389 run-time error if the check fails.
390 Use of this macro requires compiler support, available with
392 gcc(1) since version 4.0.
393 Default definitions, implicit definitions, and combining definitions
395 If no feature test macros are explicitly defined, then the following
396 feature test macros are defined by default: _BSD_SOURCE (in glibc 2.19
397 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), _DEFAULT_SOURCE
398 (since glibc 2.19), _POSIX_SOURCE, and _POSIX_C_SOURCE=200809L (200112L
399 in glibc versions before 2.10; 199506L in glibc versions before 2.4;
400 199309L in glibc versions before 2.1).
401 If any of __STRICT_ANSI__, _ISOC99_SOURCE, _POSIX_SOURCE,
403 _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED, _BSD_SOURCE (in
404 glibc 2.19 and earlier), or _SVID_SOURCE (in glibc 2.19 and earlier) is
405 explicitly defined, then _BSD_SOURCE, _SVID_SOURCE, and _DEFAULT_SOURCE
406 are not defined by default.
407 If _POSIX_SOURCE and _POSIX_C_SOURCE are not explicitly defined, and
409 either __STRICT_ANSI__ is not defined or _XOPEN_SOURCE is defined with
410 a value of 500 or more, then
411 * _POSIX_SOURCE is defined with the value 1; and
413 * _POSIX_C_SOURCE is defined with one of the following values:
415 · 2, if _XOPEN_SOURCE is defined with a value less than 500;
417 · 199506L, if _XOPEN_SOURCE is defined with a value greater than or
419 equal to 500 and less than 600; or
420 · (since glibc 2.4) 200112L, if _XOPEN_SOURCE is defined with a
422 value greater than or equal to 600 and less than 700.
423 · (Since glibc 2.10) 200809L, if _XOPEN_SOURCE is defined with a
425 value greater than or equal to 700.
426 · Older versions of glibc do not know about the values 200112L and
428 200809L for _POSIX_C_SOURCE, and the setting of this macro will
429 depend on the glibc version.
430 · If _XOPEN_SOURCE is undefined, then the setting of
432 _POSIX_C_SOURCE depends on the glibc version: 199506L, in glibc
433 versions before 2.4; 200112L, in glibc 2.4 to 2.9; and 200809L,
434 since glibc 2.10.
435 Multiple macros can be defined; the results are additive.
437
439 POSIX.1 specifies _POSIX_C_SOURCE, _POSIX_SOURCE, and _XOPEN_SOURCE.
440 _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1), but is not
442 present in SUSv2 and later. _FILE_OFFSET_BITS is not specified by any
443 standard, but is employed on some other implementations.
444 _BSD_SOURCE, _SVID_SOURCE, _DEFAULT_SOURCE, _ATFILE_SOURCE,
446 _GNU_SOURCE, _FORTIFY_SOURCE, _REENTRANT, and _THREAD_SAFE are specific
447 to Linux (glibc).
448
450 <features.h> is a Linux/glibc-specific header file. Other systems have
451 an analogous file, but typically with a different name. This header
452 file is automatically included by other header files as required: it is
453 not necessary to explicitly include it in order to employ feature test
454 macros.
455 According to which of the above feature test macros are defined, <fea‐
457 tures.h> internally defines various other macros that are checked by
458 other glibc header files. These macros have names prefixed by two
459 underscores (e.g., __USE_MISC). Programs should never define these
460 macros directly: instead, the appropriate feature test macro(s) from
461 the list above should be employed.
462
464 The program below can be used to explore how the various feature test
465 macros are set depending on the glibc version and what feature test
466 macros are explicitly set. The following shell session, on a system
467 with glibc 2.10, shows some examples of what we would see:
468 $ cc ftm.c
470 $ ./a.out
471 _POSIX_SOURCE defined
472 _POSIX_C_SOURCE defined: 200809L
473 _BSD_SOURCE defined
474 _SVID_SOURCE defined
475 _ATFILE_SOURCE defined
476 $ cc -D_XOPEN_SOURCE=500 ftm.c
477 $ ./a.out
478 _POSIX_SOURCE defined
479 _POSIX_C_SOURCE defined: 199506L
480 _XOPEN_SOURCE defined: 500
481 $ cc -D_GNU_SOURCE ftm.c
482 $ ./a.out
483 _POSIX_SOURCE defined
484 _POSIX_C_SOURCE defined: 200809L
485 _ISOC99_SOURCE defined
486 _XOPEN_SOURCE defined: 700
487 _XOPEN_SOURCE_EXTENDED defined
488 _LARGEFILE64_SOURCE defined
489 _BSD_SOURCE defined
490 _SVID_SOURCE defined
491 _ATFILE_SOURCE defined
492 _GNU_SOURCE defined
493 Program source
495 /* ftm.c */
497 #include <stdio.h>
499 #include <unistd.h>
500 #include <stdlib.h>
501 int
503 main(int argc, char *argv[])
504 {
505 #ifdef _POSIX_SOURCE
506 printf("_POSIX_SOURCE defined\n");
507 #endif
508 #ifdef _POSIX_C_SOURCE
510 printf("_POSIX_C_SOURCE defined: %ldL\n", (long) _POSIX_C_SOURCE);
511 #endif
512 #ifdef _ISOC99_SOURCE
514 printf("_ISOC99_SOURCE defined\n");
515 #endif
516 #ifdef _ISOC11_SOURCE
518 printf("_ISOC11_SOURCE defined\n");
519 #endif
520 #ifdef _XOPEN_SOURCE
522 printf("_XOPEN_SOURCE defined: %d\n", _XOPEN_SOURCE);
523 #endif
524 #ifdef _XOPEN_SOURCE_EXTENDED
526 printf("_XOPEN_SOURCE_EXTENDED defined\n");
527 #endif
528 #ifdef _LARGEFILE64_SOURCE
530 printf("_LARGEFILE64_SOURCE defined\n");
531 #endif
532 #ifdef _FILE_OFFSET_BITS
534 printf("_FILE_OFFSET_BITS defined: %d\n", _FILE_OFFSET_BITS);
535 #endif
536 #ifdef _BSD_SOURCE
538 printf("_BSD_SOURCE defined\n");
539 #endif
540 #ifdef _SVID_SOURCE
542 printf("_SVID_SOURCE defined\n");
543 #endif
544 #ifdef _DEFAULT_SOURCE
546 printf("_DEFAULT_SOURCE defined\n");
547 #endif
548 #ifdef _ATFILE_SOURCE
550 printf("_ATFILE_SOURCE defined\n");
551 #endif
552 #ifdef _GNU_SOURCE
554 printf("_GNU_SOURCE defined\n");
555 #endif
556 #ifdef _REENTRANT
558 printf("_REENTRANT defined\n");
559 #endif
560 #ifdef _THREAD_SAFE
562 printf("_THREAD_SAFE defined\n");
563 #endif
564 #ifdef _FORTIFY_SOURCE
566 printf("_FORTIFY_SOURCE defined\n");
567 #endif
568 exit(EXIT_SUCCESS);
570 }
571
573 libc(7), standards(7)
574 The section "Feature Test Macros" under info libc.
576 /usr/include/features.h
578
580 This page is part of release 5.04 of the Linux man-pages project. A
581 description of the project, information about reporting bugs, and the
582 latest version of this page, can be found at
583 https://www.kernel.org/doc/man-pages/.
584Linux 2019-03-06 FEATURE_TEST_MACROS(7)