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