diff options
Diffstat (limited to 'REORG.TODO/manual/creature.texi')
| -rw-r--r-- | REORG.TODO/manual/creature.texi | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/REORG.TODO/manual/creature.texi b/REORG.TODO/manual/creature.texi new file mode 100644 index 0000000000..23218bbac3 --- /dev/null +++ b/REORG.TODO/manual/creature.texi @@ -0,0 +1,249 @@ +@node Feature Test Macros +@subsection Feature Test Macros + +@cindex feature test macros +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 +@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 + +You should define these macros by using @samp{#define} preprocessor +directives at the top of your source code files. These directives +@emph{must} come before any @code{#include} of a system header file. It +is best to make them the very first thing in the file, preceded only by +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 +@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 +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 +@theglibc{} 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 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. @Theglibc{} 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 ISO +@defvr Macro __STDC_WANT_LIB_EXT2__ +If you define this macro to the value @code{1}, features from ISO/IEC +TR 24731-2:2010 (Dynamic Allocation Functions) are enabled. Only some +of the features from this TR are supported by @theglibc{}. +@end defvr + +@comment (none) +@comment ISO +@defvr Macro __STDC_WANT_IEC_60559_BFP_EXT__ +If you define this macro, features from ISO/IEC TS 18661-1:2014 +(Floating-point extensions for C: Binary floating-point arithmetic) +are enabled. Only some of the features from this TS are supported by +@theglibc{}. +@end defvr + +@comment (none) +@comment ISO +@defvr Macro __STDC_WANT_IEC_60559_FUNCS_EXT__ +If you define this macro, features from ISO/IEC TS 18661-4:2015 +(Floating-point extensions for C: Supplementary functions) are +enabled. Only some of the features from this TS are supported by +@theglibc{}. +@end defvr + +@comment (none) +@comment ISO +@defvr Macro __STDC_WANT_IEC_60559_TYPES_EXT__ +If you define this macro, features from ISO/IEC TS 18661-3:2015 +(Floating-point extensions for C: Interchange and extended types) are +enabled. Only some of the features from this TS are supported by +@theglibc{}. +@end defvr + +@comment (none) +@comment GNU +@defvr Macro _GNU_SOURCE +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. +@end defvr + +@comment (none) +@comment GNU +@defvr Macro _DEFAULT_SOURCE +If you define this macro, most features are included apart from +X/Open, LFS and GNU extensions: the effect is to enable features from +the 2008 edition of POSIX, as well as certain BSD and SVID features +without a separate feature test macro to control them. Defining this +macro, on its own and without using compiler options such as +@option{-ansi} or @option{-std=c99}, has the same effect as not +defining any feature test macros; defining it together with other +feature test macros, or when options such as @option{-ansi} are used, +enables those features even when the other options would otherwise +cause them to be disabled. +@end defvr + +@comment (none) +@comment GNU +@defvr Macro _REENTRANT +@defvrx Macro _THREAD_SAFE +These macros are obsolete. They have the same effect as defining +@code{_POSIX_C_SOURCE} with the value @code{199506L}. + +Some very old C libraries required one of these macros to be defined +for basic functionality (e.g.@: @code{getchar}) to be 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, or other conformance options +such as @option{-std=c99}, and don't define any of these macros +explicitly, the effect is the same as defining @code{_DEFAULT_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 +those features. For example, if you define @code{_POSIX_C_SOURCE}, then +defining @code{_POSIX_SOURCE} as well has no effect. Likewise, if you +define @code{_GNU_SOURCE}, then defining either @code{_POSIX_SOURCE} or +@code{_POSIX_C_SOURCE} as well has no effect. |