.\" Copyright 2006, Michael Kerrisk .\" Copyright, the authors of the Linux man-pages project .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .TH feature_test_macros 7 2026-06-24 "Linux man-pages 6.19" .SH NAME feature_test_macros \- feature test macros .SH DESCRIPTION Feature test macros allow the programmer to control the definitions that are exposed by system header files when a program is compiled. .P .B NOTE: In order to be effective, a feature test macro .IR "must be defined before including any header files" . This can be done either in the compilation command .RI ( "cc \-DMACRO=value" ) or by defining the macro within the source code before including any headers. The requirement that the macro must be defined before including any header file exists because header files may freely include one another. Thus, for example, in the following lines, defining the .B _GNU_SOURCE macro may have no effect because the header .I itself includes .I (POSIX explicitly allows this): .P .in +4n .EX #include #define _GNU_SOURCE #include .EE .in .P Some feature test macros are useful for creating portable applications, by preventing nonstandard definitions from being exposed. Other macros can be used to expose nonstandard definitions that are not exposed by default. .P The precise effects of each of the feature test macros described below can be ascertained by inspecting the .I header file. .BR Note : applications do .I not need to directly include .IR ; indeed, doing so is actively discouraged. See NOTES. .SS Specification of feature test macro requirements in manual pages When a function requires that a feature test macro is defined, the manual page SYNOPSIS typically includes a note of the following form (this example from the .BR acct (2) manual page): .P .RS .B #include .P .BI "int acct(const char *" filename ); .P .RS -4 .EX Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .EE .RE .P .BR acct (): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) .RE .P The .B || means that in order to obtain the declaration of .BR acct (2) from .IR , .I either of the following macro definitions must be made before including any header files: .P .in +4n .EX #define _BSD_SOURCE #define _XOPEN_SOURCE /* or any value < 500 */ .EE .in .P Alternatively, equivalent definitions can be included in the compilation command: .P .in +4n .EX cc \-D_BSD_SOURCE cc \-D_XOPEN_SOURCE # Or any value < 500 .EE .in .P Note that, as described below, .BR "some feature test macros are defined by default" , so that it may not always be necessary to explicitly specify the feature test macro(s) shown in the SYNOPSIS. .P In a few cases, manual pages use a shorthand for expressing the feature test macro requirements (this example from .BR readahead (2)): .P .RS +4 .EX .B #define _GNU_SOURCE .B #define _FILE_OFFSET_BITS 64 .B #include .P .BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); .EE .RE .P This format is employed when the feature test macros ensure that the proper function declarations are visible, and the macros are not defined by default. .SS Feature test macros understood by glibc The paragraphs below explain how feature test macros are handled in glibc .RI 2. x , .I x > 0. .P First, though, a summary of a few details for the impatient: .IP \[bu] 3 The macros that you most likely need to use in modern source code are .B _POSIX_C_SOURCE (for definitions from various versions of POSIX.1), .B _XOPEN_SOURCE (for definitions from various versions of SUS), .B _GNU_SOURCE (for GNU and/or Linux specific stuff), and .B _DEFAULT_SOURCE (to get definitions that would normally be provided by default). .IP \[bu] Certain macros are defined with default values. Thus, although one or more macros may be indicated as being required in the SYNOPSIS of a man page, it may not be necessary to define them explicitly. Full details of the defaults are given later in this man page. .P glibc understands the following feature test macros: .TP .B __STRICT_ANSI__ ISO Standard C. This macro is implicitly defined by .BR gcc (1) when invoked with, for example, the .I \-std=c99 or .I \-ansi flag. .TP .B _POSIX_C_SOURCE Defining this macro causes header files to expose definitions conforming to the following standards, depending on the value. .RS .TP .RB >=\~ 1 POSIX.1-1990. POSIX.1-1990 implies ISO C90. .TP .RB >=\~ 2 POSIX.2-1992. .TP .RB >=\~ 199309L POSIX.1b (real-time extensions). .TP .BR 199506L " (since glibc 2.1)" POSIX.1c (threads). .TP .BR 200112L " (since glibc 2.3.3)" POSIX.1-2001 (excluding the XSI extension). POSIX.1-2001 implies ISO C99. .TP .BR 200809L " (since glibc 2.10)" POSIX.1-2008 (excluding the XSI extension). POSIX.1-2008 implies ISO C99. .RE .TP .BR _POSIX_SOURCE " [[deprecated]]" Equivalent to .IR -D_POSIX_C_SOURCE=1 . .TP .B _XOPEN_SOURCE Defining this macro causes header files to expose definitions conforming to the following standards, depending on the value. .RS .TP .B 1 POSIX.1, POSIX.2, XPG4. .TP .B 500 SUSv2 (Issue 5). .TP .BR 600 " (since glibc 2.2)" SUSv3 (Issue 6). SUSv3 is POSIX.1-2001 plus the XSI extension. .TP .BR 700 " (since glibc 2.10)" SUSv4 (Issue 7). SUSv4 is POSIX.1-2008 plus the XSI extension. .RE .TP .BR _XOPEN_SOURCE_EXTENDED " [[deprecated]]" Defining this macro causes header files to expose definitions conforming to SUSv1. .TP .BI _ISOC xx _SOURCE Defining one of these macros causes header files to expose definitions conforming to corresponding version of the ISO C standard. .IP They should not be defined by programmers. Instead, the language version should be specified with the corresponding compiler flag. .RS .TP .BR _ISOC99_SOURCE " (since glibc 2.1.3)" C99. Use .I -std=c99 or .I -std=gnu99 instead. .TP .BR _ISOC11_SOURCE " (since glibc 2.16)" C11. Use .I -std=c11 or .I -std=gnu11 instead. .TP .BR _ISOC23_SOURCE " (since glibc 2.40)" .TQ .BR _ISOC2X_SOURCE " (since glibc 2.31) [[deprecated]]" C23. Use .I -std=c23 or .I -std=gnu23 instead. Exposes declarations consistent with the ISO C23 standard. .RE .TP .BR _LARGEFILE64_SOURCE " [[deprecated]]" Expose definitions for the alternative API specified by the LFS (Large File Summit) as a "transitional extension" to the Single UNIX Specification. (See .UR http:\:/\:/opengroup.org\:/platform\:/lfs.html .UE .) The alternative API consists of a set of new objects (i.e., functions and types) whose names are suffixed with "64" (e.g., .I off64_t versus .IR off_t , .BR lseek64 () versus .BR lseek (), etc.). New programs should not employ this macro; instead .I _FILE_OFFSET_BITS=64 should be employed. .TP .BR _LARGEFILE_SOURCE " [[deprecated]]" This macro was historically used to expose certain functions (specifically, .BR fseeko (3) and .BR ftello (3)) that address limitations of earlier APIs .RB ( fseek (3) and .BR ftell (3)) that use .I long for file offsets. These functions are now part of SUSv2; use .B _XOPEN_SOURCE instead. Alternatively, defining .B _FILE_OFFSET_BITS with the value 64 also serves for this. .TP .B _FILE_OFFSET_BITS Defining this macro with the value 64 automatically converts references to 32-bit functions and data types related to file I/O and filesystem operations into references to their 64-bit counterparts. This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. It is also useful when calling functions like .BR copy_file_range (2) that were added more recently and that come only in 64-bit flavors. (Defining this macro permits correctly written programs to use large files with only a recompilation being required.) .IP 64-bit systems naturally permit file sizes greater than 2 Gigabytes, and on those systems this macro has no effect. .TP .B _TIME_BITS Defining this macro with the value 64 changes the width of .BR time_t (3type) to 64-bit which allows handling of timestamps beyond 2038. It is closely related to .B _FILE_OFFSET_BITS and depending on implementation, may require it set. This macro is available as of glibc 2.34. .TP .BR _BSD_SOURCE " [[deprecated]]" Defining this macro with any value causes header files to expose BSD-derived definitions. .IP In glibc versions up to and including 2.18, defining this macro also causes BSD definitions to be preferred in some situations where standards conflict, unless one or more of .BR _SVID_SOURCE , .BR _POSIX_SOURCE , .BR _POSIX_C_SOURCE , .BR _XOPEN_SOURCE , .BR _XOPEN_SOURCE_EXTENDED , or .B _GNU_SOURCE is defined, in which case BSD definitions are disfavored. Since glibc 2.19, .B _BSD_SOURCE no longer causes BSD definitions to be preferred in case of conflicts. .IP Since glibc 2.20, this macro is deprecated. .\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 .\" commit 498afc54dfee41d33ba519f496e96480badace8e .\" commit acd7f096d79c181866d56d4aaf3b043e741f1e2c It now has the same effect as defining .BR _DEFAULT_SOURCE , but generates a compile-time warning (unless .B _DEFAULT_SOURCE .\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78 is also defined). Use .B _DEFAULT_SOURCE instead. To allow code that requires .B _BSD_SOURCE in glibc 2.19 and earlier and .B _DEFAULT_SOURCE in glibc 2.20 and later to compile without warnings, define .I both .B _BSD_SOURCE and .BR _DEFAULT_SOURCE . .TP .BR _SVID_SOURCE " [[deprecated]]" Defining this macro with any value causes header files to expose System V-derived definitions. (SVID == System V Interface Definition; see .BR standards (7).) .IP Since glibc 2.20, this macro is deprecated in the same fashion as .BR _BSD_SOURCE . .TP .BR _DEFAULT_SOURCE " (since glibc 2.19)" This macro can be defined to ensure that the "default" definitions are provided even when the defaults would otherwise be disabled, as happens when individual macros are explicitly defined, or the compiler is invoked in one of its "standard" modes (e.g., .IR cc\~\-std=c99 ). Defining .B _DEFAULT_SOURCE without defining other individual macros or invoking the compiler in one of its "standard" modes has no effect. .IP The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, as well as various definitions originally derived from BSD and System V. On glibc 2.19 and earlier, these defaults were approximately equivalent to explicitly defining the following: .IP .in +4n .EX cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 .EE .in .TP .BR _ATFILE_SOURCE " (since glibc 2.4)" Defining this macro with any value causes header files to expose declarations of a range of functions with the suffix "at"; see .BR openat (2). Since glibc 2.10, this macro is also implicitly defined if .B _POSIX_C_SOURCE is defined with a value greater than or equal to 200809L. .TP .B _GNU_SOURCE Defining this macro (with any value) implicitly defines .BR _ATFILE_SOURCE , .BR _LARGEFILE64_SOURCE , .BR _ISOC99_SOURCE , .BR _XOPEN_SOURCE_EXTENDED , .BR _POSIX_SOURCE , .B _POSIX_C_SOURCE with the value 200809L (200112L before glibc 2.10; 199506L before glibc 2.5; 199309L before glibc 2.1) and .B _XOPEN_SOURCE with the value 700 (600 before glibc 2.10; 500 before glibc 2.2). In addition, various GNU-specific extensions are also exposed. .IP Since glibc 2.19, defining .B _GNU_SOURCE also has the effect of implicitly defining .BR _DEFAULT_SOURCE . Before glibc 2.20, defining .B _GNU_SOURCE also had the effect of implicitly defining .B _BSD_SOURCE and .BR _SVID_SOURCE . .TP .BR _REENTRANT " [[deprecated]]" Historically, on various C libraries it was necessary to define this macro in all multithreaded code. .\" Zack Weinberg .\" There did once exist C libraries where it was necessary. The ones .\" I remember were proprietary Unix vendor libcs from the mid-1990s .\" You would get completely unlocked stdio without _REENTRANT. (Some C libraries may still require this.) In glibc, this macro also exposed definitions of certain reentrant functions. .IP However, glibc has been thread-safe by default for many years; since glibc 2.3, the only effect of defining .B _REENTRANT has been to enable one or two of the same declarations that are also enabled by defining .B _POSIX_C_SOURCE with a value of 199506L or greater. .IP .B _REENTRANT is now obsolete. In glibc 2.25 and later, defining .B _REENTRANT is equivalent to defining .B _POSIX_C_SOURCE with the value 199506L. If a higher POSIX conformance level is selected by any other means (such as .B _POSIX_C_SOURCE itself, .BR _XOPEN_SOURCE , .BR _DEFAULT_SOURCE , or .BR _GNU_SOURCE ), then defining .B _REENTRANT has no effect. .IP This macro is automatically defined if one compiles with .IR cc\~\-pthread . .TP .BR _THREAD_SAFE " [[deprecated]]" Synonym for .BR _REENTRANT , provided for compatibility with some other implementations. .TP .BR _FORTIFY_SOURCE " (since glibc 2.3.4)" .\" For more detail, see: .\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html .\" [PATCH] Object size checking to prevent (some) buffer overflows .\" * From: Jakub Jelinek .\" * To: gcc-patches at gcc dot gnu dot org .\" * Date: Tue, 21 Sep 2004 04:16:40 -0400 Defining this macro causes some lightweight checks to be performed to detect some buffer overflow errors when employing various string and memory manipulation functions (for example, .BR memcpy (3), .BR memset (3), .BR stpcpy (3), .BR strcpy (3), .BR strncpy (3), .BR strcat (3), .BR strncat (3), .BR sprintf (3), .BR snprintf (3), .BR vsprintf (3), .BR vsnprintf (3), .BR gets (3), and wide character variants thereof). For some functions, argument consistency is checked; for example, a check is made that .BR open (2) has been supplied with a .I mode argument when the specified flags include .BR O_CREAT . Not all problems are detected, just some common cases. .\" Look for __USE_FORTIFY_LEVEL in the header files .IP If .B _FORTIFY_SOURCE is set to 1, with compiler optimization level 1 .RI ( "gcc\ \-O1" ) and above, checks that shouldn't change the behavior of conforming programs are performed. With .B _FORTIFY_SOURCE set to 2, some more checking is added, but some conforming programs might fail. .\" For example, given the following code .\" int d; .\" char buf[1000], buf[1000]; .\" strcpy(fmt, "Hello world\n%n"); .\" snprintf(buf, sizeof(buf), fmt, &d); .\" .\" Compiling with "gcc -D_FORTIFY_SOURCE=2 -O1" and then running will .\" cause the following diagnostic at run time at the snprintf() call .\" .\" *** %n in writable segment detected *** .\" Aborted (core dumped) .\" .IP Some of the checks can be performed at compile time (via macros logic implemented in header files), and result in compiler warnings; other checks take place at run time, and result in a run-time error if the check fails. .IP With .B _FORTIFY_SOURCE set to 3, additional checking is added to intercept some function calls used with an argument of variable size where the compiler can deduce an upper bound for its value. For example, a program where .BR malloc (3)'s size argument is variable can now be fortified. .IP Use of this macro requires compiler support, available since gcc 4.0 and clang 2.6. Use of .B _FORTIFY_SOURCE set to 3 requires gcc 12.0 or later, or clang 9.0 or later, in conjunction with glibc 2.33 or later. .\" glibc is not an absolute requirement (gcc has libssp; NetBSD/newlib .\" and Darwin each have their own implementation), but let's keep it .\" simple. .SS Default definitions, implicit definitions, and combining definitions If no feature test macros are explicitly defined, then the following feature test macros are defined by default: .B _BSD_SOURCE (in glibc 2.19 and earlier), .B _SVID_SOURCE (in glibc 2.19 and earlier), .B _DEFAULT_SOURCE (since glibc 2.19), .BR _POSIX_SOURCE , and .BR _POSIX_C_SOURCE =200809L (200112L before glibc 2.10; 199506L before glibc 2.4; 199309L before glibc 2.1). .P If any of .BR __STRICT_ANSI__ , .BR _ISOC99_SOURCE , .B _ISOC11_SOURCE (since glibc 2.18), .B _ISOC23_SOURCE (since glibc 2.40), .BR _POSIX_SOURCE , .BR _POSIX_C_SOURCE , .BR _XOPEN_SOURCE , .B _XOPEN_SOURCE_EXTENDED (in glibc 2.11 and earlier), .B _BSD_SOURCE (in glibc 2.19 and earlier), or .B _SVID_SOURCE (in glibc 2.19 and earlier) is explicitly defined, then .BR _BSD_SOURCE , .BR _SVID_SOURCE , and .B _DEFAULT_SOURCE are not defined by default. .SH STANDARDS POSIX.1 specifies .BR _POSIX_C_SOURCE , .BR _POSIX_SOURCE , and .BR _XOPEN_SOURCE . .P .B _FILE_OFFSET_BITS is not specified by any standard, but is employed on some other implementations. .P .BR _BSD_SOURCE , .BR _SVID_SOURCE , .BR _DEFAULT_SOURCE , .BR _ATFILE_SOURCE , .BR _GNU_SOURCE , .BR _FORTIFY_SOURCE , .BR _REENTRANT , and .B _THREAD_SAFE are specific to glibc. .SH HISTORY .B _XOPEN_SOURCE_EXTENDED was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later. .SH NOTES .I is a Linux/glibc-specific header file. Other systems have an analogous file, but typically with a different name. This header file is automatically included by other header files as required: it is not necessary to explicitly include it in order to employ feature test macros. .P According to which of the above feature test macros are defined, .I internally defines various other macros that are checked by other glibc header files. These macros have names prefixed by two underscores (e.g., .BR __USE_MISC ). Programs should .I never define these macros directly: instead, the appropriate feature test macro(s) from the list above should be employed. .SH EXAMPLES The program below can be used to explore how the various feature test macros are set depending on the glibc version and what feature test macros are explicitly set. The following shell session, on a system with glibc 2.10, shows some examples of what we would see: .P .in +4n .EX .RB $ " cc ftm.c" .RB $ " ./a.out" _POSIX_SOURCE defined _POSIX_C_SOURCE defined: 200809L _BSD_SOURCE defined _SVID_SOURCE defined _ATFILE_SOURCE defined .RB $ " cc \-D_XOPEN_SOURCE=500 ftm.c" .RB $ " ./a.out" _POSIX_SOURCE defined _POSIX_C_SOURCE defined: 199506L _XOPEN_SOURCE defined: 500 .RB $ " cc \-D_GNU_SOURCE ftm.c" .RB $ " ./a.out" _POSIX_SOURCE defined _POSIX_C_SOURCE defined: 200809L _ISOC99_SOURCE defined _XOPEN_SOURCE defined: 700 _XOPEN_SOURCE_EXTENDED defined _LARGEFILE64_SOURCE defined _BSD_SOURCE defined _SVID_SOURCE defined _ATFILE_SOURCE defined _GNU_SOURCE defined .EE .in .SS Program source \& .EX /* ftm.c */ \& #include #include #include #include \& int main(int argc, char *argv[]) { #ifdef _POSIX_SOURCE printf("_POSIX_SOURCE defined\[rs]n"); #endif \& #ifdef _POSIX_C_SOURCE printf("_POSIX_C_SOURCE defined: %jdL\[rs]n", (intmax_t) _POSIX_C_SOURCE); #endif \& #ifdef _ISOC99_SOURCE printf("_ISOC99_SOURCE defined\[rs]n"); #endif \& #ifdef _ISOC11_SOURCE printf("_ISOC11_SOURCE defined\[rs]n"); #endif \& #ifdef _ISOC23_SOURCE printf("_ISOC23_SOURCE defined\[rs]n"); #endif \& #ifdef _XOPEN_SOURCE printf("_XOPEN_SOURCE defined: %d\[rs]n", _XOPEN_SOURCE); #endif \& #ifdef _XOPEN_SOURCE_EXTENDED printf("_XOPEN_SOURCE_EXTENDED defined\[rs]n"); #endif \& #ifdef _LARGEFILE64_SOURCE printf("_LARGEFILE64_SOURCE defined\[rs]n"); #endif \& #ifdef _FILE_OFFSET_BITS printf("_FILE_OFFSET_BITS defined: %d\[rs]n", _FILE_OFFSET_BITS); #endif \& #ifdef _TIME_BITS printf("_TIME_BITS defined: %d\[rs]n", _TIME_BITS); #endif \& #ifdef _BSD_SOURCE printf("_BSD_SOURCE defined\[rs]n"); #endif \& #ifdef _SVID_SOURCE printf("_SVID_SOURCE defined\[rs]n"); #endif \& #ifdef _DEFAULT_SOURCE printf("_DEFAULT_SOURCE defined\[rs]n"); #endif \& #ifdef _ATFILE_SOURCE printf("_ATFILE_SOURCE defined\[rs]n"); #endif \& #ifdef _GNU_SOURCE printf("_GNU_SOURCE defined\[rs]n"); #endif \& #ifdef _REENTRANT printf("_REENTRANT defined\[rs]n"); #endif \& #ifdef _THREAD_SAFE printf("_THREAD_SAFE defined\[rs]n"); #endif \& #ifdef _FORTIFY_SOURCE printf("_FORTIFY_SOURCE defined\[rs]n"); #endif \& exit(EXIT_SUCCESS); } .EE .SH SEE ALSO .BR libc (7), .BR standards (7), .BR system_data_types (7) .P The section "Feature Test Macros" under .IR "info libc" . .\" But beware: the info libc document is out of date (Jul 07, mtk) .P .I /usr/include/features.h