2.2 The Compilation Environment

2.2.1 POSIX.1 Symbols

Certain symbols in this volume of IEEE Std 1003.1-2001 are defined in headers (see the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Headers). Some of those headers could also define symbols other than those defined by IEEE Std 1003.1-2001, potentially conflicting with symbols used by the application. Also, IEEE Std 1003.1-2001 defines symbols that are not permitted by other standards to appear in those headers without some control on the visibility of those symbols.

Symbols called "feature test macros" are used to control the visibility of symbols that might be included in a header. Implementations, future versions of IEEE Std 1003.1-2001, and other standards may define additional feature test macros.

In the compilation of an application that #defines a feature test macro specified by IEEE Std 1003.1-2001, no header defined by IEEE Std 1003.1-2001 shall be included prior to the definition of the feature test macro. This restriction also applies to any implementation-provided header in which these feature test macros are used. If the definition of the macro does not precede the #include, the result is undefined.

Feature test macros shall begin with the underscore character ( '_' ).

The _POSIX_C_SOURCE Feature Test Macro

A POSIX-conforming application should ensure that the feature test macro _POSIX_C_SOURCE is defined before inclusion of any header.

When an application includes a header described by IEEE Std 1003.1-2001, and when this feature test macro is defined to have the value 200112L:

1. All symbols required by IEEE Std 1003.1-2001 to appear when the header is included shall be made visible.

2. Symbols that are explicitly permitted, but not required, by IEEE Std 1003.1-2001 to appear in that header (including those in reserved name spaces) may be made visible.

3. Additional symbols not required or explicitly permitted by IEEE Std 1003.1-2001 to be in that header shall not be made visible, except when enabled by another feature test macro.

Identifiers in IEEE Std 1003.1-2001 may only be undefined using the #undef directive as described in Use and Implementation of Functions or The Name Space. These #undef directives shall follow all #include directives of any header in IEEE Std 1003.1-2001.

Note:

The POSIX.1-1990 standard specified a macro called _POSIX_SOURCE. This has been superseded by _POSIX_C_SOURCE.

The _XOPEN_SOURCE Feature Test Macro

^[XSI] An XSI-conforming application should ensure that the feature test macro _XOPEN_SOURCE is defined with the value 600 before inclusion of any header. This is needed to enable the functionality described in The _POSIX_C_SOURCE Feature Test Macro and in addition to enable the XSI extension.

Since this volume of IEEE Std 1003.1-2001 is aligned with the ISO C standard, and since all functionality enabled by _POSIX_C_SOURCE set equal to 200112L is enabled by _XOPEN_SOURCE set equal to 600, there should be no need to define _POSIX_C_SOURCE if _XOPEN_SOURCE is so defined. Therefore, if _XOPEN_SOURCE is set equal to 600 and _POSIX_C_SOURCE is set equal to 200112L, the behavior is the same as if only _XOPEN_SOURCE is defined and set equal to 600. However, should _POSIX_C_SOURCE be set to a value greater than 200112L, the behavior is unspecified.

2.2.2 The Name Space

All identifiers in this volume of IEEE Std 1003.1-2001, except environ, are defined in at least one of the headers, as shown in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Headers. When ^[XSI]  _XOPEN_SOURCE or _POSIX_C_SOURCE is defined, each header defines or declares some identifiers, potentially conflicting with identifiers used by the application. The set of identifiers visible to the application consists of precisely those identifiers from the header pages of the included headers, as well as additional identifiers reserved for the implementation. In addition, some headers may make visible identifiers from other headers as indicated on the relevant header pages.

Implementations may also add members to a structure or union without controlling the visibility of those members with a feature test macro, as long as a user-defined macro with the same name cannot interfere with the correct interpretation of the program. The identifiers reserved for use by the implementation are described below:

1. Each identifier with external linkage described in the header section is reserved for use as an identifier with external linkage if the header is included.

2. Each macro described in the header section is reserved for any use if the header is included.

3. Each identifier with file scope described in the header section is reserved for use as an identifier with file scope in the same name space if the header is included.

The prefixes posix_, POSIX_, and _POSIX_ are reserved for use by IEEE Std 1003.1-2001 and other POSIX standards. Implementations may add symbols to the headers shown in the following table, provided the identifiers for those symbols either:

1. Begin with the corresponding reserved prefixes in the table, or

2. Have one of the corresponding complete names in the table, or

3. End in the string indicated as a reserved suffix in the table and do not use the reserved prefixes posix_, POSIX_, or _POSIX_, as long as the reserved suffix is in that part of the name considered significant by the implementation.

Symbols that use the reserved prefix _POSIX_ may be made visible by implementations in any header defined by IEEE Std 1003.1-2001.

Note:

The notation [A-Z] indicates any uppercase letter in the portable character set. The notation [a-z] indicates any lowercase letter in the portable character set. Commas and spaces in the lists of prefixes and complete names in the above table are not part of any prefix or complete name.

If any header in the following table is included, macros with the prefixes shown may be defined. After the last inclusion of a given header, an application may use identifiers with the corresponding prefixes for its own purpose, provided their use is preceded by a #undef of the corresponding macro.

The following are used to reserve complete names for the <stdint.h> header:

INT[0-9A-Za-z_]*_MIN
INT[0-9A-Za-z_]*_MAX
INT[0-9A-Za-z_]*_C
UINT[0-9A-Za-z_]*_MIN
UINT[0-9A-Za-z_]*_MAX
UINT[0-9A-Za-z_]*_C

Note:

The notation [0-9] indicates any digit. The notation [A-Z] indicates any uppercase letter in the portable character set. The notation [0-9a-z_] indicates any digit, any lowercase letter in the portable character set, or underscore.

