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 be‐
19 cause the header <abc.h> itself includes <xyz.h> (POSIX explicitly al‐
20 lows this):
21 #include <abc.h>
23 #define _GNU_SOURCE
24 #include <xyz.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, do‐
34 ing 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 be‐
52 fore 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 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 _DE‐
89 FAULT_SOURCE (to get definitions that would normally be provided by
90 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 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 ex‐
171 poses definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001
172 base specification plus the XSI extension) and C99 defini‐
173 tions.
174 • (Since glibc 2.10) The value 700 or greater additionally ex‐
176 poses 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 _XOPEN_SOURCE_EX‐
203 TENDED.
204 _XOPEN_SOURCE_EXTENDED
206 If this macro is defined, and _XOPEN_SOURCE is defined, then ex‐
207 pose definitions corresponding to the XPG4v2 (SUSv1) UNIX exten‐
208 sions (UNIX 95). Defining _XOPEN_SOURCE with a value of 500 or
209 more also produces the same effect as defining _XOPEN_SOURCE_EX‐
210 TENDED. Use of _XOPEN_SOURCE_EXTENDED in new source code should
211 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 (ob‐
215 solete) 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 ob‐
246 jects (i.e., functions and types) whose names are suffixed with
247 "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 for file
255 offsets. This macro is implicitly defined if _XOPEN_SOURCE is
256 defined with a value greater than or equal to 500. New programs
257 should not employ this macro; defining _XOPEN_SOURCE as just de‐
258 scribed or defining _FILE_OFFSET_BITS with the value 64 is the
259 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, _XOPEN_SOURCE_EX‐
281 TENDED, or _GNU_SOURCE is defined, in which case BSD definitions
282 are disfavored. Since glibc 2.19, _BSD_SOURCE no longer causes
283 BSD definitions to be preferred in case of conflicts.
284 Since glibc 2.20, this macro is deprecated. It now has the same
286 effect as defining _DEFAULT_SOURCE, but generates a compile-time
287 warning (unless _DEFAULT_SOURCE is also defined). Use _DE‐
288 FAULT_SOURCE instead. To allow code that requires _BSD_SOURCE
289 in glibc 2.19 and earlier and _DEFAULT_SOURCE in glibc 2.20 and
290 later to compile without warnings, define both _BSD_SOURCE and
291 _DEFAULT_SOURCE.
292 _SVID_SOURCE (deprecated since glibc 2.20)
294 Defining this macro with any value causes header files to expose
295 System V-derived definitions. (SVID == System V Interface Defi‐
296 nition; see standards(7).)
297 Since glibc 2.20, this macro is deprecated in the same fashion
299 as _BSD_SOURCE.
300 _DEFAULT_SOURCE (since glibc 2.19)
302 This macro can be defined to ensure that the "default" defini‐
303 tions are provided even when the defaults would otherwise be
304 disabled, as happens when individual macros are explicitly de‐
305 fined, or the compiler is invoked in one of its "standard" modes
306 (e.g., cc -std=c99). Defining _DEFAULT_SOURCE without defining
307 other individual macros or invoking the compiler in one of its
308 "standard" modes has no effect.
309 The "default" definitions comprise those required by
311 POSIX.1-2008 and ISO C99, as well as various definitions origi‐
312 nally derived from BSD and System V. On glibc 2.19 and earlier,
313 these defaults were approximately equivalent to explicitly
314 defining the following:
315 cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809
317 _ATFILE_SOURCE (since glibc 2.4)
319 Defining this macro with any value causes header files to expose
320 declarations of a range of functions with the suffix "at"; see
321 openat(2). Since glibc 2.10, this macro is also implicitly de‐
322 fined if _POSIX_C_SOURCE is defined with a value greater than or
323 equal to 200809L.
324 _GNU_SOURCE
326 Defining this macro (with any value) implicitly defines _AT‐
327 FILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE,
328 _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE with the
329 value 200809L (200112L in glibc versions before 2.10; 199506L in
330 glibc versions before 2.5; 199309L in glibc versions before 2.1)
331 and _XOPEN_SOURCE with the value 700 (600 in glibc versions be‐
332 fore 2.10; 500 in glibc versions before 2.2). In addition, var‐
333 ious GNU-specific extensions are also exposed.
334 Since glibc 2.19, defining _GNU_SOURCE also has the effect of
336 implicitly defining _DEFAULT_SOURCE. In glibc versions before
337 2.20, defining _GNU_SOURCE also had the effect of implicitly
338 defining _BSD_SOURCE and _SVID_SOURCE.
339 _REENTRANT
341 Historically, on various C libraries it was necessary to define
342 this macro in all multithreaded code. (Some C libraries may
343 still require this.) In glibc, this macro also exposed defini‐
344 tions of certain reentrant functions.
345 However, glibc has been thread-safe by default for many years;
347 since glibc 2.3, the only effect of defining _REENTRANT has been
348 to enable one or two of the same declarations that are also en‐
349 abled by defining _POSIX_C_SOURCE with a value of 199606L or
350 greater.
351 _REENTRANT is now obsolete. In glibc 2.25 and later, defining
353 _REENTRANT is equivalent to defining _POSIX_C_SOURCE with the
354 value 199606L. If a higher POSIX conformance level is selected
355 by any other means (such as _POSIX_C_SOURCE itself,
356 _XOPEN_SOURCE, _DEFAULT_SOURCE, or _GNU_SOURCE), then defining
357 _REENTRANT has no effect.
358 This macro is automatically defined if one compiles with
360 cc -pthread.
361 _THREAD_SAFE
363 Synonym for the (deprecated) _REENTRANT, provided for compati‐
364 bility with some other implementations.
365 _FORTIFY_SOURCE (since glibc 2.3.4)
367 Defining this macro causes some lightweight checks to be per‐
368 formed to detect some buffer overflow errors when employing var‐
369 ious string and memory manipulation functions (for example, mem‐
370 cpy(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3),
371 strncat(3), sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3),
372 gets(3), and wide character variants thereof). For some func‐
373 tions, argument consistency is checked; for example, a check is
374 made that open(2) has been supplied with a mode argument when
375 the specified flags include O_CREAT. Not all problems are de‐
376 tected, just some common cases.
377 If _FORTIFY_SOURCE is set to 1, with compiler optimization level
379 1 (gcc -O1) and above, checks that shouldn't change the behavior
380 of conforming programs are performed. With _FORTIFY_SOURCE set
381 to 2, some more checking is added, but some conforming programs
382 might fail.
383 Some of the checks can be performed at compile time (via macros
385 logic implemented in header files), and result in compiler warn‐
386 ings; other checks take place at run time, and result in a run-
387 time error if the check fails.
388 Use of this macro requires compiler support, available with
390 gcc(1) since version 4.0.
391 Default definitions, implicit definitions, and combining definitions
393 If no feature test macros are explicitly defined, then the following
394 feature test macros are defined by default: _BSD_SOURCE (in glibc 2.19
395 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), _DEFAULT_SOURCE
396 (since glibc 2.19), _POSIX_SOURCE, and _POSIX_C_SOURCE=200809L (200112L
397 in glibc versions before 2.10; 199506L in glibc versions before 2.4;
398 199309L in glibc versions before 2.1).
399 If any of __STRICT_ANSI__, _ISOC99_SOURCE, _ISOC11_SOURCE (since glibc
401 2.18), _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EX‐
402 TENDED (in glibc 2.11 and earlier), _BSD_SOURCE (in glibc 2.19 and ear‐
403 lier), or _SVID_SOURCE (in glibc 2.19 and earlier) is explicitly de‐
404 fined, then _BSD_SOURCE, _SVID_SOURCE, and _DEFAULT_SOURCE are not de‐
405 fined 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 un‐
458 derscores (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 <stdint.h>
498 #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: %jdL\n",
511 (intmax_t) _POSIX_C_SOURCE);
512 #endif
513 #ifdef _ISOC99_SOURCE
515 printf("_ISOC99_SOURCE defined\n");
516 #endif
517 #ifdef _ISOC11_SOURCE
519 printf("_ISOC11_SOURCE defined\n");
520 #endif
521 #ifdef _XOPEN_SOURCE
523 printf("_XOPEN_SOURCE defined: %d\n", _XOPEN_SOURCE);
524 #endif
525 #ifdef _XOPEN_SOURCE_EXTENDED
527 printf("_XOPEN_SOURCE_EXTENDED defined\n");
528 #endif
529 #ifdef _LARGEFILE64_SOURCE
531 printf("_LARGEFILE64_SOURCE defined\n");
532 #endif
533 #ifdef _FILE_OFFSET_BITS
535 printf("_FILE_OFFSET_BITS defined: %d\n", _FILE_OFFSET_BITS);
536 #endif
537 #ifdef _BSD_SOURCE
539 printf("_BSD_SOURCE defined\n");
540 #endif
541 #ifdef _SVID_SOURCE
543 printf("_SVID_SOURCE defined\n");
544 #endif
545 #ifdef _DEFAULT_SOURCE
547 printf("_DEFAULT_SOURCE defined\n");
548 #endif
549 #ifdef _ATFILE_SOURCE
551 printf("_ATFILE_SOURCE defined\n");
552 #endif
553 #ifdef _GNU_SOURCE
555 printf("_GNU_SOURCE defined\n");
556 #endif
557 #ifdef _REENTRANT
559 printf("_REENTRANT defined\n");
560 #endif
561 #ifdef _THREAD_SAFE
563 printf("_THREAD_SAFE defined\n");
564 #endif
565 #ifdef _FORTIFY_SOURCE
567 printf("_FORTIFY_SOURCE defined\n");
568 #endif
569 exit(EXIT_SUCCESS);
571 }
572
574 libc(7), standards(7), system_data_types(7)
575 The section "Feature Test Macros" under info libc.
577 /usr/include/features.h
579
581 This page is part of release 5.13 of the Linux man-pages project. A
582 description of the project, information about reporting bugs, and the
583 latest version of this page, can be found at
584 https://www.kernel.org/doc/man-pages/.
585Linux 2021-03-22 FEATURE_TEST_MACROS(7)