]>
Commit | Line | Data |
---|---|---|
55b726d1 MK |
1 | .\" This manpage is Copyright (C) 2006, Michael Kerrisk |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
55b726d1 MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
55b726d1 MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
55b726d1 MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
55b726d1 | 24 | .\" |
e8426ca2 | 25 | .TH FEATURE_TEST_MACROS 7 2020-04-11 "Linux" "Linux Programmer's Manual" |
55b726d1 | 26 | .SH NAME |
a8e7c990 | 27 | feature_test_macros \- feature test macros |
55b726d1 MK |
28 | .SH DESCRIPTION |
29 | Feature test macros allow the programmer to control the definitions that | |
30 | are exposed by system header files when a program is compiled. | |
5711c04f | 31 | .PP |
e0530cbb MK |
32 | .B NOTE: |
33 | In order to be effective, a feature test macro | |
34 | .IR "must be defined before including any header files" . | |
b220f1b5 | 35 | This can be done either in the compilation command |
e0530cbb MK |
36 | .RI ( "cc \-DMACRO=value" ) |
37 | or by defining the macro within the source code before | |
38 | including any headers. | |
1be4da28 MK |
39 | The requirement that the macro must be defined before including any |
40 | header file exists because header files may freely include one another. | |
41 | Thus, for example, in the following lines, defining the | |
42 | .B _GNU_SOURCE | |
43 | macro may have no effect because the header | |
44 | .I <abc.h> | |
45 | itself includes | |
46 | .I <xyz.h> | |
47 | (POSIX explicitly allows this): | |
48 | .PP | |
49 | .in +4n | |
50 | .EX | |
51 | #include <abc.h> | |
52 | #define _GNU_SOURCE | |
53 | #include <xys.h> | |
54 | .EE | |
55 | .in | |
5711c04f | 56 | .PP |
f8b21213 | 57 | Some feature test macros are useful for creating portable applications, |
c8f2dd47 MK |
58 | by preventing nonstandard definitions from being exposed. |
59 | Other macros can be used to expose nonstandard definitions that | |
55b726d1 | 60 | are not exposed by default. |
5711c04f | 61 | .PP |
c13182ef | 62 | The precise effects of each of the feature test macros described below |
55b726d1 MK |
63 | can be ascertained by inspecting the |
64 | .I <features.h> | |
65 | header file. | |
6e558a81 MK |
66 | .BR Note : |
67 | applications do | |
68 | .I not | |
69 | need to directly include | |
70 | .IR <features.h> ; | |
71 | indeed, doing so is actively discouraged. | |
72 | See NOTES. | |
18409fb8 MK |
73 | .SS Specification of feature test macro requirements in manual pages |
74 | When a function requires that a feature test macro is defined, | |
922cf8f6 | 75 | the manual page SYNOPSIS typically includes a note of the following form |
18409fb8 | 76 | (this example from the |
cab82d65 | 77 | .BR acct (2) |
e9600b20 | 78 | manual page): |
6545cc56 | 79 | .PP |
cab82d65 | 80 | .RS 8 |
cab82d65 | 81 | .B #include <unistd.h> |
6545cc56 | 82 | .PP |
cab82d65 | 83 | .BI "int acct(const char *" filename ); |
6545cc56 | 84 | .PP |
b9c93deb | 85 | .EX |
18409fb8 MK |
86 | .in -4n |
87 | Feature Test Macro Requirements for glibc (see | |
88 | .BR feature_test_macros (7)): | |
b8302363 | 89 | .EE |
18409fb8 | 90 | .in |
6545cc56 | 91 | .PP |
cab82d65 MK |
92 | .BR acct (): |
93 | _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500) | |
18409fb8 MK |
94 | .RE |
95 | .PP | |
aeb9b6a6 MK |
96 | The |
97 | .B || | |
98 | means that in order to obtain the declaration of | |
cab82d65 | 99 | .BR acct (2) |
18409fb8 | 100 | from |
cab82d65 | 101 | .IR <unistd.h> , |
aeb9b6a6 MK |
102 | .I either |
103 | of the following macro | |
18409fb8 | 104 | definitions must be made before including any header files: |
9c40f2b9 MK |
105 | .PP |
106 | .in +4n | |
107 | .EX | |
922cf8f6 | 108 | #define _BSD_SOURCE |
cab82d65 | 109 | #define _XOPEN_SOURCE /* or any value < 500 */ |
9c40f2b9 MK |
110 | .EE |
111 | .in | |
18409fb8 MK |
112 | .PP |
113 | Alternatively, equivalent definitions can be included in the | |
114 | compilation command: | |
408731d4 MK |
115 | .PP |
116 | .in +4n | |
117 | .EX | |
5b8dbfd4 | 118 | cc \-D_BSD_SOURCE |
cab82d65 | 119 | cc \-D_XOPEN_SOURCE # Or any value < 500 |
408731d4 MK |
120 | .EE |
121 | .in | |
18409fb8 | 122 | .PP |
922cf8f6 | 123 | Note that, as described below, |
7f9a8f08 | 124 | .BR "some feature test macros are defined by default" , |
922cf8f6 | 125 | so that it may not always be necessary to |
e9600b20 MK |
126 | explicitly specify the feature test macro(s) shown in the |
127 | SYNOPSIS. | |
5711c04f | 128 | .PP |
e9600b20 MK |
129 | In a few cases, manual pages use a shorthand for expressing the |
130 | feature test macro requirements (this example from | |
131 | .BR readahead (2)): | |
6545cc56 | 132 | .PP |
408731d4 MK |
133 | .in +4n |
134 | .EX | |
e9600b20 MK |
135 | .B #define _GNU_SOURCE |
136 | .B #include <fcntl.h> | |
6545cc56 | 137 | .PP |
e9600b20 | 138 | .BI "ssize_t readahead(int " fd ", off64_t *" offset ", size_t " count ); |
408731d4 MK |
139 | .EE |
140 | .in | |
e9600b20 | 141 | .PP |
e0bf9127 | 142 | This format is employed in cases where only a single |
e9600b20 MK |
143 | feature test macro can be used to expose the function |
144 | declaration, and that macro is not defined by default. | |
18409fb8 | 145 | .SS Feature test macros understood by glibc |
f125c769 | 146 | The paragraphs below explain how feature test macros are handled |
aeb9b6a6 MK |
147 | in Linux glibc 2.\fIx\fP, |
148 | .I x | |
149 | > 0. | |
5711c04f | 150 | .PP |
f125c769 MK |
151 | First, though a summary of a few details for the impatient: |
152 | .IP * 3 | |
153 | The macros that you most likely need to use in modern source code are | |
154 | .BR _POSIX_C_SOURCE | |
155 | (for definitions from various versions of POSIX.1), | |
156 | .BR _XOPEN_SOURCE | |
1d229d9f | 157 | (for definitions from various versions of SUS), |
f125c769 MK |
158 | .BR _GNU_SOURCE |
159 | (for GNU and/or Linux specific stuff), and | |
160 | .BR _DEFAULT_SOURCE | |
161 | (to get definitions that would normally be provided by default). | |
162 | .IP * | |
38d9e98e | 163 | Certain macros are defined with default values. |
2c767761 | 164 | Thus, although one or more macros may be indicated as being |
38d9e98e MK |
165 | required in the SYNOPSIS of a man page, |
166 | it may not be necessary to define them explicitly. | |
167 | Full details of the defaults are given later in this man page. | |
168 | .IP * | |
f125c769 MK |
169 | Defining |
170 | .BR _XOPEN_SOURCE | |
171 | with a value of 600 or greater produces the same effects as defining | |
172 | .BR _POSIX_C_SOURCE | |
173 | with a value of 200112L or greater. | |
174 | Where one sees | |
408731d4 MK |
175 | .IP |
176 | .in +4n | |
177 | .EX | |
178 | _POSIX_C_SOURCE >= 200112L | |
179 | .EE | |
180 | .in | |
f125c769 MK |
181 | .IP |
182 | in the feature test macro requirements in the SYNOPSIS of a man page, | |
183 | it is implicit that the following has the same effect: | |
408731d4 MK |
184 | .IP |
185 | .in +4n | |
186 | .EX | |
187 | _XOPEN_SOURCE >= 600 | |
188 | .EE | |
189 | .in | |
f125c769 MK |
190 | .IP * |
191 | Defining | |
192 | .BR _XOPEN_SOURCE | |
193 | with a value of 700 or greater produces the same effects as defining | |
194 | .BR _POSIX_C_SOURCE | |
195 | with a value of 200809L or greater. | |
196 | Where one sees | |
408731d4 MK |
197 | .IP |
198 | .in +4n | |
199 | .EX | |
200 | _POSIX_C_SOURCE >= 200809L | |
201 | .EE | |
202 | .in | |
f125c769 MK |
203 | .IP |
204 | in the feature test macro requirements in the SYNOPSIS of a man page, | |
205 | it is implicit that the following has the same effect: | |
408731d4 MK |
206 | .IP |
207 | .in +4n | |
208 | .EX | |
209 | _XOPEN_SOURCE >= 700 | |
210 | .EE | |
211 | .in | |
3efa27b5 | 212 | .\" The details in glibc 2.0 are simpler, but combining a |
93d5a2a1 MK |
213 | .\" a description of them with the details in later glibc versions |
214 | .\" would make for a complicated description. | |
5711c04f | 215 | .PP |
93d5a2a1 | 216 | Linux glibc understands the following feature test macros: |
0019177e | 217 | .TP |
4769db24 MK |
218 | .B __STRICT_ANSI__ |
219 | ISO Standard C. | |
220 | This macro is implicitly defined by | |
221 | .BR gcc (1) | |
222 | when invoked with, for example, the | |
223 | .I -std=c99 | |
224 | or | |
225 | .I -ansi | |
226 | flag. | |
55b726d1 MK |
227 | .TP |
228 | .B _POSIX_C_SOURCE | |
922cf8f6 MK |
229 | Defining this macro causes header files to expose definitions as follows: |
230 | .RS | |
231 | .IP \(bu 3 | |
232 | The value 1 exposes definitions conforming to POSIX.1-1990 and | |
233 | ISO C (1990). | |
234 | .IP \(bu | |
235 | The value 2 or greater additionally exposes | |
18409fb8 | 236 | definitions for POSIX.2-1992. |
922cf8f6 MK |
237 | .IP \(bu |
238 | The value 199309L or greater additionally exposes | |
55b726d1 | 239 | definitions for POSIX.1b (real-time extensions). |
33a0ccb2 | 240 | .\" 199506L functionality is available only since glibc 2.1 |
922cf8f6 MK |
241 | .IP \(bu |
242 | The value 199506L or greater additionally exposes | |
55b726d1 | 243 | definitions for POSIX.1c (threads). |
922cf8f6 MK |
244 | .IP \(bu |
245 | (Since glibc 2.3.3) | |
b694081a | 246 | The value 200112L or greater additionally exposes definitions corresponding |
f04d68ba MK |
247 | to the POSIX.1-2001 base specification (excluding the XSI extension). |
248 | This value also causes C95 (since glibc 2.12) and | |
249 | C99 (since glibc 2.10) features to be exposed | |
250 | (in other words, the equivalent of defining | |
251 | .BR _ISOC99_SOURCE ). | |
6e047f16 MK |
252 | .IP \(bu |
253 | (Since glibc 2.10) | |
b694081a | 254 | The value 200809L or greater additionally exposes definitions corresponding |
6e047f16 | 255 | to the POSIX.1-2008 base specification (excluding the XSI extension). |
922cf8f6 | 256 | .RE |
c13182ef | 257 | .TP |
bcb564f2 | 258 | .B _POSIX_SOURCE |
55b726d1 MK |
259 | Defining this obsolete macro with any value is equivalent to defining |
260 | .B _POSIX_C_SOURCE | |
261 | with the value 1. | |
5711c04f | 262 | .IP |
c1016e87 MK |
263 | Since this macro is obsolete, |
264 | its usage is generally not documented when discussing | |
265 | feature test macro requirements in the man pages. | |
55b726d1 MK |
266 | .TP |
267 | .B _XOPEN_SOURCE | |
922cf8f6 MK |
268 | Defining this macro causes header files to expose definitions as follows: |
269 | .RS | |
270 | .IP \(bu 3 | |
271 | Defining with any value exposes | |
55b726d1 | 272 | definitions conforming to POSIX.1, POSIX.2, and XPG4. |
922cf8f6 MK |
273 | .IP \(bu |
274 | The value 500 or greater additionally exposes | |
55b726d1 | 275 | definitions for SUSv2 (UNIX 98). |
922cf8f6 MK |
276 | .IP \(bu |
277 | (Since glibc 2.2) The value 600 or greater additionally exposes | |
c13182ef | 278 | definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification |
5709731e | 279 | plus the XSI extension) and C99 definitions. |
6e047f16 MK |
280 | .IP \(bu |
281 | (Since glibc 2.10) The value 700 or greater additionally exposes | |
282 | definitions for SUSv4 (i.e., the POSIX.1-2008 base specification | |
283 | plus the XSI extension). | |
922cf8f6 | 284 | .RE |
d4e80b4d MK |
285 | .IP |
286 | If | |
287 | .B __STRICT_ANSI__ | |
288 | is not defined, or | |
289 | .BR _XOPEN_SOURCE | |
290 | is defined with a value greater than or equal to 500 | |
291 | .I and | |
292 | neither | |
293 | .B _POSIX_SOURCE | |
25ca8ac7 | 294 | nor |
d4e80b4d MK |
295 | .B _POSIX_C_SOURCE |
296 | is explicitly defined, then | |
297 | the following macros are implicitly defined: | |
298 | .RS | |
299 | .IP \(bu 3 | |
300 | .B _POSIX_SOURCE | |
301 | is defined with the value 1. | |
302 | .IP \(bu | |
303 | .B _POSIX_C_SOURCE | |
304 | is defined, according to the value of | |
305 | .BR _XOPEN_SOURCE : | |
a62ca28a | 306 | .RS |
d4e80b4d MK |
307 | .TP |
308 | .BR _XOPEN_SOURCE " < 500" | |
309 | .B _POSIX_C_SOURCE | |
310 | is defined with the value 2. | |
311 | .TP | |
312 | .RB "500 <= " _XOPEN_SOURCE " < 600" | |
313 | .B _POSIX_C_SOURCE | |
314 | is defined with the value 199506L. | |
315 | .TP | |
316 | .RB "600 <= " _XOPEN_SOURCE " < 700" | |
317 | .B _POSIX_C_SOURCE | |
318 | is defined with the value 200112L. | |
319 | .TP | |
320 | .RB "700 <= " _XOPEN_SOURCE " (since glibc 2.10)" | |
321 | .B _POSIX_C_SOURCE | |
322 | is defined with the value 200809L. | |
323 | .RE | |
324 | .RE | |
a7d7000f MK |
325 | .IP |
326 | In addition, defining | |
327 | .BR _XOPEN_SOURCE | |
328 | with a value of 500 or greater produces the same effects as defining | |
329 | .BR _XOPEN_SOURCE_EXTENDED . | |
55b726d1 MK |
330 | .TP |
331 | .B _XOPEN_SOURCE_EXTENDED | |
49d2e094 MK |
332 | If this macro is defined, |
333 | .I and | |
0daa9e92 | 334 | .B _XOPEN_SOURCE |
55b726d1 | 335 | is defined, then expose definitions corresponding to the XPG4v2 |
18409fb8 | 336 | (SUSv1) UNIX extensions (UNIX 95). |
a7d7000f | 337 | Defining |
18409fb8 | 338 | .B _XOPEN_SOURCE |
a7d7000f MK |
339 | with a value of 500 or more also produces the same effect as defining |
340 | .BR _XOPEN_SOURCE_EXTENDED . | |
d1473a83 MK |
341 | Use of |
342 | .BR _XOPEN_SOURCE_EXTENDED | |
343 | in new source code should be avoided. | |
5711c04f | 344 | .IP |
1e92200f MK |
345 | Since defining |
346 | .B _XOPEN_SOURCE | |
347 | with a value of 500 or more has the same effect as defining | |
348 | .BR _XOPEN_SOURCE_EXTENDED , | |
349 | the latter (obsolete) feature test macro is generally not described in the | |
350 | SYNOPSIS in man pages. | |
55b726d1 | 351 | .TP |
df553d91 | 352 | .BR _ISOC99_SOURCE " (since glibc 2.1.3)" |
72807508 | 353 | Exposes declarations consistent with the ISO C99 standard. |
5711c04f | 354 | .IP |
df553d91 | 355 | Earlier glibc 2.1.x versions recognized an equivalent macro named |
a4de892a MK |
356 | .B _ISOC9X_SOURCE |
357 | (because the C99 standard had not then been finalized). | |
df553d91 | 358 | Although the use of this macro is obsolete, glibc continues |
5fab2e7c | 359 | to recognize it for backward compatibility. |
5711c04f | 360 | .IP |
cfba52fc MK |
361 | Defining |
362 | .B _ISOC99_SOURCE | |
363 | also exposes ISO C (1990) Amendment 1 ("C95") definitions. | |
364 | (The primary change in C95 was support for international character sets.) | |
5711c04f | 365 | .IP |
50d844a9 MK |
366 | Invoking the C compiler with the option |
367 | .IR \-std=c99 | |
368 | produces the same effects as defining this macro. | |
55b726d1 | 369 | .TP |
d6ced64f | 370 | .BR _ISOC11_SOURCE " (since glibc 2.16)" |
ea22a037 | 371 | Exposes declarations consistent with the ISO C11 standard. |
8effdb2d MK |
372 | Defining this macro also enables C99 and C95 features (like |
373 | .BR _ISOC99_SOURCE ). | |
5711c04f | 374 | .IP |
50d844a9 MK |
375 | Invoking the C compiler with the option |
376 | .IR \-std=c11 | |
377 | produces the same effects as defining this macro. | |
ea22a037 | 378 | .TP |
55b726d1 | 379 | .B _LARGEFILE64_SOURCE |
c13182ef MK |
380 | Expose definitions for the alternative API specified by the |
381 | LFS (Large File Summit) as a "transitional extension" to the | |
382 | Single UNIX Specification. | |
608bf950 SK |
383 | (See |
384 | .UR http:\:/\:/opengroup.org\:/platform\:/lfs.html | |
034a3f2f | 385 | .UE .) |
18409fb8 MK |
386 | The alternative API consists of a set of new objects |
387 | (i.e., functions and types) whose names are suffixed with "64" | |
388 | (e.g., | |
389 | .I off64_t | |
390 | versus | |
391 | .IR off_t , | |
392 | .BR lseek64 () | |
393 | versus | |
394 | .BR lseek (), | |
395 | etc.). | |
a007cc29 | 396 | New programs should not employ this macro; instead |
0daa9e92 | 397 | .I _FILE_OFFSET_BITS=64 |
18409fb8 | 398 | should be employed. |
55b726d1 | 399 | .TP |
d84dea22 MK |
400 | .BR _LARGEFILE_SOURCE |
401 | This macro was historically used to expose certain functions (specifically | |
402 | .BR fseeko (3) | |
403 | and | |
404 | .BR ftello (3)) | |
405 | that address limitations of earlier APIs | |
0c12fe8f | 406 | .RB ( fseek (3) |
d84dea22 MK |
407 | and |
408 | .BR ftell (3)) | |
409 | that use | |
410 | .IR "long int" | |
411 | for file offsets. | |
412 | This macro is implicitly defined if | |
413 | .BR _XOPEN_SOURCE | |
414 | is defined with a value greater than or equal to 500. | |
415 | New programs should not employ this macro; | |
416 | defining | |
417 | .BR _XOPEN_SOURCE | |
418 | as just described or defining | |
419 | .B _FILE_OFFSET_BITS | |
420 | with the value 64 is the preferred mechanism to achieve the same result. | |
421 | .TP | |
55b726d1 | 422 | .B _FILE_OFFSET_BITS |
c13182ef MK |
423 | Defining this macro with the value 64 |
424 | automatically converts references to 32-bit functions and data types | |
9ee4a2b6 | 425 | related to file I/O and filesystem operations into references to |
55b726d1 MK |
426 | their 64-bit counterparts. |
427 | This is useful for performing I/O on large files (> 2 Gigabytes) | |
428 | on 32-bit systems. | |
18409fb8 MK |
429 | (Defining this macro permits correctly written programs to use |
430 | large files with only a recompilation being required.) | |
5711c04f | 431 | .IP |
18409fb8 MK |
432 | 64-bit systems naturally permit file sizes greater than 2 Gigabytes, |
433 | and on those systems this macro has no effect. | |
55b726d1 | 434 | .TP |
d6472258 | 435 | .BR _BSD_SOURCE " (deprecated since glibc 2.20)" |
93d5a2a1 | 436 | Defining this macro with any value causes header files to expose |
55b726d1 | 437 | BSD-derived definitions. |
5711c04f | 438 | .IP |
0385c88e MK |
439 | In glibc versions up to and including 2.18, |
440 | defining this macro also causes BSD definitions to be preferred in | |
18409fb8 MK |
441 | some situations where standards conflict, unless one or more of |
442 | .BR _SVID_SOURCE , | |
443 | .BR _POSIX_SOURCE , | |
444 | .BR _POSIX_C_SOURCE , | |
445 | .BR _XOPEN_SOURCE , | |
446 | .BR _XOPEN_SOURCE_EXTENDED , | |
447 | or | |
0daa9e92 | 448 | .B _GNU_SOURCE |
18409fb8 | 449 | is defined, in which case BSD definitions are disfavored. |
0385c88e MK |
450 | Since glibc 2.19, |
451 | .B _BSD_SOURCE | |
452 | no longer causes BSD definitions to be preferred in case of conflicts. | |
5711c04f | 453 | .IP |
d6472258 MK |
454 | Since glibc 2.20, this macro is deprecated. |
455 | .\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 | |
456 | .\" commit 498afc54dfee41d33ba519f496e96480badace8e | |
457 | .\" commit acd7f096d79c181866d56d4aaf3b043e741f1e2c | |
458 | It now has the same effect as defining | |
459 | .BR _DEFAULT_SOURCE , | |
460 | but generates a compile-time warning (unless | |
461 | .BR _DEFAULT_SOURCE | |
462 | .\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78 | |
463 | is also defined). | |
464 | Use | |
465 | .B _DEFAULT_SOURCE | |
466 | instead. | |
da6aad02 MK |
467 | To allow code that requires |
468 | .BR _BSD_SOURCE | |
469 | in glibc 2.19 and earlier and | |
470 | .BR _DEFAULT_SOURCE | |
471 | in glibc 2.20 and later to compile without warnings, define | |
472 | .I both | |
473 | .B _BSD_SOURCE | |
474 | and | |
475 | .BR _DEFAULT_SOURCE . | |
55b726d1 | 476 | .TP |
d6472258 | 477 | .BR _SVID_SOURCE " (deprecated since glibc 2.20)" |
93d5a2a1 | 478 | Defining this macro with any value causes header files to expose |
c13182ef | 479 | System V-derived definitions. |
4dec66f9 MK |
480 | (SVID == System V Interface Definition; see |
481 | .BR standards (7).) | |
5711c04f | 482 | .IP |
d6472258 MK |
483 | Since glibc 2.20, this macro is deprecated in the same fashion as |
484 | .BR _BSD_SOURCE . | |
55b726d1 | 485 | .TP |
ba694dd0 | 486 | .BR _DEFAULT_SOURCE " (since glibc 2.19)" |
ba694dd0 MK |
487 | This macro can be defined to ensure that the "default" |
488 | definitions are provided even when the defaults would otherwise | |
489 | be disabled, | |
490 | as happens when individual macros are explicitly defined, | |
491 | or the compiler is invoked in one of its "standard" modes (e.g., | |
492 | .IR "cc\ \-std=c99" ). | |
dfb1232c MK |
493 | Defining |
494 | .B _DEFAULT_SOURCE | |
495 | without defining other individual macros | |
496 | or invoking the compiler in one of its "standard" modes has no effect. | |
5711c04f | 497 | .IP |
f04d68ba MK |
498 | The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, |
499 | as well as various definitions originally derived from BSD and System V. | |
dfb1232c MK |
500 | On glibc 2.19 and earlier, these defaults were approximately equivalent |
501 | to explicitly defining the following: | |
5711c04f | 502 | .IP |
dfb1232c | 503 | cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 |
ba694dd0 | 504 | .TP |
a4de892a | 505 | .BR _ATFILE_SOURCE " (since glibc 2.4)" |
93d5a2a1 | 506 | Defining this macro with any value causes header files to expose |
4769db24 MK |
507 | declarations of a range of functions with the suffix "at"; |
508 | see | |
509 | .BR openat (2). | |
8a8c6284 MK |
510 | Since glibc 2.10, this macro is also implicitly defined if |
511 | .BR _POSIX_C_SOURCE | |
512 | is defined with a value greater than or equal to 200809L. | |
4769db24 | 513 | .TP |
55b726d1 | 514 | .B _GNU_SOURCE |
08d69565 | 515 | Defining this macro (with any value) implicitly defines |
4769db24 | 516 | .BR _ATFILE_SOURCE , |
55b726d1 | 517 | .BR _LARGEFILE64_SOURCE , |
4769db24 MK |
518 | .BR _ISOC99_SOURCE , |
519 | .BR _XOPEN_SOURCE_EXTENDED , | |
520 | .BR _POSIX_SOURCE , | |
0daa9e92 | 521 | .B _POSIX_C_SOURCE |
6e047f16 MK |
522 | with the value 200809L |
523 | (200112L in glibc versions before 2.10; | |
524 | 199506L in glibc versions before 2.5; | |
525 | 199309L in glibc versions before 2.1) | |
922cf8f6 | 526 | and |
0daa9e92 | 527 | .B _XOPEN_SOURCE |
6e047f16 MK |
528 | with the value 700 |
529 | (600 in glibc versions before 2.10; | |
530 | 500 in glibc versions before 2.2). | |
55b726d1 | 531 | In addition, various GNU-specific extensions are also exposed. |
5711c04f | 532 | .IP |
dfb1232c MK |
533 | Since glibc 2.19, defining |
534 | .BR _GNU_SOURCE | |
08d69565 | 535 | also has the effect of implicitly defining |
dfb1232c MK |
536 | .BR _DEFAULT_SOURCE . |
537 | In glibc versions before 2.20, defining | |
538 | .BR _GNU_SOURCE | |
08d69565 | 539 | also had the effect of implicitly defining |
dfb1232c MK |
540 | .BR _BSD_SOURCE |
541 | and | |
542 | .BR _SVID_SOURCE . | |
d3bbf18d MK |
543 | .TP |
544 | .B _REENTRANT | |
03fb4543 MK |
545 | Historically, on various C libraries |
546 | it was necessary to define this macro in all | |
f74991be | 547 | multithreaded code. |
03fb4543 MK |
548 | .\" Zack Weinberg |
549 | .\" There did once exist C libraries where it was necessary. The ones | |
550 | .\" I remember were proprietary Unix vendor libcs from the mid-1990s | |
551 | .\" You would get completely unlocked stdio without _REENTRANT. | |
f74991be MK |
552 | (Some C libraries may still require this.) |
553 | In glibc, | |
554 | this macro also exposed definitions of certain reentrant functions. | |
5711c04f | 555 | .IP |
f74991be MK |
556 | However, glibc has been thread-safe by default for many years; |
557 | since glibc 2.3, the only effect of defining | |
558 | .BR _REENTRANT | |
559 | has been to enable one or two of the same declarations that | |
560 | are also enabled by defining | |
75b554e7 MK |
561 | .BR _POSIX_C_SOURCE |
562 | with a value of 199606L or greater. | |
5711c04f | 563 | .IP |
f74991be | 564 | .B _REENTRANT |
03fb4543 MK |
565 | is now obsolete. |
566 | In glibc 2.25 and later, defining | |
567 | .B _REENTRANT | |
568 | is equivalent to defining | |
f74991be MK |
569 | .B _POSIX_C_SOURCE |
570 | with the value 199606L. | |
571 | If a higher POSIX conformance level is | |
572 | selected by any other means (such as | |
573 | .B _POSIX_C_SOURCE | |
574 | itself, | |
575 | .BR _XOPEN_SOURCE , | |
576 | .BR _DEFAULT_SOURCE , | |
577 | or | |
578 | .BR _GNU_SOURCE ), | |
03fb4543 | 579 | then defining |
f74991be MK |
580 | .B _REENTRANT |
581 | has no effect. | |
5711c04f | 582 | .IP |
03fb4543 | 583 | This macro is automatically defined if one compiles with |
26719dcf | 584 | .IR "cc\ \-pthread" . |
d3bbf18d MK |
585 | .TP |
586 | .B _THREAD_SAFE | |
75b554e7 | 587 | Synonym for the (deprecated) |
d3bbf18d MK |
588 | .BR _REENTRANT , |
589 | provided for compatibility with some other implementations. | |
590 | .TP | |
a4de892a | 591 | .BR _FORTIFY_SOURCE " (since glibc 2.3.4)" |
d3bbf18d MK |
592 | .\" For more detail, see: |
593 | .\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html | |
594 | .\" [PATCH] Object size checking to prevent (some) buffer overflows | |
595 | .\" * From: Jakub Jelinek <jakub at redhat dot com> | |
596 | .\" * To: gcc-patches at gcc dot gnu dot org | |
597 | .\" * Date: Tue, 21 Sep 2004 04:16:40 -0400 | |
598 | Defining this macro causes some lightweight checks to be performed | |
599 | to detect some buffer overflow errors when employing | |
29ca3cb0 | 600 | various string and memory manipulation functions (for example, |
d3bbf18d | 601 | .BR memcpy (3), |
d3bbf18d MK |
602 | .BR memset (3), |
603 | .BR stpcpy (3), | |
604 | .BR strcpy (3), | |
605 | .BR strncpy (3), | |
606 | .BR strcat (3), | |
607 | .BR strncat (3), | |
608 | .BR sprintf (3), | |
609 | .BR snprintf (3), | |
610 | .BR vsprintf (3), | |
611 | .BR vsnprintf (3), | |
29ca3cb0 MK |
612 | .BR gets (3), |
613 | and wide character variants thereof). | |
614 | For some functions, argument consistency is checked; | |
615 | for example, a check is made that | |
616 | .BR open (2) | |
617 | has been supplied with a | |
618 | .I mode | |
619 | argument when the specified flags include | |
620 | .BR O_CREAT . | |
621 | Not all problems are detected, just some common cases. | |
622 | .\" Look for __USE_FORTIFY_LEVEL in the header files | |
5711c04f | 623 | .IP |
c13182ef MK |
624 | If |
625 | .B _FORTIFY_SOURCE | |
626 | is set to 1, with compiler optimization level 1 | |
5b8dbfd4 | 627 | .RI ( "gcc\ \-O1" ) |
d9bfdb9c | 628 | and above, checks that shouldn't change the behavior of |
d3bbf18d | 629 | conforming programs are performed. |
c13182ef MK |
630 | With |
631 | .B _FORTIFY_SOURCE | |
29ca3cb0 | 632 | set to 2, some more checking is added, but |
d3bbf18d | 633 | some conforming programs might fail. |
ef797056 MK |
634 | .\" For example, given the following code |
635 | .\" int d; | |
636 | .\" char buf[1000], buf[1000]; | |
637 | .\" strcpy(fmt, "Hello world\n%n"); | |
638 | .\" snprintf(buf, sizeof(buf), fmt, &d); | |
639 | .\" | |
640 | .\" Compiling with "gcc -D_FORTIFY_SOURCE=2 -O1" and then running will | |
29c0586f | 641 | .\" cause the following diagnostic at run time at the snprintf() call |
ef797056 MK |
642 | .\" |
643 | .\" *** %n in writable segment detected *** | |
644 | .\" Aborted (core dumped) | |
645 | .\" | |
5711c04f | 646 | .IP |
29ca3cb0 MK |
647 | Some of the checks can be performed at compile time |
648 | (via macros logic implemented in header files), | |
c13182ef MK |
649 | and result in compiler warnings; |
650 | other checks take place at run time, | |
d3bbf18d | 651 | and result in a run-time error if the check fails. |
5711c04f | 652 | .IP |
d3bbf18d MK |
653 | Use of this macro requires compiler support, available with |
654 | .BR gcc (1) | |
655 | since version 4.0. | |
4769db24 | 656 | .SS Default definitions, implicit definitions, and combining definitions |
9eaee631 | 657 | .PP |
93d5a2a1 MK |
658 | If no feature test macros are explicitly defined, |
659 | then the following feature test macros are defined by default: | |
e9f22b0a | 660 | .BR _BSD_SOURCE |
d6472258 | 661 | (in glibc 2.19 and earlier), |
e9f22b0a | 662 | .BR _SVID_SOURCE |
d6472258 | 663 | (in glibc 2.19 and earlier), |
dfb1232c MK |
664 | .BR _DEFAULT_SOURCE |
665 | (since glibc 2.19), | |
9eaee631 MK |
666 | .BR _POSIX_SOURCE , |
667 | and | |