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