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