fgetws implementation.
[kopensolaris-gnu/glibc.git] / NOTES
1 Feature Test Macros
2 -------------------
3
4    The exact set of features available when you compile a source file
5 is controlled by which "feature test macros" you define.
6
7    If you compile your programs using `gcc -ansi', you get only the
8 ISO C library features, unless you explicitly request additional
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
15 *must* come before any `#include' of a system header file.  It is best
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
21  - Macro: _POSIX_SOURCE
22      If you define this macro, then the functionality from the POSIX.1
23      standard (IEEE Standard 1003.1) is available, as well as all of the
24      ISO C facilities.
25
26  - Macro: _POSIX_C_SOURCE
27      If you define this macro with a value of `1', then the
28      functionality from the POSIX.1 standard (IEEE Standard 1003.1) is
29      made available.  If you define this macro with a value of `2',
30      then both the functionality from the POSIX.1 standard and the
31      functionality from the POSIX.2 standard (IEEE Standard 1003.2) are
32      made available.  This is in addition to the ISO C facilities.
33
34  - Macro: _BSD_SOURCE
35      If you define this macro, functionality derived from 4.3 BSD Unix
36      is included as well as the ISO C, POSIX.1, and POSIX.2 material.
37
38      Some of the features derived from 4.3 BSD Unix conflict with the
39      corresponding features specified by the POSIX.1 standard.  If this
40      macro is defined, the 4.3 BSD definitions take precedence over the
41      POSIX definitions.
42
43      Due to the nature of some of the conflicts between 4.3 BSD and
44      POSIX.1, you need to use a special "BSD compatibility library"
45      when linking programs compiled for BSD compatibility.  This is
46      because some functions must be defined in two different ways, one
47      of them in the normal C library, and one of them in the
48      compatibility library.  If your program defines `_BSD_SOURCE', you
49      must give the option `-lbsd-compat' to the compiler or linker when
50      linking the program, to tell it to find functions in this special
51      compatibility library before looking for them in the normal C
52      library.
53
54  - Macro: _SVID_SOURCE
55      If you define this macro, functionality derived from SVID is
56      included as well as the ISO C, POSIX.1, POSIX.2, and X/Open
57      material.
58
59  - Macro: _XOPEN_SOURCE
60  - Macro: _XOPEN_SOURCE_EXTENDED
61      If you define this macro, functionality described in the X/Open
62      Portability Guide is included.  This is a superset of the POSIX.1
63      and POSIX.2 functionality and in fact `_POSIX_SOURCE' and
64      `_POSIX_C_SOURCE' are automatically defined.
65
66      As the unification of all Unices, functionality only available in
67      BSD and SVID is also included.
68
69      If the macro `_XOPEN_SOURCE_EXTENDED' is also defined, even more
70      functionality is available.  The extra functions will make all
71      functions available which are necessary for the X/Open Unix brand.
72
73      If the macro `_XOPEN_SOURCE' has the value 500 this includes all
74      functionality described so far plus some new definitions from the
75      Single Unix specification, version 2.
76
77  - Macro: _LARGEFILE_SOURCE
78      If this macro is defined some extra functions are available which
79      rectify a few shortcomings in all previous standards.  More
80      concreten the functions `fseeko' and `ftello' are available.
81      Without these functions the difference between the ISO C interface
82      (`fseek', `ftell') and the low-level POSIX interface (`lseek')
83      would lead to problems.
84
85      This macro was introduced as part of the Large File Support
86      extension (LFS).
87
88  - Variable: Macro _LARGEFILE64_SOURCE
89      If you define this macro an additional set of function gets
90      available which enables to use on 32 bit systems to use files of
91      sizes beyond the usual limit of 2GB.  This interface is not
92      available if the system does not support files that large.  On
93      systems where the natural file size limit is greater than 2GB
94      (i.e., on 64 bit systems) the new functions are identical to the
95      replaced functions.
96
97      The new functionality is made available by a new set of types and
98      functions which replace existing.  The names of these new objects
99      contain `64' to indicate the intention, e.g., `off_t' vs.
100      `off64_t' and `fseeko' vs. `fseeko64'.
101
102      This macro was introduced as part of the Large File Support
103      extension (LFS).  It is a transition interface for the time 64 bit
104      offsets are not generally used (see `_FILE_OFFSET_BITS'.
105
106  - Variable: _FILE_OFFSET_BITS
107      This macro lets decide which file system interface shall be used,
108      one replacing the other.  While `_LARGEFILE64_SOURCE' makes the
109      64 bit interface available as an additional interface
110      `_FILE_OFFSET_BITS' allows to use the 64 bit interface to replace
111      the old interface.
112
113      If `_FILE_OFFSET_BITS' is undefined or if it is defined to the
114      value `32' nothing changes.  The 32 bit interface is used and
115      types like `off_t' have a size of 32 bits on 32 bit systems.
116
117      If the macro is defined to the value `64' the large file interface
118      replaces the old interface.  I.e., the functions are not made
119      available under different names as `_LARGEFILE64_SOURCE' does.
120      Instead the old function names now reference the new functions,
121      e.g., a call to `fseeko' now indeed calls `fseeko64'.
122
123      This macro should only be selected if the system provides
124      mechanisms for handling large files.  On 64 bit systems this macro
125      has no effect since the `*64' functions are identical to the
126      normal functions.
127
128      This macro was introduced as part of the Large File Support
129      extension (LFS).
130
131  - Macro: _GNU_SOURCE
132      If you define this macro, everything is included: ISO C, POSIX.1,
133      POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions.  In the cases
134      where POSIX.1 conflicts with BSD, the POSIX definitions take
135      precedence.
136
137      If you want to get the full effect of `_GNU_SOURCE' but make the
138      BSD definitions take precedence over the POSIX definitions, use
139      this sequence of definitions:
140
141           #define _GNU_SOURCE
142           #define _BSD_SOURCE
143           #define _SVID_SOURCE
144
145      Note that if you do this, you must link your program with the BSD
146      compatibility library by passing the `-lbsd-compat' option to the
147      compiler or linker.  *Note:* If you forget to do this, you may get
148      very strange errors at run time.
149
150  - Macro: _REENTRANT
151  - Macro: _THREAD_SAFE
152      If you define one of these macros, reentrant versions of several
153      functions get declared.  Some of the functions are specified in
154      POSIX.1c but many others are only available on a few other systems
155      or are unique to GNU libc.  The problem is that the
156      standardization of the thread safe C library interface still is
157      behind.
158
159      Unlike on some other systems no special version of the C library
160      must be used for linking.  There is only one version but while
161      compiling this it must have been specified to compile as thread
162      safe.
163
164    We recommend you use `_GNU_SOURCE' in new programs.  If you don't
165 specify the `-ansi' option to GCC and don't define any of these macros
166 explicitly, the effect is the same as defining `_POSIX_C_SOURCE' to 2
167 and `_POSIX_SOURCE', `_SVID_SOURCE', and `_BSD_SOURCE' to 1.
168
169    When you define a feature test macro to request a larger class of
170 features, it is harmless to define in addition a feature test macro for
171 a subset of those features.  For example, if you define
172 `_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect.
173 Likewise, if you define `_GNU_SOURCE', then defining either
174 `_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no
175 effect.
176
177    Note, however, that the features of `_BSD_SOURCE' are not a subset of
178 any of the other feature test macros supported.  This is because it
179 defines BSD features that take precedence over the POSIX features that
180 are requested by the other macros.  For this reason, defining
181 `_BSD_SOURCE' in addition to the other feature test macros does have an
182 effect: it causes the BSD features to take priority over the conflicting
183 POSIX features.
184