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