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