Sun Studio 12: C User's Guide

6.8 Standard Headers and Reserved Names

Early in the standardization process, the ISO Standards Committee chose to include library functions, macros, and header files as part of ISO C.

This section presents the various categories of reserved names and some rationale for their reservations. At the end is a set of rules to follow that can steer your programs clear of any reserved names.

6.8.1 Standard Headers

The standard headers are:

Table 6–2 Standard Headers


`assert.h`	`locale.h`	`stddef.h`
`ctype.h`	`math.h`	`stdio.h`
`errno.h`	`setjmp.h`	`stdlib.h`
`float.h`	`signal.h`	`string.h`
`limits.h`	`stdarg.h`	`time.h`

Most implementations provide more headers, but a strictly conforming 1990 ISO/IEC C program can only use these.

Other standards disagree slightly regarding the contents of some of these headers. For example, POSIX (IEEE 1003.1) specifies that fdopen is declared in stdio.h. To allow these two standards to coexist, POSIX requires the macro _POSIX_SOURCE to be #defined prior to the inclusion of any header to guarantee that these additional names exist. In its Portability Guide, X/Open has also used this macro scheme for its extensions. X/Open’s macro is _XOPEN_SOURCE.

ISO C requires the standard headers to be both self-sufficient and idempotent. No standard header needs any other header to be #included before or after it, and each standard header can be #included more than once without causing problems. The Standard also requires that its headers be #included only in safe contexts, so that the names used in the headers are guaranteed to remain unchanged.

6.8.2 Names Reserved for Implementation Use

The Standard places further restrictions on implementations regarding their libraries. In the past, most programmers learned not to use names like read and write for their own functions on UNIX Systems. ISO C requires that only names reserved by the Standard be introduced by references within the implementation.

Thus, the Standard reserves a subset of all possible names for implementations to use. This class of names consists of identifiers that begin with an underscore and continue with either another underscore or a capital letter. The class of names contains all names matching the following regular expression:

_[_A-Z][0-9_a-zA-Z]*

Strictly speaking, if your program uses such an identifier, its behavior is undefined. Thus, programs using _POSIX_SOURCE (or _XOPEN_SOURCE) have undefined behavior.

However, undefined behavior comes in different degrees. If, in a POSIX-conforming implementation you use _POSIX_SOURCE, you know that your program’s undefined behavior consists of certain additional names in certain headers, and your program still conforms to an accepted standard. This deliberate loophole in the ISO C standard allows implementations to conform to seemingly incompatible specifications. On the other hand, an implementation that does not conform to the POSIX standard is free to behave in any manner when encountering a name such as _POSIX_SOURCE.

The Standard also reserves all other names that begin with an underscore for use in header files as regular file scope identifiers and as tags for structures and unions, but not in local scopes. The common practice of having functions named _filbuf and _doprnt to implement hidden parts of the library is allowed.

6.8.3 Names Reserved for Expansion

In addition to all the names explicitly reserved, the 1990 ISO/IEC C standard also reserves (for implementations and future standards) names matching certain patterns:

Table 6–3 Names Reserved for Expansion


File	Reserved Name Pattern
`errno.h`	`E[0-9A-Z].*`
`ctype.h`	`(to\|is)[a-z].*`
`locale.h`	`LC_[A-Z].*`
`math.h`	current function names`[fl]`
`signal.h`	`(SIG\|SIG_)[A-Z].*`
`stdlib.h`	`str[a-z].*`
`string.h`	`(str\|mem\|wcs)[a-z].*`

In the above lists, names that begin with a capital letter are macros and are reserved only when the associated header is included. The rest of the names designate functions and cannot be used to name any global objects or functions.

6.8.4 Names Safe to Use

There are four simple rules you can follow to keep from colliding with any ISO C reserved names:

#include all system headers at the top of your source files (except possibly after a #define of _POSIX_SOURCE or _XOPEN_SOURCE, or both).
Do not define or declare any names that begin with an underscore.
Use an underscore or a capital letter somewhere within the first few characters of all file scope tags and regular names. Beware of the va_ prefix found in stdarg.h or varargs.h.
Use a digit or a non-capital letter somewhere within the first few characters of all macro names. Almost all names beginning with an E are reserved if errno.h is #included.

These rules are just a general guideline to follow, as most implementations will continue to add names to the standard headers by default.