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