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