(argz_delete): Fix prototype.
[kopensolaris-gnu/glibc.git] / manual / creature.texi
index 6b4d42f..c825edd 100644 (file)
@@ -6,7 +6,7 @@ The exact set of features available when you compile a source file
 is controlled by which @dfn{feature test macros} you define.
 
 If you compile your programs using @samp{gcc -ansi}, you get only the
-ANSI C library features, unless you explicitly request additional
+@w{ISO C} library features, unless you explicitly request additional
 features by defining one or more of the feature macros.
 @xref{Invoking GCC,, GNU CC Command Options, gcc.info, The GNU CC Manual},
 for more information about GCC options.@refill
@@ -19,30 +19,64 @@ comments.  You could also use the @samp{-D} option to GCC, but it's
 better if you make the source files indicate their own meaning in a
 self-contained way.
 
+This system exists to allow the library to conform to multiple standards.
+Although the different standards are often described as supersets of each
+other, they are usually incompatible because larger standards require
+functions with names that smaller ones reserve to the user program.  This
+is not mere pedantry --- it has been a problem in practice.  For instance,
+some non-GNU programs define functions named @code{getline} that have
+nothing to do with this library's @code{getline}.  They would not be
+compilable if all features were enabled indiscriminately.
+
+This should not be used to verify that a program conforms to a limited
+standard.  It is insufficient for this purpose, as it will not protect you
+from including header files outside the standard, or relying on semantics
+undefined within the standard.
+
 @comment (none)
 @comment POSIX.1
 @defvr Macro _POSIX_SOURCE
 If you define this macro, then the functionality from the POSIX.1
 standard (IEEE Standard 1003.1) is available, as well as all of the
-ANSI C facilities.
+@w{ISO C} facilities.
+
+The state of @code{_POSIX_SOURCE} is irrelevant if you define the
+macro @code{_POSIX_C_SOURCE} to a positive integer.
 @end defvr
 
 @comment (none)
 @comment POSIX.2
 @defvr Macro _POSIX_C_SOURCE
-If you define this macro with a value of @code{1}, then the
-functionality from the POSIX.1 standard (IEEE Standard 1003.1) is made
-available.  If you define this macro with a value of @code{2}, then both
-the functionality from the POSIX.1 standard and the functionality from
-the POSIX.2 standard (IEEE Standard 1003.2) are made available.  This is
-in addition to the ANSI C facilities.
+Define this macro to a positive integer to control which POSIX
+functionality is made available.  The greater the value of this macro,
+the more functionality is made available.
+
+If you define this macro to a value greater than or equal to @code{1},
+then the functionality from the 1990 edition of the POSIX.1 standard
+(IEEE Standard 1003.1-1990) is made available.
+
+If you define this macro to a value greater than or equal to @code{2},
+then the functionality from the 1992 edition of the POSIX.2 standard
+(IEEE Standard 1003.2-1992) is made available.
+
+If you define this macro to a value greater than or equal to @code{199309L},
+then the functionality from the 1993 edition of the POSIX.1b standard
+(IEEE Standard 1003.1b-1993) is made available.
+
+Greater values for @code{_POSIX_C_SOURCE} will enable future extensions.
+The POSIX standards process will define these values as necessary, and
+the GNU C Library should support them some time after they become standardized.
+The 1996 edition of POSIX.1 (ISO/IEC 9945-1: 1996) states that
+if you define @code{_POSIX_C_SOURCE} to a value greater than
+or equal to @code{199506L}, then the functionality from the 1996
+edition is made available.
 @end defvr
 
 @comment (none)
 @comment GNU
 @defvr Macro _BSD_SOURCE
 If you define this macro, functionality derived from 4.3 BSD Unix is
-included as well as the ANSI C, POSIX.1, and POSIX.2 material.
+included as well as the @w{ISO C}, POSIX.1, and POSIX.2 material.
 
 Some of the features derived from 4.3 BSD Unix conflict with the
 corresponding features specified by the POSIX.1 standard.  If this
@@ -67,15 +101,109 @@ the normal C library.
 @comment GNU
 @defvr Macro _SVID_SOURCE
 If you define this macro, functionality derived from SVID is
