| Feature Test Macros |
| ------------------- |
| |
| The exact set of features available when you compile a source file |
| is controlled by which "feature test macros" you define. |
| |
| If you compile your programs using `gcc -ansi', you get only the |
| ISO C library features, unless you explicitly request additional |
| features by defining one or more of the feature macros. *Note GNU CC |
| Command Options: (gcc.info)Invoking GCC, for more information about GCC |
| options. |
| |
| You should define these macros by using `#define' preprocessor |
| directives at the top of your source code files. These directives |
| *must* come before any `#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 `-D' option to GCC, but it's better |
| if you make the source files indicate their own meaning in a |
| self-contained way. |
| |
| - 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 |
| ISO C facilities. |
| |
| - Macro: _POSIX_C_SOURCE |
| If you define this macro with a value of `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 `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 ISO C facilities. |
| |
| - Macro: _BSD_SOURCE |
| If you define this macro, functionality derived from 4.3 BSD Unix |
| is included as well as the 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 |
| macro is defined, the 4.3 BSD definitions take precedence over the |
| POSIX definitions. |
| |
| Due to the nature of some of the conflicts between 4.3 BSD and |
| POSIX.1, you need to use a special "BSD compatibility library" |
| when linking programs compiled for BSD compatibility. This is |
| because some functions must be defined in two different ways, one |
| of them in the normal C library, and one of them in the |
| compatibility library. If your program defines `_BSD_SOURCE', you |
| must give the option `-lbsd-compat' to the compiler or linker when |
| linking the program, to tell it to find functions in this special |
| compatibility library before looking for them in the normal C |
| library. |
| |
| - Macro: _SVID_SOURCE |
| If you define this macro, functionality derived from SVID is |
| included as well as the ISO C, POSIX.1, POSIX.2, and X/Open |
| material. |
| |
| - Macro: _XOPEN_SOURCE |
| - 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 `_POSIX_SOURCE' and |
| `_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 `_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 `_XOPEN_SOURCE' has the value 500 this includes all |
| functionality described so far plus some new definitions from the |
| Single Unix specification, version 2. |
| |
| - Macro: _LARGEFILE_SOURCE |
| If this macro is defined some extra functions are available which |
| rectify a few shortcomings in all previous standards. More |
| concreten the functions `fseeko' and `ftello' are available. |
| Without these functions the difference between the ISO C interface |
| (`fseek', `ftell') and the low-level POSIX interface (`lseek') |
| would lead to problems. |
| |
| This macro was introduced as part of the Large File Support |
| extension (LFS). |
| |
| - Variable: Macro _LARGEFILE64_SOURCE |
| If you define this macro an additional set of function gets |
| available which enables to use on 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 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 existing. The names of these new objects |
| contain `64' to indicate the intention, e.g., `off_t' vs. |
| `off64_t' and `fseeko' vs. `fseeko64'. |
| |
| This macro was introduced as part of the Large File Support |
| extension (LFS). It is a transition interface for the time 64 bit |
| offsets are not generally used (see `_FILE_OFFSET_BITS'. |
| |
| - Variable: _FILE_OFFSET_BITS |
| This macro lets decide which file system interface shall be used, |
| one replacing the other. While `_LARGEFILE64_SOURCE' makes the |
| 64 bit interface available as an additional interface |
| `_FILE_OFFSET_BITS' allows to use the 64 bit interface to replace |
| the old interface. |
| |
| If `_FILE_OFFSET_BITS' is undefined or if it is defined to the |
| value `32' nothing changes. The 32 bit interface is used and |
| types like `off_t' have a size of 32 bits on 32 bit systems. |
| |
| If the macro is defined to the value `64' the large file interface |
| replaces the old interface. I.e., the functions are not made |
| available under different names as `_LARGEFILE64_SOURCE' does. |
| Instead the old function names now reference the new functions, |
| e.g., a call to `fseeko' now indeed calls `fseeko64'. |
| |
| This macro should only be selected if the system provides |
| mechanisms for handling large files. On 64 bit systems this macro |
| has no effect since the `*64' functions are identical to the |
| normal functions. |
| |
| This macro was introduced as part of the Large File Support |
| extension (LFS). |
| |
| - Macro: _GNU_SOURCE |
| If you define this macro, everything is included: ISO C, 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 `_GNU_SOURCE' but make the |
| BSD definitions take precedence over the POSIX definitions, use |
| this sequence of definitions: |
| |
| #define _GNU_SOURCE |
| #define _BSD_SOURCE |
| #define _SVID_SOURCE |
| |
| Note that if you do this, you must link your program with the BSD |
| compatibility library by passing the `-lbsd-compat' option to the |
| compiler or linker. *Note:* If you forget to do this, you may get |
| very strange errors at run time. |
| |
| - Macro: _REENTRANT |
| - 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. |
| |
| 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. |
| |
| We recommend you use `_GNU_SOURCE' in new programs. If you don't |
| specify the `-ansi' option to GCC and don't define any of these macros |
| explicitly, the effect is the same as defining `_POSIX_C_SOURCE' to 2 |
| and `_POSIX_SOURCE', `_SVID_SOURCE', and `_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 those features. For example, if you define |
| `_POSIX_C_SOURCE', then defining `_POSIX_SOURCE' as well has no effect. |
| Likewise, if you define `_GNU_SOURCE', then defining either |
| `_POSIX_SOURCE' or `_POSIX_C_SOURCE' or `_SVID_SOURCE' as well has no |
| effect. |
| |
| Note, however, that the features of `_BSD_SOURCE' are not a subset of |
| any of the other feature test macros supported. This is because it |
| defines BSD features that take precedence over the POSIX features that |
| are requested by the other macros. For this reason, defining |
| `_BSD_SOURCE' in addition to the other feature test macros does have an |
| effect: it causes the BSD features to take priority over the conflicting |
| POSIX features. |
| |