]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | @node Feature Test Macros |
2 | @subsection Feature Test Macros | |
3 | ||
4 | @cindex feature test macros | |
5 | The exact set of features available when you compile a source file | |
6 | is controlled by which @dfn{feature test macros} you define. | |
7 | ||
8 | If you compile your programs using @samp{gcc -ansi}, you get only the | |
f65fd747 | 9 | @w{ISO C} library features, unless you explicitly request additional |
28f540f4 RM |
10 | features by defining one or more of the feature macros. |
11 | @xref{Invoking GCC,, GNU CC Command Options, gcc.info, The GNU CC Manual}, | |
12 | for more information about GCC options.@refill | |
13 | ||
14 | You should define these macros by using @samp{#define} preprocessor | |
15 | directives at the top of your source code files. These directives | |
16 | @emph{must} come before any @code{#include} of a system header file. It | |
17 | is best to make them the very first thing in the file, preceded only by | |
18 | comments. You could also use the @samp{-D} option to GCC, but it's | |
19 | better if you make the source files indicate their own meaning in a | |
20 | self-contained way. | |
21 | ||
6796bc80 UD |
22 | This system exists to allow the library to conform to multiple standards. |
23 | Although the different standards are often described as supersets of each | |
24 | other, they are usually incompatible because larger standards require | |
25 | functions with names that smaller ones reserve to the user program. This | |
26 | is not mere pedantry --- it has been a problem in practice. For instance, | |
27 | some non-GNU programs define functions named @code{getline} that have | |
28 | nothing to do with this library's @code{getline}. They would not be | |
49c091e5 | 29 | compilable if all features were enabled indiscriminately. |
6796bc80 UD |
30 | |
31 | This should not be used to verify that a program conforms to a limited | |
49c091e5 | 32 | standard. It is insufficient for this purpose, as it will not protect you |
6796bc80 | 33 | from including header files outside the standard, or relying on semantics |
b4cbd371 | 34 | undefined within the standard. |
6796bc80 | 35 | |
28f540f4 RM |
36 | @comment (none) |
37 | @comment POSIX.1 | |
38 | @defvr Macro _POSIX_SOURCE | |
39 | If you define this macro, then the functionality from the POSIX.1 | |
40 | standard (IEEE Standard 1003.1) is available, as well as all of the | |
f65fd747 | 41 | @w{ISO C} facilities. |
1618c590 UD |
42 | |
43 | The state of @code{_POSIX_SOURCE} is irrelevant if you define the | |
44 | macro @code{_POSIX_C_SOURCE} to a positive integer. | |
28f540f4 RM |
45 | @end defvr |
46 | ||
47 | @comment (none) | |
48 | @comment POSIX.2 | |
86187531 | 49 | @defvr Macro _POSIX_C_SOURCE |
1618c590 UD |
50 | Define this macro to a positive integer to control which POSIX |
51 | functionality is made available. The greater the value of this macro, | |
52 | the more functionality is made available. | |
53 | ||
54 | If you define this macro to a value greater than or equal to @code{1}, | |
55 | then the functionality from the 1990 edition of the POSIX.1 standard | |
56 | (IEEE Standard 1003.1-1990) is made available. | |
57 | ||
58 | If you define this macro to a value greater than or equal to @code{2}, | |
59 | then the functionality from the 1992 edition of the POSIX.2 standard | |
60 | (IEEE Standard 1003.2-1992) is made available. | |
61 | ||
62 | If you define this macro to a value greater than or equal to @code{199309L}, | |
63 | then the functionality from the 1993 edition of the POSIX.1b standard | |
64 | (IEEE Standard 1003.1b-1993) is made available. | |
65 | ||
66 | Greater values for @code{_POSIX_C_SOURCE} will enable future extensions. | |
67 | The POSIX standards process will define these values as necessary, and | |
1f77f049 | 68 | @theglibc{} should support them some time after they become standardized. |
1618c590 UD |
69 | The 1996 edition of POSIX.1 (ISO/IEC 9945-1: 1996) states that |
70 | if you define @code{_POSIX_C_SOURCE} to a value greater than | |
71 | or equal to @code{199506L}, then the functionality from the 1996 | |
72 | edition is made available. | |
28f540f4 RM |
73 | @end defvr |
74 | ||
2c6fe0bd | 75 | @comment (none) |
dfd2257a | 76 | @comment X/Open |
2c6fe0bd | 77 | @defvr Macro _XOPEN_SOURCE |
4260bc74 UD |
78 | @comment (none) |
79 | @comment X/Open | |
ca34d7a7 | 80 | @defvrx Macro _XOPEN_SOURCE_EXTENDED |
6d52618b UD |
81 | If you define this macro, functionality described in the X/Open |
82 | Portability Guide is included. This is a superset of the POSIX.1 and | |
2c6fe0bd | 83 | POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and |
6d52618b | 84 | @code{_POSIX_C_SOURCE} are automatically defined. |
2c6fe0bd | 85 | |
6d52618b UD |
86 | As the unification of all Unices, functionality only available in |
87 | BSD and SVID is also included. | |
2c6fe0bd UD |
88 | |
89 | If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more | |
90 | functionality is available. The extra functions will make all functions | |
91 | available which are necessary for the X/Open Unix brand. | |
a5a0310d UD |
92 | |
93 | If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes | |
94 | all functionality described so far plus some new definitions from the | |
dd7d45e8 | 95 | Single Unix Specification, @w{version 2}. |
28f540f4 RM |
96 | @end defvr |
97 | ||
dfd2257a UD |
98 | @comment (NONE) |
99 | @comment X/Open | |
100 | @defvr Macro _LARGEFILE_SOURCE | |
101 | If this macro is defined some extra functions are available which | |
cf6960d7 | 102 | rectify a few shortcomings in all previous standards. Specifically, |
dfd2257a UD |
103 | the functions @code{fseeko} and @code{ftello} are available. Without |
104 | these functions the difference between the @w{ISO C} interface | |
105 | (@code{fseek}, @code{ftell}) and the low-level POSIX interface | |
106 | (@code{lseek}) would lead to problems. | |
107 | ||
108 | This macro was introduced as part of the Large File Support extension (LFS). | |
109 | @end defvr | |
110 | ||
111 | @comment (NONE) | |
112 | @comment X/Open | |
310b3460 | 113 | @defvr Macro _LARGEFILE64_SOURCE |
0aa9fad6 | 114 | If you define this macro an additional set of functions is made available |
e8b1163e | 115 | which enables @w{32 bit} systems to use files of sizes beyond |
dfd2257a UD |
116 | the usual limit of 2GB. This interface is not available if the system |
117 | does not support files that large. On systems where the natural file | |
118 | size limit is greater than 2GB (i.e., on @w{64 bit} systems) the new | |
119 | functions are identical to the replaced functions. | |
120 | ||
121 | The new functionality is made available by a new set of types and | |
e8b1163e | 122 | functions which replace the existing ones. The names of these new objects |
dfd2257a UD |
123 | contain @code{64} to indicate the intention, e.g., @code{off_t} |
124 | vs. @code{off64_t} and @code{fseeko} vs. @code{fseeko64}. | |
125 | ||
126 | This macro was introduced as part of the Large File Support extension | |
cf6960d7 UD |
127 | (LFS). It is a transition interface for the period when @w{64 bit} |
128 | offsets are not generally used (see @code{_FILE_OFFSET_BITS}). | |
310b3460 | 129 | @end defvr |
dfd2257a UD |
130 | |
131 | @comment (NONE) | |
132 | @comment X/Open | |
8619129f | 133 | @defvr Macro _FILE_OFFSET_BITS |
e8b1163e | 134 | This macro determines which file system interface shall be used, one |
cf6960d7 UD |
135 | replacing the other. Whereas @code{_LARGEFILE64_SOURCE} makes the @w{64 |
136 | bit} interface available as an additional interface, | |
e8b1163e | 137 | @code{_FILE_OFFSET_BITS} allows the @w{64 bit} interface to |
dfd2257a UD |
138 | replace the old interface. |
139 | ||
e8b1163e AJ |
140 | If @code{_FILE_OFFSET_BITS} is undefined, or if it is defined to the |
141 | value @code{32}, nothing changes. The @w{32 bit} interface is used and | |
dfd2257a UD |
142 | types like @code{off_t} have a size of @w{32 bits} on @w{32 bit} |
143 | systems. | |
144 | ||
e8b1163e | 145 | If the macro is defined to the value @code{64}, the large file interface |
dfd2257a | 146 | replaces the old interface. I.e., the functions are not made available |
cf6960d7 UD |
147 | under different names (as they are with @code{_LARGEFILE64_SOURCE}). |
148 | Instead the old function names now reference the new functions, e.g., a | |
149 | call to @code{fseeko} now indeed calls @code{fseeko64}. | |
dfd2257a UD |
150 | |
151 | This macro should only be selected if the system provides mechanisms for | |
152 | handling large files. On @w{64 bit} systems this macro has no effect | |
153 | since the @code{*64} functions are identical to the normal functions. | |
154 | ||
155 | This macro was introduced as part of the Large File Support extension | |
156 | (LFS). | |
310b3460 | 157 | @end defvr |
dfd2257a | 158 | |
b4cbd371 UD |
159 | @comment (none) |
160 | @comment GNU | |
161 | @defvr Macro _ISOC99_SOURCE | |
63ae7b63 | 162 | Until the revised @w{ISO C} standard is widely adopted the new features |
1f77f049 | 163 | are not automatically enabled. @Theglibc{} nevertheless has a complete |
b4cbd371 UD |
164 | implementation of the new standard and to enable the new features the |
165 | macro @code{_ISOC99_SOURCE} should be defined. | |
166 | @end defvr | |
167 | ||
28f540f4 RM |
168 | @comment (none) |
169 | @comment GNU | |
170 | @defvr Macro _GNU_SOURCE | |
b4cbd371 UD |
171 | If you define this macro, everything is included: @w{ISO C89}, @w{ISO |
172 | C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions. In | |
173 | the cases where POSIX.1 conflicts with BSD, the POSIX definitions take | |
174 | precedence. | |
28f540f4 RM |
175 | @end defvr |
176 | ||
c688b419 JM |
177 | @comment (none) |
178 | @comment GNU | |
179 | @defvr Macro _DEFAULT_SOURCE | |
180 | If you define this macro, most features are included apart from | |
c941736c JM |
181 | X/Open, LFS and GNU extensions: the effect is to enable features from |
182 | the 2008 edition of POSIX, as well as certain BSD and SVID features | |
183 | without a separate feature test macro to control them. Defining this | |
c688b419 JM |
184 | macro, on its own and without using compiler options such as |
185 | @option{-ansi} or @option{-std=c99}, has the same effect as not | |
186 | defining any feature test macros; defining it together with other | |
187 | feature test macros, or when options such as @option{-ansi} are used, | |
188 | enables those features even when the other options would otherwise | |
189 | cause them to be disabled. | |
190 | @end defvr | |
191 | ||
ba1ffaa1 UD |
192 | @comment (none) |
193 | @comment GNU | |
26761c28 UD |
194 | @defvr Macro _REENTRANT |
195 | @defvrx Macro _THREAD_SAFE | |
196 | If you define one of these macros, reentrant versions of several functions get | |
2c6fe0bd | 197 | declared. Some of the functions are specified in POSIX.1c but many others |
1f77f049 | 198 | are only available on a few other systems or are unique to @theglibc{}. |
e8b1163e AJ |
199 | The problem is the delay in the standardization of the thread safe C library |
200 | interface. | |
ba1ffaa1 | 201 | |
e8b1163e | 202 | Unlike on some other systems, no special version of the C library must be |
ba1ffaa1 UD |
203 | used for linking. There is only one version but while compiling this |
204 | it must have been specified to compile as thread safe. | |
205 | @end defvr | |
206 | ||
28f540f4 | 207 | We recommend you use @code{_GNU_SOURCE} in new programs. If you don't |
c688b419 JM |
208 | specify the @samp{-ansi} option to GCC, or other conformance options |
209 | such as @option{-std=c99}, and don't define any of these macros | |
210 | explicitly, the effect is the same as defining @code{_DEFAULT_SOURCE} | |
211 | to 1. | |
28f540f4 RM |
212 | |
213 | When you define a feature test macro to request a larger class of features, | |
214 | it is harmless to define in addition a feature test macro for a subset of | |
215 | those features. For example, if you define @code{_POSIX_C_SOURCE}, then | |
216 | defining @code{_POSIX_SOURCE} as well has no effect. Likewise, if you | |
217 | define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or | |
c941736c | 218 | @code{_POSIX_C_SOURCE} as well has no effect. |