-included as well as the ANSI C, POSIX.1, and POSIX.2 material.
+included as well as the @w{ISO C}, POSIX.1, POSIX.2, and X/Open material.
+@end defvr
+
+@comment (none)
+@comment X/Open
+@defvr Macro _XOPEN_SOURCE
+@comment (none)
+@comment X/Open
+@defvrx Macro _XOPEN_SOURCE_EXTENDED
+If you define this macro, functionality described in the X/Open
+Portability Guide is included.  This is a superset of the POSIX.1 and
+POSIX.2 functionality and in fact @code{_POSIX_SOURCE} and
+@code{_POSIX_C_SOURCE} are automatically defined.
+
+As the unification of all Unices, functionality only available in
+BSD and SVID is also included.
+
+If the macro @code{_XOPEN_SOURCE_EXTENDED} is also defined, even more
+functionality is available.  The extra functions will make all functions
+available which are necessary for the X/Open Unix brand.
+
+If the macro @code{_XOPEN_SOURCE} has the value @math{500} this includes
+all functionality described so far plus some new definitions from the
+Single Unix Specification, @w{version 2}.
+@end defvr
+
+@comment (NONE)
+@comment X/Open
+@defvr Macro _LARGEFILE_SOURCE
+If this macro is defined some extra functions are available which
+rectify a few shortcomings in all previous standards.  Specifically,
+the functions @code{fseeko} and @code{ftello} are available.  Without
+these functions the difference between the @w{ISO C} interface
+(@code{fseek}, @code{ftell}) and the low-level POSIX interface
+(@code{lseek}) would lead to problems.
+
+This macro was introduced as part of the Large File Support extension (LFS).
+@end defvr
+
+@comment (NONE)
+@comment X/Open
+@defvr Macro _LARGEFILE64_SOURCE
+If you define this macro an additional set of functions is made available
+which enables @w{32 bit} systems to use files of sizes beyond
+the usual limit of 2GB.  This interface is not available if the system
+does not support files that large.  On systems where the natural file
+size limit is greater than 2GB (i.e., on @w{64 bit} systems) the new
+functions are identical to the replaced functions.
+
+The new functionality is made available by a new set of types and
+functions which replace the existing ones.  The names of these new objects
+contain @code{64} to indicate the intention, e.g., @code{off_t}
+vs. @code{off64_t} and @code{fseeko} vs. @code{fseeko64}.
+
+This macro was introduced as part of the Large File Support extension
+(LFS).  It is a transition interface for the period when @w{64 bit}
+offsets are not generally used (see @code{_FILE_OFFSET_BITS}).
+@end defvr
+
+@comment (NONE)
+@comment X/Open
+@defvr Macro _FILE_OFFSET_BITS
+This macro determines which file system interface shall be used, one
+replacing the other.  Whereas @code{_LARGEFILE64_SOURCE} makes the @w{64
+bit} interface available as an additional interface,
+@code{_FILE_OFFSET_BITS} allows the @w{64 bit} interface to
+replace the old interface.
+
+If @code{_FILE_OFFSET_BITS} is undefined, or if it is defined to the
+value @code{32}, nothing changes.  The @w{32 bit} interface is used and
+types like @code{off_t} have a size of @w{32 bits} on @w{32 bit}
+systems.
+
+If the macro is defined to the value @code{64}, the large file interface
+replaces the old interface.  I.e., the functions are not made available
+under different names (as they are with @code{_LARGEFILE64_SOURCE}).
+Instead the old function names now reference the new functions, e.g., a
+call to @code{fseeko} now indeed calls @code{fseeko64}.
+
+This macro should only be selected if the system provides mechanisms for
+handling large files.  On @w{64 bit} systems this macro has no effect
+since the @code{*64} functions are identical to the normal functions.
+
+This macro was introduced as part of the Large File Support extension
+(LFS).
+@end defvr
+
+@comment (none)
+@comment GNU
+@defvr Macro _ISOC99_SOURCE
+Until the revised @w{ISO C} standard is widely adopted the new features
+are not automatically enabled.  The GNU libc nevertheless has a complete
+implementation of the new standard and to enable the new features the
+macro @code{_ISOC99_SOURCE} should be defined.
 @end defvr
 
 @comment (none)
 @comment GNU
 @defvr Macro _GNU_SOURCE
-If you define this macro, everything is included: ANSI C, POSIX.1,
-POSIX.2, BSD, SVID, and GNU extensions.  In the cases where POSIX.1
-conflicts with BSD, the POSIX definitions take precedence.
+If you define this macro, everything is included: @w{ISO C89}, @w{ISO
+C99}, POSIX.1, POSIX.2, BSD, SVID, X/Open, LFS, and GNU extensions.  In
+the cases where POSIX.1 conflicts with BSD, the POSIX definitions take
+precedence.
 
 If you want to get the full effect of @code{_GNU_SOURCE} but make the
 BSD definitions take precedence over the POSIX definitions, use this
@@ -95,21 +223,24 @@ get very strange errors at run time.
 
 @comment (none)
 @comment GNU
-@defvr Macro _REENTRANT,_THREAD_SAFE
-If you define this macro, reentrant versions of several functions get
-declared.  Some of the functions is specified in POSIX.1c but many others
+@defvr Macro _REENTRANT
+@defvrx Macro _THREAD_SAFE
+If you define one of these macros, reentrant versions of several functions get
+declared.  Some of the functions are specified in POSIX.1c but many others
 are only available on a few other systems or are unique to GNU libc.
-The problem is that the standardization of the thread safe C library
-interface still is behind.
+The problem is the delay in the standardization of the thread safe C library
+interface.
 
-Unlike on some other systems no special version of the C library must be
+Unlike on some other systems, no special version of the C library must be
 used for linking.  There is only one version but while compiling this
 it must have been specified to compile as thread safe.
 @end defvr
 
 We recommend you use @code{_GNU_SOURCE} in new programs.  If you don't
-specify the @samp{-ansi} option to GCC and don't define any of these macros
-explicitly, the effect is the same as defining @code{_GNU_SOURCE}.
+specify the @samp{-ansi} option to GCC and don't define any of these
+macros explicitly, the effect is the same as defining
+@code{_POSIX_C_SOURCE} to 2 and @code{_POSIX_SOURCE},
+@code{_SVID_SOURCE}, and @code{_BSD_SOURCE} to 1.
 
 When you define a feature test macro to request a larger class of features,
 it is harmless to define in addition a feature test macro for a subset of