1feature_test_macros(7) Miscellaneous Information 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 _TIME_BITS
274 Defining this macro with the value 64 changes the width of
275 time_t(3type) to 64-bit which allows handling of timestamps be‐
276 yond 2038. It is closely related to _FILE_OFFSET_BITS and de‐
277 pending on implementation, may require it set. This macro is
278 available as of glibc 2.34.
279 _BSD_SOURCE (deprecated since glibc 2.20)
281 Defining this macro with any value causes header files to expose
282 BSD-derived definitions.
283 In glibc versions up to and including 2.18, defining this macro
285 also causes BSD definitions to be preferred in some situations
286 where standards conflict, unless one or more of _SVID_SOURCE,
287 _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EX‐
288 TENDED, or _GNU_SOURCE is defined, in which case BSD definitions
289 are disfavored. Since glibc 2.19, _BSD_SOURCE no longer causes
290 BSD definitions to be preferred in case of conflicts.
291 Since glibc 2.20, this macro is deprecated. It now has the same
293 effect as defining _DEFAULT_SOURCE, but generates a compile-time
294 warning (unless _DEFAULT_SOURCE is also defined). Use _DE‐
295 FAULT_SOURCE instead. To allow code that requires _BSD_SOURCE
296 in glibc 2.19 and earlier and _DEFAULT_SOURCE in glibc 2.20 and
297 later to compile without warnings, define both _BSD_SOURCE and
298 _DEFAULT_SOURCE.
299 _SVID_SOURCE (deprecated since glibc 2.20)
301 Defining this macro with any value causes header files to expose
302 System V-derived definitions. (SVID == System V Interface Defi‐
303 nition; see standards(7).)
304 Since glibc 2.20, this macro is deprecated in the same fashion
306 as _BSD_SOURCE.
307 _DEFAULT_SOURCE (since glibc 2.19)
309 This macro can be defined to ensure that the "default" defini‐
310 tions are provided even when the defaults would otherwise be
311 disabled, as happens when individual macros are explicitly de‐
312 fined, or the compiler is invoked in one of its "standard" modes
313 (e.g., cc -std=c99). Defining _DEFAULT_SOURCE without defining
314 other individual macros or invoking the compiler in one of its
315 "standard" modes has no effect.
316 The "default" definitions comprise those required by
318 POSIX.1-2008 and ISO C99, as well as various definitions origi‐
319 nally derived from BSD and System V. On glibc 2.19 and earlier,
320 these defaults were approximately equivalent to explicitly
321 defining the following:
322 cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809
324 _ATFILE_SOURCE (since glibc 2.4)
326 Defining this macro with any value causes header files to expose
327 declarations of a range of functions with the suffix "at"; see
328 openat(2). Since glibc 2.10, this macro is also implicitly de‐
329 fined if _POSIX_C_SOURCE is defined with a value greater than or
330 equal to 200809L.
331 _GNU_SOURCE
333 Defining this macro (with any value) implicitly defines _AT‐
334 FILE_SOURCE, _LARGEFILE64_SOURCE, _ISOC99_SOURCE,
335 _XOPEN_SOURCE_EXTENDED, _POSIX_SOURCE, _POSIX_C_SOURCE with the
336 value 200809L (200112L before glibc 2.10; 199506L before glibc
337 2.5; 199309L before glibc 2.1) and _XOPEN_SOURCE with the value
338 700 (600 before glibc 2.10; 500 before glibc 2.2). In addition,
339 various GNU-specific extensions are also exposed.
340 Since glibc 2.19, defining _GNU_SOURCE also has the effect of
342 implicitly defining _DEFAULT_SOURCE. Before glibc 2.20, defin‐
343 ing _GNU_SOURCE also had the effect of implicitly defining
344 _BSD_SOURCE and _SVID_SOURCE.
345 _REENTRANT
347 Historically, on various C libraries it was necessary to define
348 this macro in all multithreaded code. (Some C libraries may
349 still require this.) In glibc, this macro also exposed defini‐
350 tions of certain reentrant functions.
351 However, glibc has been thread-safe by default for many years;
353 since glibc 2.3, the only effect of defining _REENTRANT has been
354 to enable one or two of the same declarations that are also en‐
355 abled by defining _POSIX_C_SOURCE with a value of 199606L or
356 greater.
357 _REENTRANT is now obsolete. In glibc 2.25 and later, defining
359 _REENTRANT is equivalent to defining _POSIX_C_SOURCE with the
360 value 199606L. If a higher POSIX conformance level is selected
361 by any other means (such as _POSIX_C_SOURCE itself,
362 _XOPEN_SOURCE, _DEFAULT_SOURCE, or _GNU_SOURCE), then defining
363 _REENTRANT has no effect.
364 This macro is automatically defined if one compiles with
366 cc -pthread.
367 _THREAD_SAFE
369 Synonym for the (deprecated) _REENTRANT, provided for compati‐
370 bility with some other implementations.
371 _FORTIFY_SOURCE (since glibc 2.3.4)
373 Defining this macro causes some lightweight checks to be per‐
374 formed to detect some buffer overflow errors when employing var‐
375 ious string and memory manipulation functions (for example, mem‐
376 cpy(3), memset(3), stpcpy(3), strcpy(3), strncpy(3), strcat(3),
377 strncat(3), sprintf(3), snprintf(3), vsprintf(3), vsnprintf(3),
378 gets(3), and wide character variants thereof). For some func‐
379 tions, argument consistency is checked; for example, a check is
380 made that open(2) has been supplied with a mode argument when
381 the specified flags include O_CREAT. Not all problems are de‐
382 tected, just some common cases.
383 If _FORTIFY_SOURCE is set to 1, with compiler optimization level
385 1 (gcc -O1) and above, checks that shouldn't change the behavior
386 of conforming programs are performed. With _FORTIFY_SOURCE set
387 to 2, some more checking is added, but some conforming programs
388 might fail.
389 Some of the checks can be performed at compile time (via macros
391 logic implemented in header files), and result in compiler warn‐
392 ings; other checks take place at run time, and result in a run-
393 time error if the check fails.
394 With _FORTIFY_SOURCE set to 3, additional checking is added to
396 intercept some function calls used with an argument of variable
397 size where the compiler can deduce an upper bound for its value.
398 For example, a program where malloc(3)'s size argument is vari‐
399 able can now be fortified.
400 Use of this macro requires compiler support, available with
402 gcc(1) since glibc 4.0.
403 Use of _FORTIFY_SOURCE set to 3 requires gcc(1) version 12.0 or
405 later.
406 Default definitions, implicit definitions, and combining definitions
408 If no feature test macros are explicitly defined, then the following
409 feature test macros are defined by default: _BSD_SOURCE (in glibc 2.19
410 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), _DEFAULT_SOURCE
411 (since glibc 2.19), _POSIX_SOURCE, and _POSIX_C_SOURCE=200809L (200112L
412 before glibc 2.10; 199506L before glibc 2.4; 199309L before glibc 2.1).
413 If any of __STRICT_ANSI__, _ISOC99_SOURCE, _ISOC11_SOURCE (since glibc
415 2.18), _POSIX_SOURCE, _POSIX_C_SOURCE, _XOPEN_SOURCE, _XOPEN_SOURCE_EX‐
416 TENDED (in glibc 2.11 and earlier), _BSD_SOURCE (in glibc 2.19 and ear‐
417 lier), or _SVID_SOURCE (in glibc 2.19 and earlier) is explicitly de‐
418 fined, then _BSD_SOURCE, _SVID_SOURCE, and _DEFAULT_SOURCE are not de‐
419 fined by default.
420 If _POSIX_SOURCE and _POSIX_C_SOURCE are not explicitly defined, and
422 either __STRICT_ANSI__ is not defined or _XOPEN_SOURCE is defined with
423 a value of 500 or more, then
424 • _POSIX_SOURCE is defined with the value 1; and
426 • _POSIX_C_SOURCE is defined with one of the following values:
428 • 2, if _XOPEN_SOURCE is defined with a value less than 500;
430 • 199506L, if _XOPEN_SOURCE is defined with a value greater than or
432 equal to 500 and less than 600; or
433 • (since glibc 2.4) 200112L, if _XOPEN_SOURCE is defined with a
435 value greater than or equal to 600 and less than 700.
436 • (Since glibc 2.10) 200809L, if _XOPEN_SOURCE is defined with a
438 value greater than or equal to 700.
439 • Older versions of glibc do not know about the values 200112L and
441 200809L for _POSIX_C_SOURCE, and the setting of this macro will
442 depend on the glibc version.
443 • If _XOPEN_SOURCE is undefined, then the setting of
445 _POSIX_C_SOURCE depends on the glibc version: 199506L, before
446 glibc 2.4; 200112L, since glibc 2.4 to glibc 2.9; and 200809L,
447 since glibc 2.10.
448 Multiple macros can be defined; the results are additive.
450
452 POSIX.1 specifies _POSIX_C_SOURCE, _POSIX_SOURCE, and _XOPEN_SOURCE.
453 _FILE_OFFSET_BITS is not specified by any standard, but is employed on
455 some other implementations.
456 _BSD_SOURCE, _SVID_SOURCE, _DEFAULT_SOURCE, _ATFILE_SOURCE,
458 _GNU_SOURCE, _FORTIFY_SOURCE, _REENTRANT, and _THREAD_SAFE are specific
459 to glibc.
460
462 _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1), but is not
463 present in SUSv2 and later.
464
466 <features.h> is a Linux/glibc-specific header file. Other systems have
467 an analogous file, but typically with a different name. This header
468 file is automatically included by other header files as required: it is
469 not necessary to explicitly include it in order to employ feature test
470 macros.
471 According to which of the above feature test macros are defined, <fea‐
473 tures.h> internally defines various other macros that are checked by
474 other glibc header files. These macros have names prefixed by two un‐
475 derscores (e.g., __USE_MISC). Programs should never define these
476 macros directly: instead, the appropriate feature test macro(s) from
477 the list above should be employed.
478
480 The program below can be used to explore how the various feature test
481 macros are set depending on the glibc version and what feature test
482 macros are explicitly set. The following shell session, on a system
483 with glibc 2.10, shows some examples of what we would see:
484 $ cc ftm.c
486 $ ./a.out
487 _POSIX_SOURCE defined
488 _POSIX_C_SOURCE defined: 200809L
489 _BSD_SOURCE defined
490 _SVID_SOURCE defined
491 _ATFILE_SOURCE defined
492 $ cc -D_XOPEN_SOURCE=500 ftm.c
493 $ ./a.out
494 _POSIX_SOURCE defined
495 _POSIX_C_SOURCE defined: 199506L
496 _XOPEN_SOURCE defined: 500
497 $ cc -D_GNU_SOURCE ftm.c
498 $ ./a.out
499 _POSIX_SOURCE defined
500 _POSIX_C_SOURCE defined: 200809L
501 _ISOC99_SOURCE defined
502 _XOPEN_SOURCE defined: 700
503 _XOPEN_SOURCE_EXTENDED defined
504 _LARGEFILE64_SOURCE defined
505 _BSD_SOURCE defined
506 _SVID_SOURCE defined
507 _ATFILE_SOURCE defined
508 _GNU_SOURCE defined
509 Program source
511 /* ftm.c */
513 #include <stdint.h>
515 #include <stdio.h>
516 #include <unistd.h>
517 #include <stdlib.h>
518 int
520 main(int argc, char *argv[])
521 {
522 #ifdef _POSIX_SOURCE
523 printf("_POSIX_SOURCE defined\n");
524 #endif
525 #ifdef _POSIX_C_SOURCE
527 printf("_POSIX_C_SOURCE defined: %jdL\n",
528 (intmax_t) _POSIX_C_SOURCE);
529 #endif
530 #ifdef _ISOC99_SOURCE
532 printf("_ISOC99_SOURCE defined\n");
533 #endif
534 #ifdef _ISOC11_SOURCE
536 printf("_ISOC11_SOURCE defined\n");
537 #endif
538 #ifdef _XOPEN_SOURCE
540 printf("_XOPEN_SOURCE defined: %d\n", _XOPEN_SOURCE);
541 #endif
542 #ifdef _XOPEN_SOURCE_EXTENDED
544 printf("_XOPEN_SOURCE_EXTENDED defined\n");
545 #endif
546 #ifdef _LARGEFILE64_SOURCE
548 printf("_LARGEFILE64_SOURCE defined\n");
549 #endif
550 #ifdef _FILE_OFFSET_BITS
552 printf("_FILE_OFFSET_BITS defined: %d\n", _FILE_OFFSET_BITS);
553 #endif
554 #ifdef _TIME_BITS
556 printf("_TIME_BITS defined: %d\n", _TIME_BITS);
557 #endif
558 #ifdef _BSD_SOURCE
560 printf("_BSD_SOURCE defined\n");
561 #endif
562 #ifdef _SVID_SOURCE
564 printf("_SVID_SOURCE defined\n");
565 #endif
566 #ifdef _DEFAULT_SOURCE
568 printf("_DEFAULT_SOURCE defined\n");
569 #endif
570 #ifdef _ATFILE_SOURCE
572 printf("_ATFILE_SOURCE defined\n");
573 #endif
574 #ifdef _GNU_SOURCE
576 printf("_GNU_SOURCE defined\n");
577 #endif
578 #ifdef _REENTRANT
580 printf("_REENTRANT defined\n");
581 #endif
582 #ifdef _THREAD_SAFE
584 printf("_THREAD_SAFE defined\n");
585 #endif
586 #ifdef _FORTIFY_SOURCE
588 printf("_FORTIFY_SOURCE defined\n");
589 #endif
590 exit(EXIT_SUCCESS);
592 }
593
595 libc(7), standards(7), system_data_types(7)
596 The section "Feature Test Macros" under info libc.
598 /usr/include/features.h
600Linux man-pages 6.04 2023-03-30 feature_test_macros(7)