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