]>
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. |
28f540f4 RM |
28 | @end defvr |
29 | ||
30 | @comment (none) | |
31 | @comment POSIX.2 | |
32 | @defvr Macro _POSIX_C_SOURCE | |
33 | If you define this macro with a value of @code{1}, then the | |
34 | functionality from the POSIX.1 standard (IEEE Standard 1003.1) is made | |
35 | available. If you define this macro with a value of @code{2}, then both | |
36 | the functionality from the POSIX.1 standard and the functionality from | |
37 | the POSIX.2 standard (IEEE Standard 1003.2) are made available. This is | |
f65fd747 | 38 | in addition to the @w{ISO C} facilities. |
28f540f4 RM |
39 | @end defvr |
40 | ||
41 | @comment (none) | |
42 | @comment GNU | |
43 | @defvr Macro _BSD_SOURCE | |
44 | If you define this macro, functionality derived from 4.3 BSD Unix is | |
f65fd747 | 45 | included as well as the @w{ISO C}, POSIX.1, and POSIX.2 material. |
28f540f4 RM |
46 | |
47 | Some of the features derived from 4.3 BSD Unix conflict with the | |
48 | corresponding features specified by the POSIX.1 standard. If this | |
49 | macro is defined, the 4.3 BSD definitions take precedence over the | |
50 | POSIX definitions. | |
51 | ||
52 | Due to the nature of some of the conflicts between 4.3 BSD and POSIX.1, | |
53 | you need to use a special @dfn{BSD compatibility library} when linking | |
54 | programs compiled for BSD compatibility. This is because some functions | |
55 | must be defined in two different ways, one of them in the normal C | |
56 | library, and one of them in the compatibility library. If your program | |
57 | defines @code{_BSD_SOURCE}, you must give the option @samp{-lbsd-compat} | |
58 | to the compiler or linker when linking the program, to tell it to find | |
59 | functions in this special compatibility library before looking for them in | |
60 | the normal C library. | |
61 | @pindex -lbsd-compat | |
62 | @pindex bsd-compat | |
63 | @cindex BSD compatibility library. | |
64 | @end defvr | |
65 | ||
66 | @comment (none) | |
67 | @comment GNU | |
68 | @defvr Macro _SVID_SOURCE | |
69 | If you define this macro, functionality derived from SVID is | |
f65fd747 | 70 | included as well as the @w{ISO C}, POSIX.1, POSIX.2, and X/Open material. |
2c6fe0bd UD |
71 | @end defvr |
72 | ||
73 | @comment (none) | |
74 | @comment XOPEN | |
75 | @defvr Macro _XOPEN_SOURCE | |
76 | If you define these macro, functionality described in the X/Open | |
77 | Portability Guide is included. This is an superset of the POSIX.1 and | |
78 | POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and | |
79 | @code{_POSIX_C_SOURCE} get automatically be defined. | |
80 | ||
26761c28 | 81 | But as the great unifiction of all Unices there is also functionality |
2c6fe0bd UD |
82 | only available in BSD and SVID is included. |
83 | ||
84 | If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more | |
85 | functionality is available. The extra functions will make all functions | |
86 | available which are necessary for the X/Open Unix brand. | |
28f540f4 RM |
87 | @end defvr |
88 | ||
89 | @comment (none) | |
90 | @comment GNU | |
91 | @defvr Macro _GNU_SOURCE | |
f65fd747 | 92 | If you define this macro, everything is included: @w{ISO C}, POSIX.1, |
2c6fe0bd UD |
93 | POSIX.2, BSD, SVID, X/Open, and GNU extensions. In the cases where |
94 | POSIX.1 conflicts with BSD, the POSIX definitions take precedence. | |
28f540f4 RM |
95 | |
96 | If you want to get the full effect of @code{_GNU_SOURCE} but make the | |
97 | BSD definitions take precedence over the POSIX definitions, use this | |
98 | sequence of definitions: | |
99 | ||
100 | @smallexample | |
101 | #define _GNU_SOURCE | |
102 | #define _BSD_SOURCE | |
103 | #define _SVID_SOURCE | |
104 | @end smallexample | |
105 | ||
106 | Note that if you do this, you must link your program with the BSD | |
107 | compatibility library by passing the @samp{-lbsd-compat} option to the | |
108 | compiler or linker. @strong{Note:} If you forget to do this, you may | |
109 | get very strange errors at run time. | |
110 | @end defvr | |
111 | ||
ba1ffaa1 UD |
112 | @comment (none) |
113 | @comment GNU | |
26761c28 UD |
114 | @defvr Macro _REENTRANT |
115 | @defvrx Macro _THREAD_SAFE | |
116 | If you define one of these macros, reentrant versions of several functions get | |
2c6fe0bd | 117 | declared. Some of the functions are specified in POSIX.1c but many others |
ba1ffaa1 UD |
118 | are only available on a few other systems or are unique to GNU libc. |
119 | The problem is that the standardization of the thread safe C library | |
120 | interface still is behind. | |
121 | ||
122 | Unlike on some other systems no special version of the C library must be | |
123 | used for linking. There is only one version but while compiling this | |
124 | it must have been specified to compile as thread safe. | |
125 | @end defvr | |
126 | ||
28f540f4 | 127 | We recommend you use @code{_GNU_SOURCE} in new programs. If you don't |
2303f5fd UD |
128 | specify the @samp{-ansi} option to GCC and don't define any of these |
129 | macros explicitly, the effect is the same as defining | |
130 | @code{_POSIX_C_SOURCE} to 2 and @code{_POSIX_SOURCE}, | |
131 | @code{_SVID_SOURCE}, and @code{_BSD_SOURCE} to 1. | |
28f540f4 RM |
132 | |
133 | When you define a feature test macro to request a larger class of features, | |
134 | it is harmless to define in addition a feature test macro for a subset of | |
135 | those features. For example, if you define @code{_POSIX_C_SOURCE}, then | |
136 | defining @code{_POSIX_SOURCE} as well has no effect. Likewise, if you | |
137 | define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or | |
138 | @code{_POSIX_C_SOURCE} or @code{_SVID_SOURCE} as well has no effect. | |
139 | ||
140 | Note, however, that the features of @code{_BSD_SOURCE} are not a subset of | |
141 | any of the other feature test macros supported. This is because it defines | |
142 | BSD features that take precedence over the POSIX features that are | |
143 | requested by the other macros. For this reason, defining | |
144 | @code{_BSD_SOURCE} in addition to the other feature test macros does have | |
145 | an effect: it causes the BSD features to take priority over the conflicting | |
146 | POSIX features. |