| 1 |
.\" Copyright 2006, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH feature_test_macros 7 2026-02-10 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
feature_test_macros \- feature test macros |
| 9 |
.SH DESCRIPTION |
| 10 |
Feature test macros allow the programmer to control the definitions that |
| 11 |
are exposed by system header files when a program is compiled. |
| 12 |
.P |
| 13 |
.B NOTE: |
| 14 |
In order to be effective, a feature test macro |
| 15 |
.IR "must be defined before including any header files" . |
| 16 |
This can be done either in the compilation command |
| 17 |
.RI ( "cc \-DMACRO=value" ) |
| 18 |
or by defining the macro within the source code before |
| 19 |
including any headers. |
| 20 |
The requirement that the macro must be defined before including any |
| 21 |
header file exists because header files may freely include one another. |
| 22 |
Thus, for example, in the following lines, defining the |
| 23 |
.B _GNU_SOURCE |
| 24 |
macro may have no effect because the header |
| 25 |
.I <abc.h> |
| 26 |
itself includes |
| 27 |
.I <xyz.h> |
| 28 |
(POSIX explicitly allows this): |
| 29 |
.P |
| 30 |
.in +4n |
| 31 |
.EX |
| 32 |
#include <abc.h> |
| 33 |
#define _GNU_SOURCE |
| 34 |
#include <xyz.h> |
| 35 |
.EE |
| 36 |
.in |
| 37 |
.P |
| 38 |
Some feature test macros are useful for creating portable applications, |
| 39 |
by preventing nonstandard definitions from being exposed. |
| 40 |
Other macros can be used to expose nonstandard definitions that |
| 41 |
are not exposed by default. |
| 42 |
.P |
| 43 |
The precise effects of each of the feature test macros described below |
| 44 |
can be ascertained by inspecting the |
| 45 |
.I <features.h> |
| 46 |
header file. |
| 47 |
.BR Note : |
| 48 |
applications do |
| 49 |
.I not |
| 50 |
need to directly include |
| 51 |
.IR <features.h> ; |
| 52 |
indeed, doing so is actively discouraged. |
| 53 |
See NOTES. |
| 54 |
.SS Specification of feature test macro requirements in manual pages |
| 55 |
When a function requires that a feature test macro is defined, |
| 56 |
the manual page SYNOPSIS typically includes a note of the following form |
| 57 |
(this example from the |
| 58 |
.BR acct (2) |
| 59 |
manual page): |
| 60 |
.P |
| 61 |
.RS |
| 62 |
.B #include <unistd.h> |
| 63 |
.P |
| 64 |
.BI "int acct(const char *" filename ); |
| 65 |
.P |
| 66 |
.RS -4 |
| 67 |
.EX |
| 68 |
Feature Test Macro Requirements for glibc (see |
| 69 |
.BR feature_test_macros (7)): |
| 70 |
.EE |
| 71 |
.RE |
| 72 |
.P |
| 73 |
.BR acct (): |
| 74 |
_BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE < 500) |
| 75 |
.RE |
| 76 |
.P |
| 77 |
The |
| 78 |
.B || |
| 79 |
means that in order to obtain the declaration of |
| 80 |
.BR acct (2) |
| 81 |
from |
| 82 |
.IR <unistd.h> , |
| 83 |
.I either |
| 84 |
of the following macro |
| 85 |
definitions must be made before including any header files: |
| 86 |
.P |
| 87 |
.in +4n |
| 88 |
.EX |
| 89 |
#define _BSD_SOURCE |
| 90 |
#define _XOPEN_SOURCE /* or any value < 500 */ |
| 91 |
.EE |
| 92 |
.in |
| 93 |
.P |
| 94 |
Alternatively, equivalent definitions can be included in the |
| 95 |
compilation command: |
| 96 |
.P |
| 97 |
.in +4n |
| 98 |
.EX |
| 99 |
cc \-D_BSD_SOURCE |
| 100 |
cc \-D_XOPEN_SOURCE # Or any value < 500 |
| 101 |
.EE |
| 102 |
.in |
| 103 |
.P |
| 104 |
Note that, as described below, |
| 105 |
.BR "some feature test macros are defined by default" , |
| 106 |
so that it may not always be necessary to |
| 107 |
explicitly specify the feature test macro(s) shown in the |
| 108 |
SYNOPSIS. |
| 109 |
.P |
| 110 |
In a few cases, manual pages use a shorthand for expressing the |
| 111 |
feature test macro requirements (this example from |
| 112 |
.BR readahead (2)): |
| 113 |
.P |
| 114 |
.RS +4 |
| 115 |
.EX |
| 116 |
.B #define _GNU_SOURCE |
| 117 |
.B #define _FILE_OFFSET_BITS 64 |
| 118 |
.B #include <fcntl.h> |
| 119 |
.P |
| 120 |
.BI "ssize_t readahead(int " fd ", off_t *" offset ", size_t " count ); |
| 121 |
.EE |
| 122 |
.RE |
| 123 |
.P |
| 124 |
This format is employed when the feature test macros ensure |
| 125 |
that the proper function declarations are visible, |
| 126 |
and the macros are not defined by default. |
| 127 |
.SS Feature test macros understood by glibc |
| 128 |
The paragraphs below explain how feature test macros are handled |
| 129 |
in glibc |
| 130 |
.RI 2. x , |
| 131 |
.I x |
| 132 |
> 0. |
| 133 |
.P |
| 134 |
First, though, a summary of a few details for the impatient: |
| 135 |
.IP \[bu] 3 |
| 136 |
The macros that you most likely need to use in modern source code are |
| 137 |
.B _POSIX_C_SOURCE |
| 138 |
(for definitions from various versions of POSIX.1), |
| 139 |
.B _XOPEN_SOURCE |
| 140 |
(for definitions from various versions of SUS), |
| 141 |
.B _GNU_SOURCE |
| 142 |
(for GNU and/or Linux specific stuff), and |
| 143 |
.B _DEFAULT_SOURCE |
| 144 |
(to get definitions that would normally be provided by default). |
| 145 |
.IP \[bu] |
| 146 |
Certain macros are defined with default values. |
| 147 |
Thus, although one or more macros may be indicated as being |
| 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 \[bu] |
| 152 |
Defining |
| 153 |
.B _XOPEN_SOURCE |
| 154 |
with a value of 600 or greater produces the same effects as defining |
| 155 |
.B _POSIX_C_SOURCE |
| 156 |
with a value of 200112L or greater. |
| 157 |
Where one sees |
| 158 |
.IP |
| 159 |
.in +4n |
| 160 |
.EX |
| 161 |
_POSIX_C_SOURCE >= 200112L |
| 162 |
.EE |
| 163 |
.in |
| 164 |
.IP |
| 165 |
in the feature test macro requirements in the SYNOPSIS of a man page, |
| 166 |
it is implicit that the following has the same effect: |
| 167 |
.IP |
| 168 |
.in +4n |
| 169 |
.EX |
| 170 |
_XOPEN_SOURCE >= 600 |
| 171 |
.EE |
| 172 |
.in |
| 173 |
.IP \[bu] |
| 174 |
Defining |
| 175 |
.B _XOPEN_SOURCE |
| 176 |
with a value of 700 or greater produces the same effects as defining |
| 177 |
.B _POSIX_C_SOURCE |
| 178 |
with a value of 200809L or greater. |
| 179 |
Where one sees |
| 180 |
.IP |
| 181 |
.in +4n |
| 182 |
.EX |
| 183 |
_POSIX_C_SOURCE >= 200809L |
| 184 |
.EE |
| 185 |
.in |
| 186 |
.IP |
| 187 |
in the feature test macro requirements in the SYNOPSIS of a man page, |
| 188 |
it is implicit that the following has the same effect: |
| 189 |
.IP |
| 190 |
.in +4n |
| 191 |
.EX |
| 192 |
_XOPEN_SOURCE >= 700 |
| 193 |
.EE |
| 194 |
.in |
| 195 |
.\" The details in glibc 2.0 are simpler, but combining a |
| 196 |
.\" a description of them with the details in later glibc versions |
| 197 |
.\" would make for a complicated description. |
| 198 |
.P |
| 199 |
glibc understands the following feature test macros: |
| 200 |
.TP |
| 201 |
.B __STRICT_ANSI__ |
| 202 |
ISO Standard C. |
| 203 |
This macro is implicitly defined by |
| 204 |
.BR gcc (1) |
| 205 |
when invoked with, for example, the |
| 206 |
.I \-std=c99 |
| 207 |
or |
| 208 |
.I \-ansi |
| 209 |
flag. |
| 210 |
.TP |
| 211 |
.B _POSIX_C_SOURCE |
| 212 |
Defining this macro causes header files to expose definitions as follows: |
| 213 |
.RS |
| 214 |
.IP \[bu] 3 |
| 215 |
The value 1 exposes definitions conforming to POSIX.1-1990 and |
| 216 |
ISO C (1990). |
| 217 |
.IP \[bu] |
| 218 |
The value 2 or greater additionally exposes |
| 219 |
definitions for POSIX.2-1992. |
| 220 |
.IP \[bu] |
| 221 |
The value 199309L or greater additionally exposes |
| 222 |
definitions for POSIX.1b (real-time extensions). |
| 223 |
.\" 199506L functionality is available only since glibc 2.1 |
| 224 |
.IP \[bu] |
| 225 |
The value 199506L or greater additionally exposes |
| 226 |
definitions for POSIX.1c (threads). |
| 227 |
.IP \[bu] |
| 228 |
(Since glibc 2.3.3) |
| 229 |
The value 200112L or greater additionally exposes definitions corresponding |
| 230 |
to the POSIX.1-2001 base specification (excluding the XSI extension). |
| 231 |
This value also causes C95 (since glibc 2.12) and |
| 232 |
C99 (since glibc 2.10) features to be exposed |
| 233 |
(in other words, the equivalent of defining |
| 234 |
.BR _ISOC99_SOURCE ). |
| 235 |
.IP \[bu] |
| 236 |
(Since glibc 2.10) |
| 237 |
The value 200809L or greater additionally exposes definitions corresponding |
| 238 |
to the POSIX.1-2008 base specification (excluding the XSI extension). |
| 239 |
.RE |
| 240 |
.TP |
| 241 |
.B _POSIX_SOURCE |
| 242 |
Defining this obsolete macro with any value is equivalent to defining |
| 243 |
.B _POSIX_C_SOURCE |
| 244 |
with the value 1. |
| 245 |
.IP |
| 246 |
Since this macro is obsolete, |
| 247 |
its usage is generally not documented when discussing |
| 248 |
feature test macro requirements in the man pages. |
| 249 |
.TP |
| 250 |
.B _XOPEN_SOURCE |
| 251 |
Defining this macro causes header files to expose definitions as follows: |
| 252 |
.RS |
| 253 |
.IP \[bu] 3 |
| 254 |
Defining with any value exposes |
| 255 |
definitions conforming to POSIX.1, POSIX.2, and XPG4. |
| 256 |
.IP \[bu] |
| 257 |
The value 500 or greater additionally exposes |
| 258 |
definitions for SUSv2 (UNIX 98). |
| 259 |
.IP \[bu] |
| 260 |
(Since glibc 2.2) The value 600 or greater additionally exposes |
| 261 |
definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification |
| 262 |
plus the XSI extension) and C99 definitions. |
| 263 |
.IP \[bu] |
| 264 |
(Since glibc 2.10) The value 700 or greater additionally exposes |
| 265 |
definitions for SUSv4 (i.e., the POSIX.1-2008 base specification |
| 266 |
plus the XSI extension). |
| 267 |
.RE |
| 268 |
.IP |
| 269 |
If |
| 270 |
.B __STRICT_ANSI__ |
| 271 |
is not defined, or |
| 272 |
.B _XOPEN_SOURCE |
| 273 |
is defined with a value greater than or equal to 500 |
| 274 |
.I and |
| 275 |
neither |
| 276 |
.B _POSIX_SOURCE |
| 277 |
nor |
| 278 |
.B _POSIX_C_SOURCE |
| 279 |
is explicitly defined, then |
| 280 |
the following macros are implicitly defined: |
| 281 |
.RS |
| 282 |
.IP \[bu] 3 |
| 283 |
.B _POSIX_SOURCE |
| 284 |
is defined with the value 1. |
| 285 |
.IP \[bu] |
| 286 |
.B _POSIX_C_SOURCE |
| 287 |
is defined, according to the value of |
| 288 |
.BR _XOPEN_SOURCE : |
| 289 |
.RS |
| 290 |
.TP |
| 291 |
.BR _XOPEN_SOURCE " < 500" |
| 292 |
.B _POSIX_C_SOURCE |
| 293 |
is defined with the value 2. |
| 294 |
.TP |
| 295 |
.RB "500 <= " _XOPEN_SOURCE " < 600" |
| 296 |
.B _POSIX_C_SOURCE |
| 297 |
is defined with the value 199506L. |
| 298 |
.TP |
| 299 |
.RB "600 <= " _XOPEN_SOURCE " < 700" |
| 300 |
.B _POSIX_C_SOURCE |
| 301 |
is defined with the value 200112L. |
| 302 |
.TP |
| 303 |
.RB "700 <= " _XOPEN_SOURCE " (since glibc 2.10)" |
| 304 |
.B _POSIX_C_SOURCE |
| 305 |
is defined with the value 200809L. |
| 306 |
.RE |
| 307 |
.RE |
| 308 |
.IP |
| 309 |
In addition, defining |
| 310 |
.B _XOPEN_SOURCE |
| 311 |
with a value of 500 or greater produces the same effects as defining |
| 312 |
.BR _XOPEN_SOURCE_EXTENDED . |
| 313 |
.TP |
| 314 |
.B _XOPEN_SOURCE_EXTENDED |
| 315 |
If this macro is defined, |
| 316 |
.I and |
| 317 |
.B _XOPEN_SOURCE |
| 318 |
is defined, then expose definitions corresponding to the XPG4v2 |
| 319 |
(SUSv1) UNIX extensions (UNIX 95). |
| 320 |
Defining |
| 321 |
.B _XOPEN_SOURCE |
| 322 |
with a value of 500 or more also produces the same effect as defining |
| 323 |
.BR _XOPEN_SOURCE_EXTENDED . |
| 324 |
Use of |
| 325 |
.B _XOPEN_SOURCE_EXTENDED |
| 326 |
in new source code should be avoided. |
| 327 |
.IP |
| 328 |
Since defining |
| 329 |
.B _XOPEN_SOURCE |
| 330 |
with a value of 500 or more has the same effect as defining |
| 331 |
.BR _XOPEN_SOURCE_EXTENDED , |
| 332 |
the latter (obsolete) feature test macro is generally not described in the |
| 333 |
SYNOPSIS in man pages. |
| 334 |
.TP |
| 335 |
.BR _ISOC99_SOURCE " (since glibc 2.1.3)" |
| 336 |
Exposes declarations consistent with the ISO C99 standard. |
| 337 |
Defining this macro also exposes ISO C (1990) Amendment 1 ("C95") definitions. |
| 338 |
(The primary change in C95 was support for international character sets.) |
| 339 |
.IP |
| 340 |
Invoking the C compiler with the option |
| 341 |
.I \-std=c99 |
| 342 |
produces the same effects as defining this macro. |
| 343 |
.TP |
| 344 |
.BR _ISOC11_SOURCE " (since glibc 2.16)" |
| 345 |
Exposes declarations consistent with the ISO C11 standard. |
| 346 |
Defining this macro also enables C99 and C95 features (like |
| 347 |
.BR _ISOC99_SOURCE ). |
| 348 |
.IP |
| 349 |
Invoking the C compiler with the option |
| 350 |
.I \-std=c11 |
| 351 |
produces the same effects as defining this macro. |
| 352 |
.TP |
| 353 |
.BR _ISOC23_SOURCE " (since glibc 2.40)" |
| 354 |
Exposes declarations consistent with the ISO C23 standard. |
| 355 |
.IP |
| 356 |
Since glibc 2.31, |
| 357 |
an equivalent macro named |
| 358 |
.B _ISOC2X_SOURCE |
| 359 |
was recognized |
| 360 |
(because the C23 standard had not then been finalized). |
| 361 |
Although the use of this macro is obsolete, |
| 362 |
glibc continues to recognize it for backward compatibility. |
| 363 |
.IP |
| 364 |
Defining |
| 365 |
.B _ISOC23_SOURCE |
| 366 |
also enables C11, C99, and C95 features. |
| 367 |
.IP |
| 368 |
Invoking the C compiler with the option |
| 369 |
.I \-std=c23 |
| 370 |
produces the same effects as defining this macro. |
| 371 |
.TP |
| 372 |
.B _LARGEFILE64_SOURCE |
| 373 |
Expose definitions for the alternative API specified by the |
| 374 |
LFS (Large File Summit) as a "transitional extension" to the |
| 375 |
Single UNIX Specification. |
| 376 |
(See |
| 377 |
.UR http:\:/\:/opengroup.org\:/platform\:/lfs.html |
| 378 |
.UE .) |
| 379 |
The alternative API consists of a set of new objects |
| 380 |
(i.e., functions and types) whose names are suffixed with "64" |
| 381 |
(e.g., |
| 382 |
.I off64_t |
| 383 |
versus |
| 384 |
.IR off_t , |
| 385 |
.BR lseek64 () |
| 386 |
versus |
| 387 |
.BR lseek (), |
| 388 |
etc.). |
| 389 |
New programs should not employ this macro; |
| 390 |
instead |
| 391 |
.I _FILE_OFFSET_BITS=64 |
| 392 |
should be employed. |
| 393 |
.TP |
| 394 |
.B _LARGEFILE_SOURCE |
| 395 |
This macro was historically used to expose certain functions (specifically |
| 396 |
.BR fseeko (3) |
| 397 |
and |
| 398 |
.BR ftello (3)) |
| 399 |
that address limitations of earlier APIs |
| 400 |
.RB ( fseek (3) |
| 401 |
and |
| 402 |
.BR ftell (3)) |
| 403 |
that use |
| 404 |
.I long |
| 405 |
for file offsets. |
| 406 |
This macro is implicitly defined if |
| 407 |
.B _XOPEN_SOURCE |
| 408 |
is defined with a value greater than or equal to 500. |
| 409 |
New programs should not employ this macro; |
| 410 |
defining |
| 411 |
.B _XOPEN_SOURCE |
| 412 |
as just described or defining |
| 413 |
.B _FILE_OFFSET_BITS |
| 414 |
with the value 64 is the preferred mechanism to achieve the same result. |
| 415 |
.TP |
| 416 |
.B _FILE_OFFSET_BITS |
| 417 |
Defining this macro with the value 64 |
| 418 |
automatically converts references to 32-bit functions and data types |
| 419 |
related to file I/O and filesystem operations into references to |
| 420 |
their 64-bit counterparts. |
| 421 |
This is useful for performing I/O on large files (> 2 Gigabytes) |
| 422 |
on 32-bit systems. |
| 423 |
It is also useful when calling functions like |
| 424 |
.BR copy_file_range (2) |
| 425 |
that were added more recently and that come only in 64-bit flavors. |
| 426 |
(Defining this macro permits correctly written programs to use |
| 427 |
large files with only a recompilation being required.) |
| 428 |
.IP |
| 429 |
64-bit systems naturally permit file sizes greater than 2 Gigabytes, |
| 430 |
and on those systems this macro has no effect. |
| 431 |
.TP |
| 432 |
.B _TIME_BITS |
| 433 |
Defining this macro with the value 64 |
| 434 |
changes the width of |
| 435 |
.BR time_t (3type) |
| 436 |
to 64-bit which allows handling of timestamps beyond |
| 437 |
2038. |
| 438 |
It is closely related to |
| 439 |
.B _FILE_OFFSET_BITS |
| 440 |
and depending on implementation, may require it set. |
| 441 |
This macro is available as of glibc 2.34. |
| 442 |
.TP |
| 443 |
.BR _BSD_SOURCE " (deprecated since glibc 2.20)" |
| 444 |
Defining this macro with any value causes header files to expose |
| 445 |
BSD-derived definitions. |
| 446 |
.IP |
| 447 |
In glibc versions up to and including 2.18, |
| 448 |
defining this macro also causes BSD definitions to be preferred in |
| 449 |
some situations where standards conflict, unless one or more of |
| 450 |
.BR _SVID_SOURCE , |
| 451 |
.BR _POSIX_SOURCE , |
| 452 |
.BR _POSIX_C_SOURCE , |
| 453 |
.BR _XOPEN_SOURCE , |
| 454 |
.BR _XOPEN_SOURCE_EXTENDED , |
| 455 |
or |
| 456 |
.B _GNU_SOURCE |
| 457 |
is defined, in which case BSD definitions are disfavored. |
| 458 |
Since glibc 2.19, |
| 459 |
.B _BSD_SOURCE |
| 460 |
no longer causes BSD definitions to be preferred in case of conflicts. |
| 461 |
.IP |
| 462 |
Since glibc 2.20, this macro is deprecated. |
| 463 |
.\" commit c941736c92fa3a319221f65f6755659b2a5e0a20 |
| 464 |
.\" commit 498afc54dfee41d33ba519f496e96480badace8e |
| 465 |
.\" commit acd7f096d79c181866d56d4aaf3b043e741f1e2c |
| 466 |
It now has the same effect as defining |
| 467 |
.BR _DEFAULT_SOURCE , |
| 468 |
but generates a compile-time warning (unless |
| 469 |
.B _DEFAULT_SOURCE |
| 470 |
.\" commit ade40b10ff5fa59a318cf55b9d8414b758e8df78 |
| 471 |
is also defined). |
| 472 |
Use |
| 473 |
.B _DEFAULT_SOURCE |
| 474 |
instead. |
| 475 |
To allow code that requires |
| 476 |
.B _BSD_SOURCE |
| 477 |
in glibc 2.19 and earlier and |
| 478 |
.B _DEFAULT_SOURCE |
| 479 |
in glibc 2.20 and later to compile without warnings, define |
| 480 |
.I both |
| 481 |
.B _BSD_SOURCE |
| 482 |
and |
| 483 |
.BR _DEFAULT_SOURCE . |
| 484 |
.TP |
| 485 |
.BR _SVID_SOURCE " (deprecated since glibc 2.20)" |
| 486 |
Defining this macro with any value causes header files to expose |
| 487 |
System V-derived definitions. |
| 488 |
(SVID == System V Interface Definition; |
| 489 |
see |
| 490 |
.BR standards (7).) |
| 491 |
.IP |
| 492 |
Since glibc 2.20, this macro is deprecated in the same fashion as |
| 493 |
.BR _BSD_SOURCE . |
| 494 |
.TP |
| 495 |
.BR _DEFAULT_SOURCE " (since glibc 2.19)" |
| 496 |
This macro can be defined to ensure that the "default" |
| 497 |
definitions are provided even when the defaults would otherwise |
| 498 |
be disabled, |
| 499 |
as happens when individual macros are explicitly defined, |
| 500 |
or the compiler is invoked in one of its "standard" modes (e.g., |
| 501 |
.IR cc\~\-std=c99 ). |
| 502 |
Defining |
| 503 |
.B _DEFAULT_SOURCE |
| 504 |
without defining other individual macros |
| 505 |
or invoking the compiler in one of its "standard" modes has no effect. |
| 506 |
.IP |
| 507 |
The "default" definitions comprise those required by POSIX.1-2008 and ISO C99, |
| 508 |
as well as various definitions originally derived from BSD and System V. |
| 509 |
On glibc 2.19 and earlier, these defaults were approximately equivalent |
| 510 |
to explicitly defining the following: |
| 511 |
.IP |
| 512 |
.in +4n |
| 513 |
.EX |
| 514 |
cc \-D_BSD_SOURCE \-D_SVID_SOURCE \-D_POSIX_C_SOURCE=200809 |
| 515 |
.EE |
| 516 |
.in |
| 517 |
.TP |
| 518 |
.BR _ATFILE_SOURCE " (since glibc 2.4)" |
| 519 |
Defining this macro with any value causes header files to expose |
| 520 |
declarations of a range of functions with the suffix "at"; |
| 521 |
see |
| 522 |
.BR openat (2). |
| 523 |
Since glibc 2.10, this macro is also implicitly defined if |
| 524 |
.B _POSIX_C_SOURCE |
| 525 |
is defined with a value greater than or equal to 200809L. |
| 526 |
.TP |
| 527 |
.B _GNU_SOURCE |
| 528 |
Defining this macro (with any value) implicitly defines |
| 529 |
.BR _ATFILE_SOURCE , |
| 530 |
.BR _LARGEFILE64_SOURCE , |
| 531 |
.BR _ISOC99_SOURCE , |
| 532 |
.BR _XOPEN_SOURCE_EXTENDED , |
| 533 |
.BR _POSIX_SOURCE , |
| 534 |
.B _POSIX_C_SOURCE |
| 535 |
with the value 200809L |
| 536 |
(200112L before glibc 2.10; |
| 537 |
199506L before glibc 2.5; |
| 538 |
199309L before glibc 2.1) |
| 539 |
and |
| 540 |
.B _XOPEN_SOURCE |
| 541 |
with the value 700 |
| 542 |
(600 before glibc 2.10; |
| 543 |
500 before glibc 2.2). |
| 544 |
In addition, various GNU-specific extensions are also exposed. |
| 545 |
.IP |
| 546 |
Since glibc 2.19, defining |
| 547 |
.B _GNU_SOURCE |
| 548 |
also has the effect of implicitly defining |
| 549 |
.BR _DEFAULT_SOURCE . |
| 550 |
Before glibc 2.20, defining |
| 551 |
.B _GNU_SOURCE |
| 552 |
also had the effect of implicitly defining |
| 553 |
.B _BSD_SOURCE |
| 554 |
and |
| 555 |
.BR _SVID_SOURCE . |
| 556 |
.TP |
| 557 |
.B _REENTRANT |
| 558 |
Historically, on various C libraries |
| 559 |
it was necessary to define this macro in all |
| 560 |
multithreaded code. |
| 561 |
.\" Zack Weinberg |
| 562 |
.\" There did once exist C libraries where it was necessary. The ones |
| 563 |
.\" I remember were proprietary Unix vendor libcs from the mid-1990s |
| 564 |
.\" You would get completely unlocked stdio without _REENTRANT. |
| 565 |
(Some C libraries may still require this.) |
| 566 |
In glibc, |
| 567 |
this macro also exposed definitions of certain reentrant functions. |
| 568 |
.IP |
| 569 |
However, glibc has been thread-safe by default for many years; |
| 570 |
since glibc 2.3, the only effect of defining |
| 571 |
.B _REENTRANT |
| 572 |
has been to enable one or two of the same declarations that |
| 573 |
are also enabled by defining |
| 574 |
.B _POSIX_C_SOURCE |
| 575 |
with a value of 199606L or greater. |
| 576 |
.IP |
| 577 |
.B _REENTRANT |
| 578 |
is now obsolete. |
| 579 |
In glibc 2.25 and later, defining |
| 580 |
.B _REENTRANT |
| 581 |
is equivalent to defining |
| 582 |
.B _POSIX_C_SOURCE |
| 583 |
with the value 199606L. |
| 584 |
If a higher POSIX conformance level is |
| 585 |
selected by any other means (such as |
| 586 |
.B _POSIX_C_SOURCE |
| 587 |
itself, |
| 588 |
.BR _XOPEN_SOURCE , |
| 589 |
.BR _DEFAULT_SOURCE , |
| 590 |
or |
| 591 |
.BR _GNU_SOURCE ), |
| 592 |
then defining |
| 593 |
.B _REENTRANT |
| 594 |
has no effect. |
| 595 |
.IP |
| 596 |
This macro is automatically defined if one compiles with |
| 597 |
.IR cc\~\-pthread . |
| 598 |
.TP |
| 599 |
.B _THREAD_SAFE |
| 600 |
Synonym for the (deprecated) |
| 601 |
.BR _REENTRANT , |
| 602 |
provided for compatibility with some other implementations. |
| 603 |
.TP |
| 604 |
.BR _FORTIFY_SOURCE " (since glibc 2.3.4)" |
| 605 |
.\" For more detail, see: |
| 606 |
.\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html |
| 607 |
.\" [PATCH] Object size checking to prevent (some) buffer overflows |
| 608 |
.\" * From: Jakub Jelinek <jakub at redhat dot com> |
| 609 |
.\" * To: gcc-patches at gcc dot gnu dot org |
| 610 |
.\" * Date: Tue, 21 Sep 2004 04:16:40 -0400 |
| 611 |
Defining this macro causes some lightweight checks to be performed |
| 612 |
to detect some buffer overflow errors when employing |
| 613 |
various string and memory manipulation functions (for example, |
| 614 |
.BR memcpy (3), |
| 615 |
.BR memset (3), |
| 616 |
.BR stpcpy (3), |
| 617 |
.BR strcpy (3), |
| 618 |
.BR strncpy (3), |
| 619 |
.BR strcat (3), |
| 620 |
.BR strncat (3), |
| 621 |
.BR sprintf (3), |
| 622 |
.BR snprintf (3), |
| 623 |
.BR vsprintf (3), |
| 624 |
.BR vsnprintf (3), |
| 625 |
.BR gets (3), |
| 626 |
and wide character variants thereof). |
| 627 |
For some functions, argument consistency is checked; |
| 628 |
for example, a check is made that |
| 629 |
.BR open (2) |
| 630 |
has been supplied with a |
| 631 |
.I mode |
| 632 |
argument when the specified flags include |
| 633 |
.BR O_CREAT . |
| 634 |
Not all problems are detected, just some common cases. |
| 635 |
.\" Look for __USE_FORTIFY_LEVEL in the header files |
| 636 |
.IP |
| 637 |
If |
| 638 |
.B _FORTIFY_SOURCE |
| 639 |
is set to 1, with compiler optimization level 1 |
| 640 |
.RI ( "gcc\ \-O1" ) |
| 641 |
and above, checks that shouldn't change the behavior of |
| 642 |
conforming programs are performed. |
| 643 |
With |
| 644 |
.B _FORTIFY_SOURCE |
| 645 |
set to 2, some more checking is added, but |
| 646 |
some conforming programs might fail. |
| 647 |
.\" For example, given the following code |
| 648 |
.\" int d; |
| 649 |
.\" char buf[1000], buf[1000]; |
| 650 |
.\" strcpy(fmt, "Hello world\n%n"); |
| 651 |
.\" snprintf(buf, sizeof(buf), fmt, &d); |
| 652 |
.\" |
| 653 |
.\" Compiling with "gcc -D_FORTIFY_SOURCE=2 -O1" and then running will |
| 654 |
.\" cause the following diagnostic at run time at the snprintf() call |
| 655 |
.\" |
| 656 |
.\" *** %n in writable segment detected *** |
| 657 |
.\" Aborted (core dumped) |
| 658 |
.\" |
| 659 |
.IP |
| 660 |
Some of the checks can be performed at compile time |
| 661 |
(via macros logic implemented in header files), |
| 662 |
and result in compiler warnings; |
| 663 |
other checks take place at run time, |
| 664 |
and result in a run-time error if the check fails. |
| 665 |
.IP |
| 666 |
With |
| 667 |
.B _FORTIFY_SOURCE |
| 668 |
set to 3, additional checking is added to intercept |
| 669 |
some function calls used with an argument of variable size |
| 670 |
where the compiler can deduce an upper bound for its value. |
| 671 |
For example, a program where |
| 672 |
.BR malloc (3)'s |
| 673 |
size argument is variable |
| 674 |
can now be fortified. |
| 675 |
.IP |
| 676 |
Use of this macro requires compiler support, available since |
| 677 |
gcc 4.0 and clang 2.6. |
| 678 |
Use of |
| 679 |
.B _FORTIFY_SOURCE |
| 680 |
set to 3 requires gcc 12.0 or later, or clang 9.0 or later, |
| 681 |
in conjunction with glibc 2.33 or later. |
| 682 |
.\" glibc is not an absolute requirement (gcc has libssp; NetBSD/newlib |
| 683 |
.\" and Darwin each have their own implementation), but let's keep it |
| 684 |
.\" simple. |
| 685 |
.SS Default definitions, implicit definitions, and combining definitions |
| 686 |
If no feature test macros are explicitly defined, |
| 687 |
then the following feature test macros are defined by default: |
| 688 |
.B _BSD_SOURCE |
| 689 |
(in glibc 2.19 and earlier), |
| 690 |
.B _SVID_SOURCE |
| 691 |
(in glibc 2.19 and earlier), |
| 692 |
.B _DEFAULT_SOURCE |
| 693 |
(since glibc 2.19), |
| 694 |
.BR _POSIX_SOURCE , |
| 695 |
and |
| 696 |
.BR _POSIX_C_SOURCE =200809L |
| 697 |
(200112L before glibc 2.10; |
| 698 |
199506L before glibc 2.4; |
| 699 |
199309L before glibc 2.1). |
| 700 |
.P |
| 701 |
If any of |
| 702 |
.BR __STRICT_ANSI__ , |
| 703 |
.BR _ISOC99_SOURCE , |
| 704 |
.B _ISOC11_SOURCE |
| 705 |
(since glibc 2.18), |
| 706 |
.B _ISOC23_SOURCE |
| 707 |
(since glibc 2.40), |
| 708 |
.BR _POSIX_SOURCE , |
| 709 |
.BR _POSIX_C_SOURCE , |
| 710 |
.BR _XOPEN_SOURCE , |
| 711 |
.B _XOPEN_SOURCE_EXTENDED |
| 712 |
(in glibc 2.11 and earlier), |
| 713 |
.B _BSD_SOURCE |
| 714 |
(in glibc 2.19 and earlier), |
| 715 |
or |
| 716 |
.B _SVID_SOURCE |
| 717 |
(in glibc 2.19 and earlier) |
| 718 |
is explicitly defined, then |
| 719 |
.BR _BSD_SOURCE , |
| 720 |
.BR _SVID_SOURCE , |
| 721 |
and |
| 722 |
.B _DEFAULT_SOURCE |
| 723 |
are not defined by default. |
| 724 |
.P |
| 725 |
If |
| 726 |
.B _POSIX_SOURCE |
| 727 |
and |
| 728 |
.B _POSIX_C_SOURCE |
| 729 |
are not explicitly defined, |
| 730 |
and either |
| 731 |
.B __STRICT_ANSI__ |
| 732 |
is not defined or |
| 733 |
.B _XOPEN_SOURCE |
| 734 |
is defined with a value of 500 or more, then |
| 735 |
.IP \[bu] 3 |
| 736 |
.B _POSIX_SOURCE |
| 737 |
is defined with the value 1; |
| 738 |
and |
| 739 |
.IP \[bu] |
| 740 |
.B _POSIX_C_SOURCE |
| 741 |
is defined with one of the following values: |
| 742 |
.RS |
| 743 |
.IP \[bu] 3 |
| 744 |
2, |
| 745 |
if |
| 746 |
.B _XOPEN_SOURCE |
| 747 |
is defined with a value less than 500; |
| 748 |
.IP \[bu] |
| 749 |
199506L, |
| 750 |
if |
| 751 |
.B _XOPEN_SOURCE |
| 752 |
is defined with a value greater than or equal to 500 and less than 600; |
| 753 |
or |
| 754 |
.IP \[bu] |
| 755 |
(since glibc 2.4) 200112L, |
| 756 |
if |
| 757 |
.B _XOPEN_SOURCE |
| 758 |
is defined with a value greater than or equal to 600 and less than 700. |
| 759 |
.IP \[bu] |
| 760 |
(Since glibc 2.10) |
| 761 |
200809L, |
| 762 |
if |
| 763 |
.B _XOPEN_SOURCE |
| 764 |
is defined with a value greater than or equal to 700. |
| 765 |
.IP \[bu] |
| 766 |
Older versions of glibc do not know about the values |
| 767 |
200112L and 200809L for |
| 768 |
.BR _POSIX_C_SOURCE , |
| 769 |
and the setting of this macro will depend on the glibc version. |
| 770 |
.IP \[bu] |
| 771 |
If |
| 772 |
.B _XOPEN_SOURCE |
| 773 |
is undefined, then the setting of |
| 774 |
.B _POSIX_C_SOURCE |
| 775 |
depends on the glibc version: |
| 776 |
199506L, before glibc 2.4; |
| 777 |
200112L, since glibc 2.4 to glibc 2.9; |
| 778 |
and |
| 779 |
200809L, since glibc 2.10. |
| 780 |
.RE |
| 781 |
.P |
| 782 |
Multiple macros can be defined; |
| 783 |
the results are additive. |
| 784 |
.SH STANDARDS |
| 785 |
POSIX.1 specifies |
| 786 |
.BR _POSIX_C_SOURCE , |
| 787 |
.BR _POSIX_SOURCE , |
| 788 |
and |
| 789 |
.BR _XOPEN_SOURCE . |
| 790 |
.P |
| 791 |
.B _FILE_OFFSET_BITS |
| 792 |
is not specified by any standard, |
| 793 |
but is employed on some other implementations. |
| 794 |
.P |
| 795 |
.BR _BSD_SOURCE , |
| 796 |
.BR _SVID_SOURCE , |
| 797 |
.BR _DEFAULT_SOURCE , |
| 798 |
.BR _ATFILE_SOURCE , |
| 799 |
.BR _GNU_SOURCE , |
| 800 |
.BR _FORTIFY_SOURCE , |
| 801 |
.BR _REENTRANT , |
| 802 |
and |
| 803 |
.B _THREAD_SAFE |
| 804 |
are specific to glibc. |
| 805 |
.SH HISTORY |
| 806 |
.B _XOPEN_SOURCE_EXTENDED |
| 807 |
was specified by XPG4v2 (aka SUSv1), but is not present in SUSv2 and later. |
| 808 |
.SH NOTES |
| 809 |
.I <features.h> |
| 810 |
is a Linux/glibc-specific header file. |
| 811 |
Other systems have an analogous file, but typically with a different name. |
| 812 |
This header file is automatically included by other header files as |
| 813 |
required: it is not necessary to explicitly include it in order to |
| 814 |
employ feature test macros. |
| 815 |
.P |
| 816 |
According to which of the above feature test macros are defined, |
| 817 |
.I <features.h> |
| 818 |
internally defines various other macros that are checked by |
| 819 |
other glibc header files. |
| 820 |
These macros have names prefixed by two underscores (e.g., |
| 821 |
.BR __USE_MISC ). |
| 822 |
Programs should |
| 823 |
.I never |
| 824 |
define these macros directly: |
| 825 |
instead, the appropriate feature test macro(s) from the |
| 826 |
list above should be employed. |
| 827 |
.SH EXAMPLES |
| 828 |
The program below can be used to explore how the various |
| 829 |
feature test macros are set depending on the glibc version |
| 830 |
and what feature test macros are explicitly set. |
| 831 |
The following shell session, on a system with glibc 2.10, |
| 832 |
shows some examples of what we would see: |
| 833 |
.P |
| 834 |
.in +4n |
| 835 |
.EX |
| 836 |
.RB $ " cc ftm.c" |
| 837 |
.RB $ " ./a.out" |
| 838 |
_POSIX_SOURCE defined |
| 839 |
_POSIX_C_SOURCE defined: 200809L |
| 840 |
_BSD_SOURCE defined |
| 841 |
_SVID_SOURCE defined |
| 842 |
_ATFILE_SOURCE defined |
| 843 |
.RB $ " cc \-D_XOPEN_SOURCE=500 ftm.c" |
| 844 |
.RB $ " ./a.out" |
| 845 |
_POSIX_SOURCE defined |
| 846 |
_POSIX_C_SOURCE defined: 199506L |
| 847 |
_XOPEN_SOURCE defined: 500 |
| 848 |
.RB $ " cc \-D_GNU_SOURCE ftm.c" |
| 849 |
.RB $ " ./a.out" |
| 850 |
_POSIX_SOURCE defined |
| 851 |
_POSIX_C_SOURCE defined: 200809L |
| 852 |
_ISOC99_SOURCE defined |
| 853 |
_XOPEN_SOURCE defined: 700 |
| 854 |
_XOPEN_SOURCE_EXTENDED defined |
| 855 |
_LARGEFILE64_SOURCE defined |
| 856 |
_BSD_SOURCE defined |
| 857 |
_SVID_SOURCE defined |
| 858 |
_ATFILE_SOURCE defined |
| 859 |
_GNU_SOURCE defined |
| 860 |
.EE |
| 861 |
.in |
| 862 |
.SS Program source |
| 863 |
\& |
| 864 |
.EX |
| 865 |
/* ftm.c */ |
| 866 |
\& |
| 867 |
#include <stdint.h> |
| 868 |
#include <stdio.h> |
| 869 |
#include <unistd.h> |
| 870 |
#include <stdlib.h> |
| 871 |
\& |
| 872 |
int |
| 873 |
main(int argc, char *argv[]) |
| 874 |
{ |
| 875 |
#ifdef _POSIX_SOURCE |
| 876 |
printf("_POSIX_SOURCE defined\[rs]n"); |
| 877 |
#endif |
| 878 |
\& |
| 879 |
#ifdef _POSIX_C_SOURCE |
| 880 |
printf("_POSIX_C_SOURCE defined: %jdL\[rs]n", |
| 881 |
(intmax_t) _POSIX_C_SOURCE); |
| 882 |
#endif |
| 883 |
\& |
| 884 |
#ifdef _ISOC99_SOURCE |
| 885 |
printf("_ISOC99_SOURCE defined\[rs]n"); |
| 886 |
#endif |
| 887 |
\& |
| 888 |
#ifdef _ISOC11_SOURCE |
| 889 |
printf("_ISOC11_SOURCE defined\[rs]n"); |
| 890 |
#endif |
| 891 |
\& |
| 892 |
#ifdef _ISOC23_SOURCE |
| 893 |
printf("_ISOC23_SOURCE defined\[rs]n"); |
| 894 |
#endif |
| 895 |
\& |
| 896 |
#ifdef _XOPEN_SOURCE |
| 897 |
printf("_XOPEN_SOURCE defined: %d\[rs]n", _XOPEN_SOURCE); |
| 898 |
#endif |
| 899 |
\& |
| 900 |
#ifdef _XOPEN_SOURCE_EXTENDED |
| 901 |
printf("_XOPEN_SOURCE_EXTENDED defined\[rs]n"); |
| 902 |
#endif |
| 903 |
\& |
| 904 |
#ifdef _LARGEFILE64_SOURCE |
| 905 |
printf("_LARGEFILE64_SOURCE defined\[rs]n"); |
| 906 |
#endif |
| 907 |
\& |
| 908 |
#ifdef _FILE_OFFSET_BITS |
| 909 |
printf("_FILE_OFFSET_BITS defined: %d\[rs]n", _FILE_OFFSET_BITS); |
| 910 |
#endif |
| 911 |
\& |
| 912 |
#ifdef _TIME_BITS |
| 913 |
printf("_TIME_BITS defined: %d\[rs]n", _TIME_BITS); |
| 914 |
#endif |
| 915 |
\& |
| 916 |
#ifdef _BSD_SOURCE |
| 917 |
printf("_BSD_SOURCE defined\[rs]n"); |
| 918 |
#endif |
| 919 |
\& |
| 920 |
#ifdef _SVID_SOURCE |
| 921 |
printf("_SVID_SOURCE defined\[rs]n"); |
| 922 |
#endif |
| 923 |
\& |
| 924 |
#ifdef _DEFAULT_SOURCE |
| 925 |
printf("_DEFAULT_SOURCE defined\[rs]n"); |
| 926 |
#endif |
| 927 |
\& |
| 928 |
#ifdef _ATFILE_SOURCE |
| 929 |
printf("_ATFILE_SOURCE defined\[rs]n"); |
| 930 |
#endif |
| 931 |
\& |
| 932 |
#ifdef _GNU_SOURCE |
| 933 |
printf("_GNU_SOURCE defined\[rs]n"); |
| 934 |
#endif |
| 935 |
\& |
| 936 |
#ifdef _REENTRANT |
| 937 |
printf("_REENTRANT defined\[rs]n"); |
| 938 |
#endif |
| 939 |
\& |
| 940 |
#ifdef _THREAD_SAFE |
| 941 |
printf("_THREAD_SAFE defined\[rs]n"); |
| 942 |
#endif |
| 943 |
\& |
| 944 |
#ifdef _FORTIFY_SOURCE |
| 945 |
printf("_FORTIFY_SOURCE defined\[rs]n"); |
| 946 |
#endif |
| 947 |
\& |
| 948 |
exit(EXIT_SUCCESS); |
| 949 |
} |
| 950 |
.EE |
| 951 |
.SH SEE ALSO |
| 952 |
.BR libc (7), |
| 953 |
.BR standards (7), |
| 954 |
.BR system_data_types (7) |
| 955 |
.P |
| 956 |
The section "Feature Test Macros" under |
| 957 |
.IR "info libc" . |
| 958 |
.\" But beware: the info libc document is out of date (Jul 07, mtk) |
| 959 |
.P |
| 960 |
.I /usr/include/features.h |