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) when
123 invoked with, for example, the -std=c99 or -ansi flag.
124 _POSIX_C_SOURCE
126 Defining this macro causes header files to expose definitions as
127 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 definitions
136 for POSIX.1b (real-time extensions).
137 · The value 199506L or greater additionally exposes definitions
139 for POSIX.1c (threads).
140 · (Since glibc 2.3.3) The value 200112L or greater additionally
142 exposes definitions corresponding to the POSIX.1-2001 base
143 specification (excluding the XSI extension). This value also
144 causes C95 (since glibc 2.12) and C99 (since glibc 2.10) fea‐
145 tures to be exposed (in other words, the equivalent of defin‐
146 ing _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 as
162 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 for
168 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 the
214 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 been
223 finalized). Although the use of this macro is obsolete, glibc
224 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 for
228 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 lseek(),
248 etc.). New programs should not employ this macro; instead
249 _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 _XOPEN_SOURCE
256 is defined with a value greater than or equal to 500. New pro‐
257 grams should not employ this macro; defining _XOPEN_SOURCE as
258 just described or defining _FILE_OFFSET_BITS with the value 64
259 is the preferred mechanism to achieve the same result.
260 _FILE_OFFSET_BITS
262 Defining this macro with the value 64 automatically converts
263 references to 32-bit functions and data types related to file
264 I/O and filesystem operations into references to their 64-bit
265 counterparts. This is useful for performing I/O on large files
266 (> 2 Gigabytes) on 32-bit systems. (Defining this macro permits
267 correctly written programs to use large files with only a recom‐
268 pilation being required.)
269 64-bit systems naturally permit file sizes greater than 2 Giga‐
271 bytes, and on those systems this macro has no effect.
272 _BSD_SOURCE (deprecated since glibc 2.20)
274 Defining this macro with any value causes header files to expose
275 BSD-derived definitions.
276 In glibc versions up to and including 2.18, defining this macro
278 also causes BSD definitions to be preferred in some situations
279 where standards conflict, unless one or more of _SVID_SOURCE,
280 _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE,
281 _XOPEN_SOURCE_EXTENDED, or _GNU_SOURCE is defined, in which case
282 BSD definitions are disfavored. Since glibc 2.19, _BSD_SOURCE
283 no longer causes BSD definitions to be preferred in case of con‐
284 flicts.
285 Since glibc 2.20, this macro is deprecated. It now has the same
287 effect as defining _DEFAULT_SOURCE, but generates a compile-time
288 warning (unless _DEFAULT_SOURCE is also defined). Use
289 _DEFAULT_SOURCE instead. To allow code that requires
290 _BSD_SOURCE in glibc 2.19 and earlier and _DEFAULT_SOURCE in
291 glibc 2.20 and later to compile without warnings, define both
292 _BSD_SOURCE and _DEFAULT_SOURCE.
293 _SVID_SOURCE (deprecated since glibc 2.20)
295 Defining this macro with any value causes header files to expose
296 System V-derived definitions. (SVID == System V Interface Defi‐
297 nition; see standards(7).)
298 Since glibc 2.20, this macro is deprecated in the same fashion
300 as _BSD_SOURCE.
301 _DEFAULT_SOURCE (since glibc 2.19)
303 This macro can be defined to ensure that the "default" defini‐
304 tions are provided even when the defaults would otherwise be
305 disabled, as happens when individual macros are explicitly
306 defined, or the compiler is invoked in one of its "standard"
307 modes (e.g., cc -std=c99). Defining _DEFAULT_SOURCE without
308 defining other individual macros or invoking the compiler in one
309 of its "standard" modes has no effect.
310 The "default" definitions comprise those required by
312 POSIX.1-2008 and ISO C99, as well as various definitions origi‐
313 nally derived from BSD and System V. On glibc 2.19 and earlier,
314 these defaults were approximately equivalent to explicitly
315 defining the following:
316 cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809
318 _ATFILE_SOURCE (since glibc 2.4)
320 Defining this macro with any value causes header files to expose
321 declarations of a range of functions with the suffix "at"; see
322 openat(2). Since glibc 2.10, this macro is also implicitly
323 defined if _POSIX_C_SOURCE is defined with a value greater than
324 or equal to 200809L.
325 _GNU_SOURCE
327 Defining this macro (with any value) implicitly defines
328 _ATFILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE,
329 _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE with the
330 value 200809L (200112L in glibc versions before 2.10; 199506L in
331 glibc versions before 2.5; 199309L in glibc versions before 2.1)
332 and _XOPEN_SOURCE with the value 700 (600 in glibc versions
333 before 2.10; 500 in glibc versions before 2.2). In addition,
334 various GNU-specific extensions are also exposed.
335 Since glibc 2.19, defining _GNU_SOURCE also has the effect of
337 implicitly defining _DEFAULT_SOURCE. In glibc versions before
338 2.20, defining _GNU_SOURCE also had the effect of implicitly
339 defining _BSD_SOURCE and _SVID_SOURCE.
340 _REENTRANT
342 Historically, on various C libraries it was necessary to define
343 this macro in all multithreaded code. (Some C libraries may
344 still require this.) In glibc, this macro also exposed defini‐
345 tions of certain reentrant functions.
346 However, glibc has been thread-safe by default for many years;
348 since glibc 2.3, the only effect of defining _REENTRANT has been
349 to enable one or two of the same declarations that are also
350 enabled by defining _POSIX_C_SOURCE with a value of 199606L or
351 greater.
352 _REENTRANT is now obsolete. In glibc 2.25 and later, defining
354 _REENTRANT is equivalent to defining _POSIX_C_SOURCE with the
355 value 199606L. If a higher POSIX conformance level is selected
356 by any other means (such as _POSIX_C_SOURCE itself,
357 _XOPEN_SOURCE, _DEFAULT_SOURCE, or _GNU_SOURCE), then defining
358 _REENTRANT has no effect.
359 This macro is automatically defined if one compiles with
361 cc -pthread.
362 _THREAD_SAFE
364 Synonym for the (deprecated) _REENTRANT, provided for compati‐
365 bility with some other implementations.
366 _FORTIFY_SOURCE (since glibc 2.3.4)
368 Defining this macro causes some lightweight checks to be per‐
369 formed to detect some buffer overflow errors when employing var‐
370 ious string and memory manipulation functions (for example, mem‐
371 cpy(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3),
372 strncat(3), sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3),
373 gets(3), and wide character variants thereof). For some func‐
374 tions, argument consistency is checked; for example, a check is
375 made that open(2) has been supplied with a mode argument when
376 the specified flags include O_CREAT. Not all problems are
377 detected, just some common cases.
378 If _FORTIFY_SOURCE is set to 1, with compiler optimization level
380 1 (gcc -O1) and above, checks that shouldn't change the behavior
381 of conforming programs are performed. With _FORTIFY_SOURCE set
382 to 2, some more checking is added, but some conforming programs
383 might fail.
384 Some of the checks can be performed at compile time (via macros
386 logic implemented in header files), and result in compiler warn‐
387 ings; other checks take place at run time, and result in a run-
388 time error if the check fails.
389 Use of this macro requires compiler support, available with
391 gcc(1) since version 4.0.
392 Default definitions, implicit definitions, and combining definitions
394 If no feature test macros are explicitly defined, then the following
395 feature test macros are defined by default: _BSD_SOURCE (in glibc 2.19
396 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), _DEFAULT_SOURCE
397 (since glibc 2.19), _POSIX_SOURCE, and _POSIX_C_SOURCE=200809L (200112L
398 in glibc versions before 2.10; 199506L in glibc versions before 2.4;
399 199309L in glibc versions before 2.1).
400 If any of __STRICT_ANSI__, _ISOC99_SOURCE, _POSIX_SOURCE,
402 _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EXTENDED, _BSD_SOURCE (in
403 glibc 2.19 and earlier), or _SVID_SOURCE (in glibc 2.19 and earlier) is
404 explicitly defined, then _BSD_SOURCE, _SVID_SOURCE, and _DEFAULT_SOURCE
405 are not defined by default.
406 If _POSIX_SOURCE and _POSIX_C_SOURCE are not explicitly defined, and
408 either __STRICT_ANSI__ is not defined or _XOPEN_SOURCE is defined with
409 a value of 500 or more, then
410 * _POSIX_SOURCE is defined with the value 1; and
412 * _POSIX_C_SOURCE is defined with one of the following values:
414 · 2, if _XOPEN_SOURCE is defined with a value less than 500;
416 · 199506L, if _XOPEN_SOURCE is defined with a value greater than or
418 equal to 500 and less than 600; or
419 · (since glibc 2.4) 200112L, if _XOPEN_SOURCE is defined with a
421 value greater than or equal to 600 and less than 700.
422 · (Since glibc 2.10) 200809L, if _XOPEN_SOURCE is defined with a
424 value greater than or equal to 700.
425 · Older versions of glibc do not know about the values 200112L and
427 200809L for _POSIX_C_SOURCE, and the setting of this macro will
428 depend on the glibc version.
429 · If _XOPEN_SOURCE is undefined, then the setting of
431 _POSIX_C_SOURCE depends on the glibc version: 199506L, in glibc
432 versions before 2.4; 200112L, in glibc 2.4 to 2.9; and 200809L,
433 since glibc 2.10.
434 Multiple macros can be defined; the results are additive.
436
438 POSIX.1 specifies _POSIX_C_SOURCE, _POSIX_SOURCE, and _XOPEN_SOURCE.
439 _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1), but is not
441 present in SUSv2 and later. _FILE_OFFSET_BITS is not specified by any
442 standard, but is employed on some other implementations.
443 _BSD_SOURCE, _SVID_SOURCE, _DEFAULT_SOURCE, _ATFILE_SOURCE,
445 _GNU_SOURCE, _FORTIFY_SOURCE, _REENTRANT, and _THREAD_SAFE are specific
446 to Linux (glibc).
447
449 <features.h> is a Linux/glibc-specific header file. Other systems have
450 an analogous file, but typically with a different name. This header
451 file is automatically included by other header files as required: it is
452 not necessary to explicitly include it in order to employ feature test
453 macros.
454 According to which of the above feature test macros are defined, <fea‐
456 tures.h> internally defines various other macros that are checked by
457 other glibc header files. These macros have names prefixed by two
458 underscores (e.g., __USE_MISC). Programs should never define these
459 macros directly: instead, the appropriate feature test macro(s) from
460 the list above should be employed.
461
463 The program below can be used to explore how the various feature test
464 macros are set depending on the glibc version and what feature test
465 macros are explicitly set. The following shell session, on a system
466 with glibc 2.10, shows some examples of what we would see:
467 $ cc ftm.c
469 $ ./a.out
470 _POSIX_SOURCE defined
471 _POSIX_C_SOURCE defined: 200809L
472 _BSD_SOURCE defined
473 _SVID_SOURCE defined
474 _ATFILE_SOURCE defined
475 $ cc -D_XOPEN_SOURCE=500 ftm.c
476 $ ./a.out
477 _POSIX_SOURCE defined
478 _POSIX_C_SOURCE defined: 199506L
479 _XOPEN_SOURCE defined: 500
480 $ cc -D_GNU_SOURCE ftm.c
481 $ ./a.out
482 _POSIX_SOURCE defined
483 _POSIX_C_SOURCE defined: 200809L
484 _ISOC99_SOURCE defined
485 _XOPEN_SOURCE defined: 700
486 _XOPEN_SOURCE_EXTENDED defined
487 _LARGEFILE64_SOURCE defined
488 _BSD_SOURCE defined
489 _SVID_SOURCE defined
490 _ATFILE_SOURCE defined
491 _GNU_SOURCE defined
492 Program source
494 /* ftm.c */
496 #include <stdio.h>
498 #include <unistd.h>
499 #include <stdlib.h>
500 int
502 main(int argc, char *argv[])
503 {
504 #ifdef _POSIX_SOURCE
505 printf("_POSIX_SOURCE defined\n");
506 #endif
507 #ifdef _POSIX_C_SOURCE
509 printf("_POSIX_C_SOURCE defined: %ldL\n", (long) _POSIX_C_SOURCE);
510 #endif
511 #ifdef _ISOC99_SOURCE
513 printf("_ISOC99_SOURCE defined\n");
514 #endif
515 #ifdef _ISOC11_SOURCE
517 printf("_ISOC11_SOURCE defined\n");
518 #endif
519 #ifdef _XOPEN_SOURCE
521 printf("_XOPEN_SOURCE defined: %d\n", _XOPEN_SOURCE);
522 #endif
523 #ifdef _XOPEN_SOURCE_EXTENDED
525 printf("_XOPEN_SOURCE_EXTENDED defined\n");
526 #endif
527 #ifdef _LARGEFILE64_SOURCE
529 printf("_LARGEFILE64_SOURCE defined\n");
530 #endif
531 #ifdef _FILE_OFFSET_BITS
533 printf("_FILE_OFFSET_BITS defined: %d\n", _FILE_OFFSET_BITS);
534 #endif
535 #ifdef _BSD_SOURCE
537 printf("_BSD_SOURCE defined\n");
538 #endif
539 #ifdef _SVID_SOURCE
541 printf("_SVID_SOURCE defined\n");
542 #endif
543 #ifdef _DEFAULT_SOURCE
545 printf("_DEFAULT_SOURCE defined\n");
546 #endif
547 #ifdef _ATFILE_SOURCE
549 printf("_ATFILE_SOURCE defined\n");
550 #endif
551 #ifdef _GNU_SOURCE
553 printf("_GNU_SOURCE defined\n");
554 #endif
555 #ifdef _REENTRANT
557 printf("_REENTRANT defined\n");
558 #endif
559 #ifdef _THREAD_SAFE
561 printf("_THREAD_SAFE defined\n");
562 #endif
563 #ifdef _FORTIFY_SOURCE
565 printf("_FORTIFY_SOURCE defined\n");
566 #endif
567 exit(EXIT_SUCCESS);
569 }
570
572 libc(7), standards(7)
573 The section "Feature Test Macros" under info libc.
575 /usr/include/features.h
577
579 This page is part of release 5.07 of the Linux man-pages project. A
580 description of the project, information about reporting bugs, and the
581 latest version of this page, can be found at
582 https://www.kernel.org/doc/man-pages/.
583Linux 2020-04-11 FEATURE_TEST_MACROS(7)