1@node Feature Test Macros 2@subsection Feature Test Macros 3 4@cindex feature test macros 5The exact set of features available when you compile a source file 6is controlled by which @dfn{feature test macros} you define. 7 8If you compile your programs using @samp{gcc -ansi}, you get only the 9@w{ISO C} library features, unless you explicitly request additional 10features by defining one or more of the feature macros. 11@xref{Invoking GCC,, GNU CC Command Options, gcc, The GNU CC Manual}, 12for more information about GCC options. 13 14You should define these macros by using @samp{#define} preprocessor 15directives at the top of your source code files. These directives 16@emph{must} come before any @code{#include} of a system header file. It 17is best to make them the very first thing in the file, preceded only by 18comments. You could also use the @samp{-D} option to GCC, but it's 19better if you make the source files indicate their own meaning in a 20self-contained way. 21 22This system exists to allow the library to conform to multiple standards. 23Although the different standards are often described as supersets of each 24other, they are usually incompatible because larger standards require 25functions with names that smaller ones reserve to the user program. This 26is not mere pedantry --- it has been a problem in practice. For instance, 27some non-GNU programs define functions named @code{getline} that have 28nothing to do with this library's @code{getline}. They would not be 29compilable if all features were enabled indiscriminately. 30 31This should not be used to verify that a program conforms to a limited 32standard. It is insufficient for this purpose, as it will not protect you 33from including header files outside the standard, or relying on semantics 34undefined within the standard. 35 36@defvr Macro _POSIX_SOURCE 37@standards{POSIX.1, (none)} 38If you define this macro, then the functionality from the POSIX.1 39standard (IEEE Standard 1003.1) is available, as well as all of the 40@w{ISO C} facilities. 41 42The state of @code{_POSIX_SOURCE} is irrelevant if you define the 43macro @code{_POSIX_C_SOURCE} to a positive integer. 44@end defvr 45 46@defvr Macro _POSIX_C_SOURCE 47@standards{POSIX.2, (none)} 48Define this macro to a positive integer to control which POSIX 49functionality is made available. The greater the value of this macro, 50the more functionality is made available. 51 52If you define this macro to a value greater than or equal to @code{1}, 53then the functionality from the 1990 edition of the POSIX.1 standard 54(IEEE Standard 1003.1-1990) is made available. 55 56If you define this macro to a value greater than or equal to @code{2}, 57then the functionality from the 1992 edition of the POSIX.2 standard 58(IEEE Standard 1003.2-1992) is made available. 59 60If you define this macro to a value greater than or equal to @code{199309L}, 61then the functionality from the 1993 edition of the POSIX.1b standard 62(IEEE Standard 1003.1b-1993) is made available. 63 64If you define this macro to a value greater than or equal to 65@code{199506L}, then the functionality from the 1995 edition of the 66POSIX.1c standard (IEEE Standard 1003.1c-1995) is made available. 67 68If you define this macro to a value greater than or equal to 69@code{200112L}, then the functionality from the 2001 edition of the 70POSIX standard (IEEE Standard 1003.1-2001) is made available. 71 72If you define this macro to a value greater than or equal to 73@code{200809L}, then the functionality from the 2008 edition of the 74POSIX standard (IEEE Standard 1003.1-2008) is made available. 75 76Greater values for @code{_POSIX_C_SOURCE} will enable future extensions. 77The POSIX standards process will define these values as necessary, and 78@theglibc{} should support them some time after they become standardized. 79The 1996 edition of POSIX.1 (ISO/IEC 9945-1: 1996) states that 80if you define @code{_POSIX_C_SOURCE} to a value greater than 81or equal to @code{199506L}, then the functionality from the 1996 82edition is made available. In general, in @theglibc{}, bugfixes to 83the standards are included when specifying the base version; e.g., 84POSIX.1-2004 will always be included with a value of @code{200112L}. 85@end defvr 86 87@defvr Macro _XOPEN_SOURCE 88@defvrx Macro _XOPEN_SOURCE_EXTENDED 89@standards{X/Open, (none)} 90If you define this macro, functionality described in the X/Open 91Portability Guide is included. This is a superset of the POSIX.1 and 92POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and 93@code{_POSIX_C_SOURCE} are automatically defined. 94 95As the unification of all Unices, functionality only available in 96BSD and SVID is also included. 97 98If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more 99functionality is available. The extra functions will make all functions 100available which are necessary for the X/Open Unix brand. 101 102If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes 103all functionality described so far plus some new definitions from the 104Single Unix Specification, @w{version 2}. The value @math{600} 105(corresponding to the sixth revision) includes definitions from SUSv3, 106and using @math{700} (the seventh revision) includes definitions from 107SUSv4. 108@end defvr 109 110@defvr Macro _LARGEFILE_SOURCE 111@standards{X/Open, (NONE)} 112If this macro is defined some extra functions are available which 113rectify a few shortcomings in all previous standards. Specifically, 114the functions @code{fseeko} and @code{ftello} are available. Without 115these functions the difference between the @w{ISO C} interface 116(@code{fseek}, @code{ftell}) and the low-level POSIX interface 117(@code{lseek}) would lead to problems. 118 119This macro was introduced as part of the Large File Support extension (LFS). 120@end defvr 121 122@defvr Macro _LARGEFILE64_SOURCE 123@standards{X/Open, (NONE)} 124If you define this macro an additional set of functions is made available 125which enables @w{32 bit} systems to use files of sizes beyond 126the usual limit of 2GB. This interface is not available if the system 127does not support files that large. On systems where the natural file 128size limit is greater than 2GB (i.e., on @w{64 bit} systems) the new 129functions are identical to the replaced functions. 130 131The new functionality is made available by a new set of types and 132functions which replace the existing ones. The names of these new objects 133contain @code{64} to indicate the intention, e.g., @code{off_t} 134vs. @code{off64_t} and @code{fseeko} vs. @code{fseeko64}. 135 136This macro was introduced as part of the Large File Support extension 137(LFS). It is a transition interface for the period when @w{64 bit} 138offsets are not generally used (see @code{_FILE_OFFSET_BITS}). 139@end defvr 140 141@defvr Macro _FILE_OFFSET_BITS 142@standards{X/Open, (NONE)} 143This macro determines which file system interface shall be used, one 144replacing the other. Whereas @code{_LARGEFILE64_SOURCE} makes the @w{64 145bit} interface available as an additional interface, 146@code{_FILE_OFFSET_BITS} allows the @w{64 bit} interface to 147replace the old interface. 148 149If @code{_FILE_OFFSET_BITS} is defined to the 150value @code{32}, the @w{32 bit} interface is used and 151types like @code{off_t} have a size of @w{32 bits} on @w{32 bit} 152systems. 153 154If the macro is defined to the value @code{64}, the large file interface 155replaces the old interface. I.e., the functions are not made available 156under different names (as they are with @code{_LARGEFILE64_SOURCE}). 157Instead the old function names now reference the new functions, e.g., a 158call to @code{fseeko} now indeed calls @code{fseeko64}. 159 160If the macro is not defined it currently defaults to @code{32}, but 161this default is planned to change due to a need to update 162@code{time_t} for Y2038 safety, and applications should not rely on 163the default. 164 165This macro should only be selected if the system provides mechanisms for 166handling large files. On @w{64 bit} systems this macro has no effect 167since the @code{*64} functions are identical to the normal functions. 168 169This macro was introduced as part of the Large File Support extension 170(LFS). 171@end defvr 172 173@defvr Macro _TIME_BITS 174Define this macro to control the bit size of @code{time_t}, and therefore 175the bit size of all @code{time_t}-derived types and the prototypes of all 176related functions. 177 178@enumerate 179 180@item 181If @code{_TIME_BITS} is undefined, the bit size of @code{time_t} is 182architecture dependent. Currently it defaults to 64 bits on most 183architectures. Although it defaults to 32 bits on some traditional 184architectures (i686, ARM), this is planned to change and applications 185should not rely on this. 186 187@item 188If @code{_TIME_BITS} is defined to be 64, @code{time_t} is defined 189to be a 64-bit integer. On platforms where @code{time_t} was 190traditionally 32 bits, calls to proper syscalls depend on the 191Linux kernel version on which the system is running. For Linux kernel 192version above @b{5.1} syscalls supporting 64-bit time are used. Otherwise, 193a fallback code is used with legacy (i.e. 32-bit) syscalls. 194 195@item 196If @code{_TIME_BITS} is defined to be 32, @code{time_t} is defined to 197be a 32-bit integer where that is supported. This is not recommended, 198as 32-bit @code{time_t} stops working in the year 2038. 199 200@item 201For any other use case a compile-time error is emitted. 202@end enumerate 203 204@code{_TIME_BITS=64} can be defined only when 205@code{_FILE_OFFSET_BITS=64} is also defined. 206 207By using this macro certain ports gain support for 64-bit time and as 208a result become immune to the Y2038 problem. 209@end defvr 210 211@defvr Macro _ISOC99_SOURCE 212@standards{GNU, (none)} 213If this macro is defined, features from ISO C99 are included. Since 214these features are included by default, this macro is mostly relevant 215when the compiler uses an earlier language version. 216@end defvr 217 218@defvr Macro _ISOC11_SOURCE 219@standards{C11, (none)} 220If this macro is defined, ISO C11 extensions to ISO C99 are included. 221@end defvr 222 223@defvr Macro _ISOC2X_SOURCE 224@standards{C2X, (none)} 225If this macro is defined, ISO C2X extensions to ISO C11 are included. 226Only some features from this draft standard are supported by 227@theglibc{}. 228@end defvr 229 230@defvr Macro __STDC_WANT_LIB_EXT2__ 231@standards{ISO, (none)} 232If you define this macro to the value @code{1}, features from ISO/IEC 233TR 24731-2:2010 (Dynamic Allocation Functions) are enabled. Only some 234of the features from this TR are supported by @theglibc{}. 235@end defvr 236 237@defvr Macro __STDC_WANT_IEC_60559_BFP_EXT__ 238@standards{ISO, (none)} 239If you define this macro, features from ISO/IEC TS 18661-1:2014 240(Floating-point extensions for C: Binary floating-point arithmetic) 241are enabled. Only some of the features from this TS are supported by 242@theglibc{}. 243@end defvr 244 245@defvr Macro __STDC_WANT_IEC_60559_FUNCS_EXT__ 246@standards{ISO, (none)} 247If you define this macro, features from ISO/IEC TS 18661-4:2015 248(Floating-point extensions for C: Supplementary functions) are 249enabled. Only some of the features from this TS are supported by 250@theglibc{}. 251@end defvr 252 253@defvr Macro __STDC_WANT_IEC_60559_TYPES_EXT__ 254@standards{ISO, (none)} 255If you define this macro, features from ISO/IEC TS 18661-3:2015 256(Floating-point extensions for C: Interchange and extended types) are 257enabled. Only some of the features from this TS are supported by 258@theglibc{}. 259@end defvr 260 261@defvr Macro __STDC_WANT_IEC_60559_EXT__ 262@standards{ISO, (none)} 263If you define this macro, ISO C2X features defined in Annex F of that 264standard are enabled. This affects declarations of the 265@code{totalorder} functions and functions related to NaN payloads. 266@end defvr 267 268@defvr Macro _GNU_SOURCE 269@standards{GNU, (none)} 270If you define this macro, everything is included: @w{ISO C89}, @w{ISO 271C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions. In 272the cases where POSIX.1 conflicts with BSD, the POSIX definitions take 273precedence. 274@end defvr 275 276@defvr Macro _DEFAULT_SOURCE 277@standards{GNU, (none)} 278If you define this macro, most features are included apart from 279X/Open, LFS and GNU extensions: the effect is to enable features from 280the 2008 edition of POSIX, as well as certain BSD and SVID features 281without a separate feature test macro to control them. 282 283Be aware that compiler options also affect included features: 284 285@itemize 286@item 287If you use a strict conformance option, features beyond those from the 288compiler's language version will be disabled, though feature test 289macros may be used to enable them. 290 291@item 292Features enabled by compiler options are not overridden by feature 293test macros. 294@end itemize 295@end defvr 296 297@defvr Macro _ATFILE_SOURCE 298@standards{GNU, (none)} 299If this macro is defined, additional @code{*at} interfaces are 300included. 301@end defvr 302 303@defvr Macro _FORTIFY_SOURCE 304@standards{GNU, (none)} 305If this macro is defined to @math{1}, security hardening is added to 306various library functions. If defined to @math{2}, even stricter 307checks are applied. If defined to @math{3}, @theglibc{} may also use 308checks that may have an additional performance overhead. 309@end defvr 310 311@defvr Macro _DYNAMIC_STACK_SIZE_SOURCE 312@standards{GNU, (none)} 313If this macro is defined, correct (but non compile-time constant) 314MINSIGSTKSZ, SIGSTKSZ and PTHREAD_STACK_MIN are defined. 315@end defvr 316 317@defvr Macro _REENTRANT 318@defvrx Macro _THREAD_SAFE 319@standards{Obsolete, (none)} 320These macros are obsolete. They have the same effect as defining 321@code{_POSIX_C_SOURCE} with the value @code{199506L}. 322 323Some very old C libraries required one of these macros to be defined 324for basic functionality (e.g.@: @code{getchar}) to be thread-safe. 325@end defvr 326 327We recommend you use @code{_GNU_SOURCE} in new programs. If you don't 328specify the @samp{-ansi} option to GCC, or other conformance options 329such as @option{-std=c99}, and don't define any of these macros 330explicitly, the effect is the same as defining @code{_DEFAULT_SOURCE} 331to 1. 332 333When you define a feature test macro to request a larger class of features, 334it is harmless to define in addition a feature test macro for a subset of 335those features. For example, if you define @code{_POSIX_C_SOURCE}, then 336defining @code{_POSIX_SOURCE} as well has no effect. Likewise, if you 337define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or 338@code{_POSIX_C_SOURCE} as well has no effect. 339