]>
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 | |
68 | the GNU C Library should support them some time after they become standardized. | |
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. | |
dd7d45e8 UD |
73 | |
74 | The Single Unix Specification specify that setting this macro to the | |
75 | value @code{199506L} selects all the values specified by the POSIX | |
76 | standards plus those of the Single Unix Specification, i.e., is the | |
77 | same as if @code{_XOPEN_SOURCE} is set to @code{500} (see below). | |
28f540f4 RM |
78 | @end defvr |
79 | ||
80 | @comment (none) | |
81 | @comment GNU | |
82 | @defvr Macro _BSD_SOURCE | |
83 | If you define this macro, functionality derived from 4.3 BSD Unix is | |
f65fd747 | 84 | included as well as the @w{ISO C}, POSIX.1, and POSIX.2 material. |
28f540f4 RM |
85 | |
86 | Some of the features derived from 4.3 BSD Unix conflict with the | |
87 | corresponding features specified by the POSIX.1 standard. If this | |
88 | macro is defined, the 4.3 BSD definitions take precedence over the | |
89 | POSIX definitions. | |
90 | ||
91 | Due to the nature of some of the conflicts between 4.3 BSD and POSIX.1, | |
92 | you need to use a special @dfn{BSD compatibility library} when linking | |
93 | programs compiled for BSD compatibility. This is because some functions | |
94 | must be defined in two different ways, one of them in the normal C | |
95 | library, and one of them in the compatibility library. If your program | |
96 | defines @code{_BSD_SOURCE}, you must give the option @samp{-lbsd-compat} | |
97 | to the compiler or linker when linking the program, to tell it to find | |
98 | functions in this special compatibility library before looking for them in | |
99 | the normal C library. | |
100 | @pindex -lbsd-compat | |
101 | @pindex bsd-compat | |
102 | @cindex BSD compatibility library. | |
103 | @end defvr | |
104 | ||
105 | @comment (none) | |
106 | @comment GNU | |
107 | @defvr Macro _SVID_SOURCE | |
108 | If you define this macro, functionality derived from SVID is | |
f65fd747 | 109 | included as well as the @w{ISO C}, POSIX.1, POSIX.2, and X/Open material. |
2c6fe0bd UD |
110 | @end defvr |
111 | ||
112 | @comment (none) | |
dfd2257a | 113 | @comment X/Open |
2c6fe0bd | 114 | @defvr Macro _XOPEN_SOURCE |
4260bc74 UD |
115 | @comment (none) |
116 | @comment X/Open | |
ca34d7a7 | 117 | @defvrx Macro _XOPEN_SOURCE_EXTENDED |
6d52618b UD |
118 | If you define this macro, functionality described in the X/Open |
119 | Portability Guide is included. This is a superset of the POSIX.1 and | |
2c6fe0bd | 120 | POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and |
6d52618b | 121 | @code{_POSIX_C_SOURCE} are automatically defined. |
2c6fe0bd | 122 | |
6d52618b UD |
123 | As the unification of all Unices, functionality only available in |
124 | BSD and SVID is also included. | |
2c6fe0bd UD |
125 | |
126 | If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more | |
127 | functionality is available. The extra functions will make all functions | |
128 | available which are necessary for the X/Open Unix brand. | |
a5a0310d UD |
129 | |
130 | If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes | |
131 | all functionality described so far plus some new definitions from the | |
dd7d45e8 | 132 | Single Unix Specification, @w{version 2}. |
28f540f4 RM |
133 | @end defvr |
134 | ||
dfd2257a UD |
135 | @comment (NONE) |
136 | @comment X/Open | |
137 | @defvr Macro _LARGEFILE_SOURCE | |
138 | If this macro is defined some extra functions are available which | |
f2ea0f5b | 139 | rectify a few shortcomings in all previous standards. More concrete |
dfd2257a UD |
140 | the functions @code{fseeko} and @code{ftello} are available. Without |
141 | these functions the difference between the @w{ISO C} interface | |
142 | (@code{fseek}, @code{ftell}) and the low-level POSIX interface | |
143 | (@code{lseek}) would lead to problems. | |
144 | ||
145 | This macro was introduced as part of the Large File Support extension (LFS). | |
146 | @end defvr | |
147 | ||
148 | @comment (NONE) | |
149 | @comment X/Open | |
310b3460 | 150 | @defvr Macro _LARGEFILE64_SOURCE |
dfd2257a UD |
151 | If you define this macro an additional set of function gets available |
152 | which enables to use on @w{32 bit} systems to use files of sizes beyond | |
153 | the usual limit of 2GB. This interface is not available if the system | |
154 | does not support files that large. On systems where the natural file | |
155 | size limit is greater than 2GB (i.e., on @w{64 bit} systems) the new | |
156 | functions are identical to the replaced functions. | |
157 | ||
158 | The new functionality is made available by a new set of types and | |
159 | functions which replace existing. The names of these new objects | |
160 | contain @code{64} to indicate the intention, e.g., @code{off_t} | |
161 | vs. @code{off64_t} and @code{fseeko} vs. @code{fseeko64}. | |
162 | ||
163 | This macro was introduced as part of the Large File Support extension | |
164 | (LFS). It is a transition interface for the time @w{64 bit} offsets are | |
165 | not generally used (see @code{_FILE_OFFSET_BITS}. | |
310b3460 | 166 | @end defvr |
dfd2257a UD |
167 | |
168 | @comment (NONE) | |
169 | @comment X/Open | |
8619129f | 170 | @defvr Macro _FILE_OFFSET_BITS |
dfd2257a UD |
171 | This macro lets decide which file system interface shall be used, one |
172 | replacing the other. While @code{_LARGEFILE64_SOURCE} makes the @w{64 | |
173 | bit} interface available as an additional interface | |
174 | @code{_FILE_OFFSET_BITS} allows to use the @w{64 bit} interface to | |
175 | replace the old interface. | |
176 | ||
177 | If @code{_FILE_OFFSET_BITS} is undefined or if it is defined to the | |
178 | value @code{32} nothing changes. The @w{32 bit} interface is used and | |
179 | types like @code{off_t} have a size of @w{32 bits} on @w{32 bit} | |
180 | systems. | |
181 | ||
182 | If the macro is defined to the value @code{64} the large file interface | |
183 | replaces the old interface. I.e., the functions are not made available | |
184 | under different names as @code{_LARGEFILE64_SOURCE} does. Instead the | |
185 | old function names now reference the new functions, e.g., a call to | |
186 | @code{fseeko} now indeed calls @code{fseeko64}. | |
187 | ||
188 | This macro should only be selected if the system provides mechanisms for | |
189 | handling large files. On @w{64 bit} systems this macro has no effect | |
190 | since the @code{*64} functions are identical to the normal functions. | |
191 | ||
192 | This macro was introduced as part of the Large File Support extension | |
193 | (LFS). | |
310b3460 | 194 | @end defvr |
dfd2257a | 195 | |
b4cbd371 UD |
196 | @comment (none) |
197 | @comment GNU | |
198 | @defvr Macro _ISOC99_SOURCE | |
63ae7b63 | 199 | Until the revised @w{ISO C} standard is widely adopted the new features |
b4cbd371 UD |
200 | are not automatically enabled. The GNU libc nevertheless has a complete |
201 | implementation of the new standard and to enable the new features the | |
202 | macro @code{_ISOC99_SOURCE} should be defined. | |
203 | @end defvr | |
204 | ||
28f540f4 RM |
205 | @comment (none) |
206 | @comment GNU | |
207 | @defvr Macro _GNU_SOURCE | |
b4cbd371 UD |
208 | If you define this macro, everything is included: @w{ISO C89}, @w{ISO |
209 | C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions. In | |
210 | the cases where POSIX.1 conflicts with BSD, the POSIX definitions take | |
211 | precedence. | |
28f540f4 RM |
212 | |
213 | If you want to get the full effect of @code{_GNU_SOURCE} but make the | |
214 | BSD definitions take precedence over the POSIX definitions, use this | |
215 | sequence of definitions: | |
216 | ||
217 | @smallexample | |
218 | #define _GNU_SOURCE | |
219 | #define _BSD_SOURCE | |
220 | #define _SVID_SOURCE | |
221 | @end smallexample | |
222 | ||
223 | Note that if you do this, you must link your program with the BSD | |
224 | compatibility library by passing the @samp{-lbsd-compat} option to the | |
225 | compiler or linker. @strong{Note:} If you forget to do this, you may | |
226 | get very strange errors at run time. | |
227 | @end defvr | |
228 | ||
ba1ffaa1 UD |
229 | @comment (none) |
230 | @comment GNU | |
26761c28 UD |
231 | @defvr Macro _REENTRANT |
232 | @defvrx Macro _THREAD_SAFE | |
233 | If you define one of these macros, reentrant versions of several functions get | |
2c6fe0bd | 234 | declared. Some of the functions are specified in POSIX.1c but many others |
ba1ffaa1 UD |
235 | are only available on a few other systems or are unique to GNU libc. |
236 | The problem is that the standardization of the thread safe C library | |
237 | interface still is behind. | |
238 | ||
239 | Unlike on some other systems no special version of the C library must be | |
240 | used for linking. There is only one version but while compiling this | |
241 | it must have been specified to compile as thread safe. | |
242 | @end defvr | |
243 | ||
28f540f4 | 244 | We recommend you use @code{_GNU_SOURCE} in new programs. If you don't |
2303f5fd UD |
245 | specify the @samp{-ansi} option to GCC and don't define any of these |
246 | macros explicitly, the effect is the same as defining | |
247 | @code{_POSIX_C_SOURCE} to 2 and @code{_POSIX_SOURCE}, | |
248 | @code{_SVID_SOURCE}, and @code{_BSD_SOURCE} to 1. | |
28f540f4 RM |
249 | |
250 | When you define a feature test macro to request a larger class of features, | |
251 | it is harmless to define in addition a feature test macro for a subset of | |
252 | those features. For example, if you define @code{_POSIX_C_SOURCE}, then | |
253 | defining @code{_POSIX_SOURCE} as well has no effect. Likewise, if you | |
254 | define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or | |
255 | @code{_POSIX_C_SOURCE} or @code{_SVID_SOURCE} as well has no effect. | |
256 | ||
257 | Note, however, that the features of @code{_BSD_SOURCE} are not a subset of | |
258 | any of the other feature test macros supported. This is because it defines | |
259 | BSD features that take precedence over the POSIX features that are | |
260 | requested by the other macros. For this reason, defining | |
261 | @code{_BSD_SOURCE} in addition to the other feature test macros does have | |
262 | an effect: it causes the BSD features to take priority over the conflicting | |
263 | POSIX features. |