The following reserved names are used as exact matches for <termios.h>:

The following identifiers are reserved regardless of the inclusion of headers:

1. With the exception of identifiers beginning with the prefix _POSIX_, all identifiers that begin with an underscore and either an uppercase letter or another underscore are always reserved for any use by the implementation.

2. All identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary identifier and tag name spaces.

3. All identifiers in the table below are reserved for use as identifiers with external linkage. Some of these identifiers do not appear in this volume of IEEE Std 1003.1-2001, but are reserved for future use by the ISO C standard.

   _Exit abort abs acos acosf acosh acoshf acoshl acosl acosl asctime asin asinf asinh asinhf asinhl asinl asinl atan atan2 atan2f atan2l atanf atanf atanh atanh atanhf atanhl atanl atanl atexit atof atoi atol atoll bsearch cabs cabsf cabsl cacos cacosf cacosh cacoshf cacoshl cacosl calloc carg cargf cargl casin casinf casinh casinhf casinhl casinl catan catanf catanh catanh catanhf catanhf catanhl catanhl catanl cbrt cbrtf cbrtl ccos ccosf ccosh

   ccoshf ccoshl ccosl ceil ceilf ceilf ceill ceill cerf cerfc cerfcf cerfcl cerff cerfl cexmp1 cexmp1f cexmp1l cexp cexp2 cexp2f cexp2l cexpf cexpl cimag cimagf cimagl clearerr clgamma clgammaf clgammal clock clog clog10 clog10f clog10l clog1p clog1pf clog1pl clog2 clog2f clog2l clogf clogl conj conjf conjl copysign copysignf copysignl cos cosf cosh coshf coshl cosl cpow cpowf cpowl cproj cprojf cprojl creal crealf creall csin csinf csinh csinhf csinhl csinl

   csqrt csqrtf csqrtl ctan ctanf ctanl ctgamma ctgammaf ctgammal ltime difftime div erfcf erfcl erff erfl errno exit exp exp2 exp2f exp2l expf expl expm1 expm1f expm1l fabs fabsf fabsl fclose fdim fdimf fdiml feclearexcept fegetenv fegetexceptflag fegetround feholdexcept feof feraiseexcept ferror fesetenv fesetexceptflag fesetround fetestexcept feupdateenv fflush fgetc fgetpos fgets fgetwc fgetws floor floorf floorl fma fmaf fmal fmax fmaxf fmaxl fmin fminf fminl fmod fmodf fmodl fopen fprintf

   fputc fputs fputwc fputws fread free freopen frexp frexpf frexpl fscanf fseek fsetpos ftell fwide fwprintf fwrite fwscanf getc getchar getenv gets getwc getwchar gmtime hypotf hypotl ilogb ilogbf ilogbl imaxabs imaxdiv is[a-z]* isblank iswblank labs ldexp ldexpf ldexpl ldiv ldiv lgammaf lgammal llabs llrint llrintf llrintl llround llroundf llroundl localeconv localtime log log10 log10f log10l log1p log1pf log1pl log2 log2f log2l logb logbf logbl logf logl longjmp lrint lrintf

   lrintl lround lroundf lroundl malloc mblen mbrlen mbrtowc mbsinit mbsrtowcs mbstowcs mbtowc mem[a-z]* mktime modf modff modfl nan nanf nanl nearbyint nearbyintf nearbyintl nextafterf nextafterl nexttoward nexttowardf nexttowardl perror pow powf powl printf putc putchar puts putwc putwchar qsort raise rand realloc remainderf remainderl remove remquo remquof remquol rename rewind rint rintf rintl round roundf roundl scalbln scalblnf scalblnl scalbn scalbnf scalbnl scanf setbuf setjmp setlocale setvbuf signal sin sinf

   sinh sinhf sinhl sinl sprintf sqrt sqrtf sqrtl srand sscanf str[a-z]* strtof strtoimax strtold strtoll strtoull strtoumax swprintf swscanf system tan tanf tanh tanhf tanhl tanl tgamma tgammaf tgammal time tmpfile tmpnam to[a-z]* trunc truncf truncl ungetc ungetwc va_end vfprintf vfscanf vfwprintf vfwscanf vprintf vscanf vsprintf vsscanf vswprintf vswscanf vwprintf vwscanf wcrtomb wcs[a-z]* wcstof wcstoimax wcstold wcstoll wcstoull wcstoumax wctob wctomb wctrans wctype wcwidth wmem[a-z]* wprintf wscanf

   Note:

   The notation [a-z] indicates any lowercase letter in the portable character set. The notation '*' indicates any combination of digits, letters in the portable character set, or underscore.

4. All functions and external identifiers defined in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 13, Headers are reserved for use as identifiers with external linkage.

5. All the identifiers defined in this volume of IEEE Std 1003.1-2001 that have external linkage are always reserved for use as identifiers with external linkage.

No other identifiers are reserved.

Applications shall not declare or define identifiers with the same name as an identifier reserved in the same context. Since macro names are replaced whenever found, independent of scope and name space, macro names matching any of the reserved identifier names shall not be defined by an application if any associated header is included.

Except that the effect of each inclusion of <assert.h> depends on the definition of NDEBUG, headers may be included in any order, and each may be included more than once in a given scope, with no difference in effect from that of being included only once.

If used, the application shall ensure that a header is included outside of any external declaration or definition, and it shall be first included before the first reference to any type or macro it defines, or to any function or object it declares. However, if an identifier is declared or defined in more than one header, the second and subsequent associated headers may be included after the initial reference to the identifier. Prior to the inclusion of a header, the application shall not define any macros with names lexically identical to symbols defined by that header.