diff options
| -rw-r--r-- | man7/feature_test_macros.7 | 123 |
1 files changed, 112 insertions, 11 deletions
diff --git a/man7/feature_test_macros.7 b/man7/feature_test_macros.7 index 1007322370..9f2af02c3e 100644 --- a/man7/feature_test_macros.7 +++ b/man7/feature_test_macros.7 @@ -23,7 +23,7 @@ .\" the source, must acknowledge the copyright and authors of this work. .\" .\" -.TH FEATURE_TEST_MACROS 7 2006-04-26 "Linux" "Linux Programmer's Manual" +.TH FEATURE_TEST_MACROS 7 2006-07-26 "Linux" "Linux Programmer's Manual" .SH NAME feature_test_macros \- feature test macros .SH SYNOPSIS @@ -47,18 +47,71 @@ This can either be done in the compilation command .RI ( "cc \-DMACRO=value" ) or by defining the macro within the source code before including any headers. +.SS Specification of feature test macro requirements in manual pages +When a function requires that a feature test macro is defined, +the manual page SYNOPSIS includes a note of the following form +(this example from the +.BR chmod (2) +man page): +.RS +.sp +.B #include <sys/stat.h> +.sp +.BI "int chmod(const char *" path ", mode_t " mode ); +.br +.BI "int fchmod(int " fildes ", mode_t " mode ); +.sp +.in -4n +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.in +.sp +.BR fchmod (): +_BSD_SOURCE || _XOPEN_SOURCE >= 500 +.RE +.PP +The \fB||\fP means that in order to obtain the declaration of +.BR fchmod (2) +from +.IR <sys/stat.h> , +\fIeither\fP of the following macro +definitions must be made before including any header files: +.RS +.nf + +.B #define _BSD_SOURCE +.BR "#define _XOPEN_SOURCE 500" " /* or any value > 500 */" +.fi +.RE +.PP +Alternatively, equivalent definitions can be included in the +compilation command: +.RS +.nf +cc -D_BSD_SOURCE +cc -D_XOPEN_SOURCE=500 # Or any value > 500 +.fi +.RE +.PP +Note that, as described below, some feature test macros are +defined be default, so that it may not always be necessary to +explicitly specify the feature test macro(s) shown +in the SYNOPSIS. +.SS Feature test macros understood by glibc Linux/glibc understands the following feature test macros: .\" FIXME ? add _ATFILE_SOURCE to this list .TP .B _POSIX_C_SOURCE Defining this macro with the value 1 causes header files to expose definitions conforming to POSIX.1-1990 and ISO C (1990). -Defining with the value 199309 or greater additionally exposes +Defining with the value L or greater additionally exposes +definitions for POSIX.2-1992. +Defining with the value 199309L or greater additionally exposes definitions for POSIX.1b (real-time extensions). -Defining with the value 199506 or greater additionally exposes +Defining with the value 199506L or greater additionally exposes definitions for POSIX.1c (threads). -Defining with the value 200112 exposes definitions corresponding +Defining with the value 200112L exposes definitions corresponding to the POSIX.1-2001 base specification (excluding the XSI extension). .TP .B _POSIX_SOURCE @@ -74,12 +127,28 @@ definitions for SUSv2 (UNIX 98). Defining with the value 600 or greater additionally exposes definitions for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification plus the XSI extension) and C 99 definitions. +.IP +Defining +.B _XOPEN_SOURCE +also implicitly defines +.BR _POSIX_C_SOURCE : +with the value 2, if +.B _XOPEN_SOURCE +is less than 500; +with the value 199506L, if 500 <= +.B _XOPEN_SOURCE +< 600; or with the value 200112L if +.B _XOPEN_SOURCE +>= 600. .TP .B _XOPEN_SOURCE_EXTENDED If this macro is defined with the value 1, and the .BR _XOPEN_SOURCE is defined, then expose definitions corresponding to the XPG4v2 -UNIX extensions. +(SUSv1) UNIX extensions (UNIX 95). +This macro is also implicitly defined if +.B _XOPEN_SOURCE +is defined with a value of 500 or more. .TP .B _ISOC99_SOURCE Exposes C 99 extensions to ISO C (1990). @@ -89,6 +158,19 @@ Expose definitions for the alternative API specified by the LFS (Large File Summit) as a "transitional extension" to the Single UNIX Specification. (See http://opengroup.org/platform/lfs.html.) +The alternative API consists of a set of new objects +(i.e., functions and types) whose names are suffixed with "64" +(e.g., +.I off64_t +versus +.IR off_t , +.BR lseek64 () +versus +.BR lseek (), +etc.). +New programs should not employ this interface; instead +.IR _FILE_OFFSET_BITS=64 +should be employed. .TP .B _FILE_OFFSET_BITS Defining this macro with the value 64 @@ -97,12 +179,24 @@ related to file I/O and file system operations into references to their 64-bit counterparts. This is useful for performing I/O on large files (> 2 Gigabytes) on 32-bit systems. +(Defining this macro permits correctly written programs to use +large files with only a recompilation being required.) +64-bit systems naturally permit file sizes greater than 2 Gigabytes, +and on those systems this macro has no effect. .TP .B _BSD_SOURCE Defining this macro with any value cause header files to expose BSD-derived definitions. Defining this macro also causes BSD definitions to be preferred in -some situations where standards conflict. +some situations where standards conflict, unless one or more of +.BR _SVID_SOURCE , +.BR _POSIX_SOURCE , +.BR _POSIX_C_SOURCE , +.BR _XOPEN_SOURCE , +.BR _XOPEN_SOURCE_EXTENDED , +or +.BR _GNU_SOURCE +is defined, in which case BSD definitions are disfavored. .TP .B _SVID_SOURCE Defining this macro with any value cause header files to expose @@ -117,11 +211,11 @@ Defining this macro (with any value) is equivalent to defining .BR _LARGEFILE64_SOURCE , .BR _ISOC99_SOURCE .BR _POSIX_C_SOURCE -with the value 1999506, -and +with the value 200112L, and .BR _XOPEN_SOURCE with the value 600. In addition, various GNU-specific extensions are also exposed. +Where standards conflict, BSD definitions are disfavored. .TP .B _REENTRANT Defining this macro exposes definitions of certain reentrant functions. @@ -187,14 +281,14 @@ is invoked, the following macros are defined by default: .BR _SVID_SOURCE , .BR _POSIX_SOURCE , and -.BR _POSIX_C_SOURCE =199506. +.BR _POSIX_C_SOURCE =199506L. If individual macros are defined, then other macros are disabled unless they are also explicitly defined. (Exception: if .BR _POSIX_C_SOURCE is not otherwise defined, -then it is always defined with the value 200112 -(199506 in glibc versions before 2.4), +then it is always defined with the value 200112L +(199506L in glibc versions before 2.4), unless the compiler is invoked in one of its standard modes, for example, the .I -std=c99 flag.) @@ -218,6 +312,7 @@ but is employed on some other implementations. and .BR _THREAD_SAFE are Linux (glibc) specific. +.\" FIXME ? add _ATFILE_SOURCE to this list .SH NOTES .I <features.h> is a Linux/glibc specific header file. @@ -236,3 +331,9 @@ instead, the appropriate feature test macro(s) from the list above should be employed. .SH SEE ALSO .BR standards (7) +.sp +The section "Feature Test Macros" under +.IR "info libc" . +.\" But beware: the info libc document is out of date (Jul 07, mtk) +.sp +.I /usr/include/features.h |