Execution Environments

C programs run in one of two execution environments: hosted or freestanding. Most common programs run in a hosted environment; that is, under the control and with the support of an operating system. In a hosted environment, the full capabilities of the standard library are available. Furthermore, programs compiled for a hosted environment must define a function named main(), which is the first function invoked on program start.

A program designed for a freestanding environment runs without the support of an operating system. In a freestanding environment, the name and type of the first function invoked when a program starts is determined by the given implementation. Programs for a freestanding environment cannot use complex floating-point types, and may be limited to the following headers:

Specific implementations may also provide additional standard library resources.

Function and Macro Calls

All standard library functions have external linkage. You may use standard library functions without including the corresponding header by declaring them in your own code. However, if a standard function requires a type defined in the header, then you must include the header.

The standard library functions are not guaranteed to be reentrant—that is, two calls to a standard library function may not safely be in execution concurrently in one process. One reason for this rule is that several of the functions use and modify static or thread-local variables, for example.

As a result, you can’t generally call standard library functions in signal handling routines. Signals are asynchronous, which means that a program may receive a signal at any time, even while it’s executing a standard library function. If that happens, and the handler for that signal calls the same standard function, then the function must be reentrant. It is up to individual implementations to determine which functions are reentrant, or whether to provide a reentrant version of the whole standard library.

Most of the standard library functions—with a few explicitly specified exceptions—are thread-safe, meaning they can be safely executed by several threads “simultaneously.” In other words, the standard functions must be so implemented that any objects they use internally are not subject to data races when called in more than one thread. In particular, they must not use static objects without ensuring synchronization. However, you the programmer are responsible for coordinating different threads’ access to any objects referred to directly or indirectly by a function’s arguments.

Each stream has a corresponding lock which the functions in the I/O library use to obtain exclusive access to the stream before performing an operation. In this way, the standard library functions prevent data races when several threads access a given stream.

As the programmer, you are responsible for calling functions and function-like macros with valid arguments. Wrong arguments can cause severe runtime errors. Typical mistakes to avoid include the following:

• Argument values outside the domain of the function, as in the following call:

  double x = -1.0, y = sqrt(x);

• Pointer arguments that do not point to an object or a function, as in this function call with an uninitialized pointer argument:

  char *msg;  strcpy( msg, "error" );

• Arguments whose type does not match that expected by a function with a variable number of arguments. In the following example, the conversion specifier %f calls for a float pointer argument, but &x is a pointer to double:

  double x;    scanf( "%f", &x );

• Array address arguments that point to an array that isn’t large enough to accommodate data written by the function. Here is an example:

  char name[] = "Hi ";  strcat( name, "Alice" );

Macros in the standard library make full use of parentheses so that you can use them in expressions in the same way as individual identifiers. Furthermore, each function-like macro in the standard library uses its arguments only once.¹ This means that you can call these macros in the same way as ordinary functions, even using expressions with side effects as arguments. Here is an example:

int c = 'A';
while ( c <= 'Z' )  putchar( c++ );    // Output: 'ABC ... XYZ'

The functions in the standard library may be implemented both as macros and as functions. In such cases, the same header file contains both a function prototype and a macro definition for a given function name. As a result, each use of the function name after you include the header file invokes the macro. The following example calls the macro or function toupper() to convert a lowercase letter to uppercase:

#include <ctype.h>
/* ... */
  c = toupper(c);      // Invokes the macro toupper(), if there is one.

However, if you specifically want to call a function and not a macro with the same name, you can use the #undef directive to cancel the macro definition:

#include <ctype.h>
#undef toupper         // Remove any macro definition with this name.
/* ... */
  c = toupper(c)       // Calls the function toupper().

You can also call a function rather than a macro with the same name by setting the name in parentheses:

#include <ctype.h>
/* ... */
  c = (toupper)(c)     // Calls the function toupper().

Finally, you can omit the header containing the macro definition, and declare the function explicitly in your source file:

extern int toupper(int);
/* ... */
  c = toupper(c)       // Calls the function toupper().

Reserved Identifiers

When choosing identifiers to use in your programs, you must be aware that certain identifiers are reserved for the standard library. Reserved identifiers include the following:

• All identifiers that begin with an underscore followed by a second underscore or an uppercase letter are always reserved. Thus, you cannot use identifiers such as __x or _Max, even for local variables or labels.

• All other identifiers that begin with an underscore are reserved as identifiers with file scope. Thus, you cannot use an identifier such as _a_ as the name of a function or a global variable, although you can use it for a parameter, a local variable, or a label. The identifiers of structure or union members can also begin with an underscore, as long as the second character is not another underscore or an uppercase letter.

• Identifiers declared with external linkage in the standard headers are reserved as identifiers with external linkage. Such identifiers include function names, as well as the names of global variables such as errno. Although you cannot declare these identifiers with external linkage as names for your own functions or objects, you may use them for other purposes. For example, in a source file that does not include string.h, you may define a static function named strcpy().

• The identifiers of all macros defined in any header you include are reserved.

• Identifiers declared with file scope in the standard headers are reserved within their respective name spaces. Once you include a header in a source file, you cannot use any identifier that is declared with file scope in that header for another purpose in the same name space (see “Identifier Name Spaces”) or as a macro name.

Although some of the conditions listed here have “loopholes” that allow you to reuse identifiers in a certain name space or with static linkage, overloading identifiers can cause confusion, and it’s generally safest to avoid the identifiers declared in the standard headers completely. In the following sections, we also list identifiers that have been reserved for future extensions of the C standard. The last three rules in the previous list apply to such reserved identifiers as well.

Availability

Support for the bounds-checking functions is optional. They are available only in implementations that define the macro __STDC_LIB_EXT1__.

If these functions are provided, their declarations and the accompanying type and macro definitions are included in the same headers that provide the corresponding traditional functions. For example, the header stdio.h then contains the declaration of scanf_s() in addition to scanf(), and string.h contains the declaration of strcpy_s() alongside strcpy(). To make the declarations of the secure functions visible to the compiler, however, your program must define the macro __STDC_WANT_LIB_EXT1__ as equal to 1 before including the corresponding headers, for example, by using the lines:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>

To prevent name conflicts with functions defined in your program or in other libraries it uses, you can ensure that the secure functions are not visible by defining the macro __STDC_WANT_LIB_EXT1__ as equal to 0. If __STDC_WANT_LIB_EXT1__ is not defined before the program includes a standard header, the corresponding secure functions may or may not be available, depending on the given compiler.

Runtime Constraints

The parameter that specifies the size of an array in a bounds-checking function has the type rsize_t. This type is defined in the header stddef.h as equal to size_t. However, rsize_t places a special restriction on the value of a variable: a variable of the type rsize_t must not be assigned a value greater than that of the macro RSIZE_MAX. Passing an array length argument greater than RSIZE_MAX to a bounds-checking function causes an error. This constraint can detect errors that arise through the conversion of negative numbers to unsigned types, as such conversions result in very large positive numbers.

The secure functions perform other tests in addition to bounds-checking. For example, they test whether pointers passed as arguments are non-null. All the conditions that must be fulfilled for a function to execute successfully are called the function’s runtime constraints.

If a secure function’s runtime constraints are violated, the destination objects remain unchanged, and the function calls a runtime constraint handler, passing it a return value and an error message. The handler can end the program by calling abort(), or return to the secure function which called it. A program may replace the default runtime constraint handler with another standard handler or with a function of its own by calling the function set_constraint_handler_s(). For details, see the description of the function set_constraint_handler_s() in Chapter 18.

The return value of a secure function indicates whether an error has occurred. Many of the secure functions have a return value of the type errno_t. This type is defined in the header errno.h as int. These secure functions return the value 0 after a successful call, and a nonzero value if an error has occured.

assert.h

This header defines the function-like macro assert(), which tests whether the value of an expression is nonzero in the running program. If you define the macro NDEBUG before including assert.h , then calls to assert() have no effect.

In C11, the header assert.h defines the macro static_assert as a synonym for the keyword _Static_assert. A _Static_assert declaration tests a constant expression for a nonzero value at compile time (see “_Static_assert Declarations”).

complex.h

C99 supports arithmetic with complex numbers by introducing complex floating-point types and including appropriate functions in the math library. The header file complex.h contains the prototypes of the complex math functions and defines the related macros. For a brief description of complex numbers and their representation in C, see “Complex Floating-Point Types”.

Under the C11 standard, support for complex numbers is optional. The header complex.h is absent if the macro __STDC_NO_COMPLEX__ is defined.

The names of the mathematical functions for complex numbers all begin with the letter c. For example, csin() is the complex sine function, and cexp() the complex exponential function. You can find a complete list of these functions in “Mathematical Functions”. In addition, the following function names are reserved for future extensions:

cerf()    cerfc()    cexp2()    cexpm1()    clog10()    clog1p()
clog2()   clgamma()  ctgamma()

The same names with the suffixes f (for float _Complex) and l (for long double _Complex) are also reserved.

The header file complex.h defines the following macros:

complex

This is a synonym for the keyword _Complex.

_Complex_I

This macro represents an expression of type const float _Complex whose value is the imaginary unit, i.

I

This macro is a synonym for _Complex_I (or for _Imaginary_I, if defined), and likewise represents the imaginary unit, i.

A C11 implementation may also include types to represent pure imaginary numbers. If and only if a given C implementation includes such types, it defines the two following macros:

imaginary

This is a synonym for the keyword _Imaginary.

_Imaginary_I

This macro represents an expression of type const float _Imaginary whose value is the imaginary unit, i. If _Imaginary_I is defined, the macro I is defined as a synonym for it.

C11 also provides the function-like macros CMPLX, CMPXF, and CMPLXL to compose a complex number from its real and imaginary parts.

ctype.h

This header contains the declarations of functions to classify and convert single characters. These include the following functions, which are usually also implemented as macros:

isalnum()  isalpha()  isblank()  iscntrl()  isdigit()  isgraph()
islower()  isprint()  ispunct()  isspace()  isupper()  isxdigit()
tolower()  toupper()

These functions or macros take an argument of type int, whose value must be between 0 and 255, inclusive, or EOF. The macro EOF is defined in stdio.h. The classification of characters, and hence the behavior of these functions (except isdigit() and isxdigit()), is dependent on the current locale.

All names that begin with is or to followed by a lowercase letter are reserved for future extensions.

errno.h

The header errno.h defines the macro errno as representing a thread-local error variable of the type int. Various functions in the standard library set errno to a specified positive value to indicate the type of error encountered during execution. For each function that uses errno, its possible values are indicated in the function’s description in Chapter 18.

The identifier errno is not necessarily declared as a global variable. It may be a macro that represents a modifiable lvalue with the type int. For example, if _errno() is a function that returns a pointer to int, then errno could be defined as follows:

#define errno  (* _errno())

When the program starts, errno in the initial thread has the value zero. The initial value of errno in any other thread is undetermined. Because no standard function sets the value of errno to zero, a program that uses errno to detect errors should set the value of errno to zero before calling a standard library function.

The header errno.h also defines an appropriate macro constant for each possible value of errno. The names of these macros begin with E, and include at least these three:

EDOM

Domain error; the function is mathematically not defined for the given value of the argument.

EILSEQ

Illegal sequence. For example, a multibyte character conversion function may have encountered a sequence of bytes that cannot be interpreted as a multibyte character in the encoding used.

ERANGE

Range error; the function’s mathematical result is not representable by its return type.

All macro names that begin with E followed by a digit or an uppercase letter are reserved for future extensions.

C11 implementations that support the new bounds-checking, “secure” functions also define the type errno_t in the header errno.h as a synonym for int.

fenv.h

C99 introduced the floating-point environment, which provides system variables to allow programs to deal flexibly with floating-point exceptions and control modes. (See also “Mathematical Functions”.) The header fenv.h contains all the declarations that may be used in accessing the floating-point environment, although implementations are not required to support floating-point exceptions or control modes.

float.h

The header file float.h defines macros that describe the value range, the precision, and other properties of the types float, double, and long double.

inttypes.h

The header inttypes.h includes the header stdint.h, and contains extensions to it. The header stdint.h defines integer types with specified bit widths, including the types intmax_t and uintmax_t, which represent the widest integer types implemented. (See also “Integer Types Defined in Standard Headers”.)

PRIdN  PRIdLEASTN  PRIdFASTN  PRIdMAX  PRIdPTR

#include <inttypes.h>
int_fast32_t  i32Var;
/* ... */
  printf( "The value of i32Var, in hexadecimal notation: "
          "%10" PRIxFAST32 "\n", i32Var);

    SCNdN  SCNdLEASTN  SCNdFASTN  SCNdMAX  SCNdPTR

iso646.h

The header iso646.h defines the eleven macros listed in Table 16-2, which you can use as synonyms for C’s logical and bitwise operators.

limits.h

The header limits.h contains macros to represent the least and greatest representable value of each integer type. These macros are listed in Table 16-3. The numeric values in the table represent the minimum requirements of the C standard.

The range of the type char depends on whether char is signed or unsigned. If char is signed, then CHAR_MIN is equal to SCHAR_MIN and CHAR_MAX equal to SCHAR_MAX. If char is unsigned, then CHAR_MIN is zero and CHAR_MAX is equal to UCHAR_MAX.

The header limits.h also defines the following two macros:

CHAR_BIT

The number of bits in a byte, which must be at least 8.

MB_LEN_MAX

The maximum number of bytes in a multibyte character, which must be at least 1.

The value of the macro CHAR_BIT determines the value of UCHAR_MAX: UCHAR_MAX is equal to 2^CHAR_BIT − 1.

The value of MB_LEN_MAX is greater than or equal to the value of MB_CUR_MAX, which is defined in the header stdlib.h. MB_CUR_MAX represents the maximum number of bytes in a multibyte character in the current locale. More specifically, the value depends on the locale setting for the LC_CTYPE category (see the description of setlocale() in Chapter 18 for details). If the current locale uses a stateful multibyte encoding, then both MB_LEN_MAX and MB_CUR_MAX include the number of bytes necessary for a state-shift sequence before the actual multibyte character.

locale.h

The standard library supports the development of C programs that are able to adapt to local cultural conventions. For example, programs may use locale-specific character sets or formats for currency information.

The header locale.h declares two functions, the type struct lconv, the macro NULL for the null pointer constant, and macros whose names begin with LC_ for the locale information categories.

The function setlocale() allows you to query or set the current locale. The information that makes up the locale is divided into categories, which you can query and set individually. The following integer macros are defined to designate these categories:

LC_ALL        LC_COLLATE   LC_CTYPE
LC_MONETARY   LC_NUMERIC   LC_TIME

The function setlocale() takes one of these macros as its first argument, and operates on the corresponding locale category. The meanings of the macros are described under the setlocale() function in Chapter 18. Implementations may also define additional macros whose names start with LC_ followed by an uppercase letter.

The second function declared in locale.h is localeconv(), which supplies information about the conventions of the current locale by filling the members of a structure of the type struct lconv. localeconv() returns a pointer to the structure. The structure contains members to describe the local formatting of numerals, monetary amounts, and date and time information. For details, see the description of localeconv() in Chapter 18.

math.h

The header math.h declares the mathematical functions for real floating-point numbers, and the related macros and types.

The mathematical functions for integer types are declared in stdlib.h, and those for complex numbers in complex.h. In addition, the header tgmath.h defines the type-generic macros, which allow you to call mathematical functions by uniform names regardless of the arguments’ type. For a summary of the mathematical functions in the standard library, see “Mathematical Functions”.

    FP_ZERO  FP_NORMAL  FP_SUBNORMAL  FP_INFINITE  FP_NAN

setjmp.h

The header setjmp.h declares the function longjmp(), and defines the array type jmp_buf and the function-like macro setjmp().

Calling setjmp() saves the current execution environment, including at least the momentary register and stack values, in a variable whose type is jmp_buf. In this way, the setjmp() call bookmarks a point in the program, which you can then jump back to at any time by calling the companion function longjmp(). In effect, setjmp() and longjmp() allow you to program a nonlocal “goto.”

signal.h

The header signal.h declares the functions raise() and signal(), as well as related macros and the following integer type:

sig_atomic_t

You can use the type sig_atomic_t to define objects that are accessible in an atomic operation. Such objects are suitable for use in hardware interrupt signal handlers, for example. The value range of this type is described by the values of the macros SIG_ATOMIC_MIN and SIG_ATOMIC_MAX, which are defined in the header stdint.h.

A signal handler is a function that is automatically executed when the program receives a given signal from the operating environment. You can use the function signal() in your programs to install functions of your own as signal handlers.

Each type of signal that programs can receive is identified by a signal number. Accordingly, signal.h defines macros of type int to designate the signal types. The required signal type macros are:

The meanings of these signal types are described along with the signal() function in Chapter 18. Implementations may also define other signals. The names of the corresponding macros begin with SIG or SIG_, followed by an uppercase letter.

The first argument to the function signal() is a signal number. The second is the address of a signal handler function, or one of the following macros:

SIG_DFL, SIG_IGN

These macros are constant expressions whose values cannot be equal to the address of any declarable function. SIG_DFL installs the implementation’s default signal handler for the given signal type. If you call signal() with SIG_IGN as the second argument, the program ignores signals of the given type, if the implementation allows programs to ignore them.

SIG_ERR

This macro represents the value returned by the signal() function if an error occurs.

stdalign.h

The header stdalign.h is new in C11, and defines the following four macros:

alignas

This is a synonym for the specifier _Alignas. When an object is defined with the specifier _Alignas, it can have a stricter alignment than its type requires.

alignof

This is a synonym for the operator _Alignof, which obtains the alignment of a type.

__alignas_is_defined, __alignof_is_defined

These macros are equal to the integer constant 1.

For more information on the alignment of objects, see “The Alignment of Objects in Memory”.

stdarg.h

The header stdarg.h defines one type and four macros for use in accessing the optional arguments of functions that support them (see “Variable Numbers of Arguments”):

va_list

Functions with variable numbers of arguments use an object of the type va_list to access their optional arguments. Such an object is commonly called an argument pointer, as it serves as a reference to a list of optional arguments.

The following function-like macros operate on objects of the type va_list:

va_start()

Sets the argument pointer to the first optional argument in the list.

va_arg()

Returns the current argument and sets the argument pointer to the next one in the list.

va_copy()

Copies the va_list object in its current state.

va_end()

Cleans up after the use of a va_list object. A function with a variable number of arguments must contain a va_end() macro call corresponding to each invocation of va_start() or va_copy().

The macros va_copy() and va_end() may also be implemented as functions.

stdatomic.h

The header stdatomic.h is new in C11. It contains function declarations and definitions of various types and macros for atomic operations on data that is shared by several threads. For explanations and examples of atomic operations, see “Accessing Shared Data”.

Support for atomic operations is optional: C11 implementations that define the macro __STDC_NO_ATOMICS__ need not provide the header stdatomic.h.

The names of the functions declared begin with the prefix atomic_, as in atomic_store(). All function names that begin with the prefix atomic_ followed by a lowercase letter are reserved for future extensions. Type names that begin with atomic_ or memory_ followed by a lowercase letter are likewise reserved, as are macro names that begin with ATOMIC_ followed by an uppercase letter.

    memory_order_relaxed  memory_order_release  memory_order_acquire
    memory_order_consume  memory_order_acq_rel  memory_order_seq_cst

stdbool.h

The header stdbool.h defines the following four macros:

bool

A synonym for the type _Bool

true

The constant 1

false

The constant 0

__bool_true_false_are_defined

The constant 1

stddef.h

The header stddef.h defines three types and two macros for use in all kinds of programs. The three types are:

ptrdiff_t

A signed integer type that represents the difference between two pointers.

size_t

An unsigned integer type used to represent the result of sizeof operations; also defined in stdlib.h, wchar.h, stdio.h, and string.h.

wchar_t

An integer type that is wide enough to store any code in the largest extended character set that the implementation supports; also defined in stdlib.h and wchar.h.

Macros that specify the least and greatest representable values of these three types are defined in the header stdint.h .

In C11 implementations, one or two other types are also defined in stddef.h:

max_align_t

In C11, this is an object type with the largest possible alignment that the implementation supports in all contexts. It may be a type with an alignment of 8 or 16, for example.

rsize_t

This type is equivalent with size_t, and is defined only if the C11 implementation supports the secure standard functions with bounds-checking. If rsize_t is defined, then the macro RSIZE_MAX is also defined in the header stdint.h, typically with a value less than that of SIZE_MAX. In standard functions with a parameter of the type rsize_t, passing a value greater than RSIZE_MAX violates a runtime constraint.

The two macros defined in stddef.h are:

NULL

This macro represents a null pointer constant, which is an integer constant expression with the value 0, or such an expression cast as the type void *. The macro NULL is also defined in the headers stdio.h, stdlib.h, string.h, time.h, and wchar.h.

offsetof( structure_type, member )

This macro yields an integer constant with type size_t whose value is the number of bytes between the beginning of the structure and the beginning of its member member. The member must not be a bit-field.

stdint.h

The header stdint.h defines integer types with specific bit widths, and macros that indicate the value ranges of these and other types. For example, you can use the int64_t type, defined in stdint.h, to define a signed, 64-bit integer.

stdio.h

The header stdio.h contains the declarations of all the basic functions for input and output, as well as related macro and type definitions. The declarations for wide-character I/O functions—that is, for input and output of characters with the type wchar_t—are contained in the header file wchar.h (see also Chapter 13).

In addition to size_t, which is discussed in “stddef.h”, stdio.h defines the following two types:

FILE

An object of the type FILE contains all the information necessary for controlling an I/O stream. This information includes a pointer to the stream’s buffer, a file access position indicator, and flags to indicate error and end-of-file conditions.

fpos_t

Objects of this type, which is the return type of the fgetpos() function, are able to store all the information pertaining to a file access position. You can use the fsetpos() function to resume file processing at the position described by an fpos_t object.

The header stdio.h defines the macro NULL (described in “stddef.h”) as well as the following 12 macros, all of which represent integer constant expressions:

_IOFBF, _IOLBF, _IONBF

These constants are used as arguments to the setvbuf() function, and specify I/O buffering modes. The names stand for “fully buffered,” “line buffered,” and “not buffered.”

BUFSIZ

This is the size of the buffer activated by the setbuf() function, in bytes.

EOF

“End of file.” A negative value (usually -1) with type int. Various functions return the constant EOF to indicate an attempt to read at the end of a file, or to indicate an error.

FILENAME_MAX

This constant indicates how big a char array must be to store the longest filename supported by the fopen() function.

FOPEN_MAX

Programs are allowed to have at least this number of files open simultaneously.

L_tmpnam

This constant indicates how big a char array must be to store a filename generated by the tmpnam() function.

SEEK_SET, SEEK_CUR, SEEK_END

These constants are used as the third argument to the fseek() function.

TMP_MAX

The maximum number of unique filenames that the tmpnam() function can generate. This number is at least 25.

C11 implementations that support the new bounds-checking, “secure” functions also define the following macros:

L_tmpnam_s, TMP_MAX_S

The meanings of these macros in the context of the function tmpnam_s() are analogous to those of the macros L_tmpnam and TMP_MAX, described in the preceding list, for the function tmpnam().

The header stdio.h also declares three objects:

stdin, stdout, stderr

These are the standard I/O streams. They are pointers to the FILE objects associated with the “standard input,” “standard output,” and “standard error output” streams.

stdlib.h

The header stdlib.h declares general utility functions for the following purposes:

• Conversion of numeral strings into binary numeric values

• Random number generation

• Memory management

• Communication with the operating system

• Searching and sorting

• Integer arithmetic

• Conversion of multibyte characters to wide characters and vice versa

stdlib.h also defines the types size_t and wchar_t, which are described in “stddef.h”, as well as the following three types:

div_t, ldiv_t, lldiv_t

These are structure types used to hold the results of the integer division functions div(), ldiv(), and lldiv(). These types are structures of two members, quot and rem, which have the type int, long, or long long.

In C11 implementations that support the bounds-checking, “secure” functions, the header stdlib.h also declares the types errno_t (see “errno.h”), and rsize_t (see “stddef.h”), and the following type:

constraint_handler_t

This is the function-pointer type of the constraint handler argument passed to the function set_constraint_handler_s(). The last handler function passed in this way to the set_constraint_handler_s() function is called when a runtime constraint is violated during a call to a “secure” function.

The header stdlib.h defines the macro NULL (see “stddef.h”) as well as the following four macros:

EXIT_FAILURE, EXIT_SUCCESS

Integer constants that you can pass as arguments to the functions exit() and _Exit() to report your program’s exit status to the operating environment.

MB_CUR_MAX

A nonzero integer expression with the type size_t. This is the maximum number of bytes in a multibyte character under the current locale setting for the locale category LC_CTYPE. This value must be less than or equal to MB_LEN_MAX, defined in limits.h.

RAND_MAX

An integer constant that indicates the greatest possible value that can be returned by the function rand().

stdnoreturn.h

The header stdnoreturn.h is new in C11 and defines only one macro, noreturn, as a synonym for the keyword _Noreturn.

string.h

The header string.h declares the string manipulation functions, along with other functions that operate on byte arrays. The names of these functions begin with str, as in strcpy(), for example, or with mem, as in memcpy(). Function names beginning with str, mem, or wcs followed by a lowercase letter are reserved for future extensions.

The header string.h also defines the type size_t and the macro NULL, described in “stddef.h”.

tgmath.h

The header tgmath.h includes the headers math.h and complex.h, and defines the type-generic macros. These macros allow you to call different variants of mathematical functions by a uniform name, regardless of the arguments’ type.

The mathematical functions in the standard library are defined with parameters of specific real or complex floating-point types. Their names indicate types other than double by the prefix c for _Complex, or by the suffixes f for float and l for long double. The type-generic macros are overloaded names for these functions that you can use with arguments of any arithmetic type. These macros detect the arguments’ type and call the appropriate math function.

The header tgmath.h defines type-generic macros for all the mathematical functions with floating-point parameters except modf(), modff(), and modfl(). If a given function is defined for both real and complex or only for real floating-point types, then the corresponding type-generic macro has the same name as the function version for arguments of the type double—that is, the base name of the function with no c prefix and no f or l suffix. For an example, assume the following declarations:

#include <tgmath.h>
float  f = 0.5F;
double d = 1.5;
double _Complex z1 = -1;
long double _Complex z2 = I;

Each of the macro calls in Table 16-8 then expands to the function call shown in the right column.

Arguments with integer types are automatically converted to double. If you use arguments of different types in invoking a type-generic macro with two parameters, such as pow(), the macro calls the function version for the argument type with the higher rank (see “Hierarchy of Types”). If any argument has a complex floating-point type, the macro calls the function for complex numbers.

Several functions are defined only for complex floating-point types. The type-generic macros for these functions have names that start with c, but with no f or l suffix:

carg()  cimag()  conj()  cproj()  creal()

If you invoke one of these macros with a real argument, it calls the function for the complex type that corresponds to the argument’s real floating-point type.

threads.h

The header threads.h, which was introduced in C11, declares the functions for multithreading support, and defines the accompanying types and macros. The header threads.h also includes the header time.h. For details and examples on multithreaded programming using C11 features, see Chapter 14.

Multithreading support is optional in C11: implementations that define the macro __STDC_NO_THREADS__ need not provide the header threads.h.

The functions and types defined in threads.h are related to threads, mutex objects, condition variables and thread-specific storage. Accordingly, the names of the functions and types begin with one of the prefixes thrd_, mtx_, cnd_ and tss_. Other names beginning with any of these prefixes, followed by a lowercase letter, are reserved for future extensions.

time.h

The header time.h declares the standard functions, macros, and types for manipulating date and time information (by the Gregorian calendar). These functions are listed in “Date and Time”.

The types declared in time.h are size_t (see stddef.h in this chapter) and the following three types:

clock_t

This is the arithmetic type returned by the function clock() (usually defined as unsigned long).

time_t

This is an arithmetic type returned by the functions timer() and mktime() (usually defined as long).

struct tm

The members of this structure represent a date or a time, broken down into seconds, minutes, hours, the day of the month, and so on. The functions gmtime() and localtime() return a pointer to struct tm. The structure’s members are described under the gmtime() function in Chapter 18.

The header time.h defines the macro NULL (see stddef.h) and the following macro:

CLOCKS_PER_SEC

This is a constant expression with the type clock_t. You can divide the return value of the clock() function by CLOCKS_PER_SEC to obtain your program’s CPU use in seconds.

uchar.h

In C11, the new header uchar.h declares types and functions for processing Unicode characters. The types declared are size_t (see “stddef.h”), mbstate_t (see “wchar.h”), and the following two new types:

char16_t

An unsigned integer type for 16-bit characters. This type is the same as uint_least16_t. Implementations that define the macro __STDC_UTF_16__ use UTF-16 encoding for characters of the type char16_t. The macro is not defined if a different encoding is used.

char32_t

An unsigned integer type for 32-bit characters. This type is the same as uint_least32_t. Implementations that define the macro __STDC_UTF_32__ use UTF-32 encoding for characters of the type char32_t. The macro is not defined if a different encoding is used.

The types uint_least16_t and uint_least32_t are described in “stdint.h”. The header uchar.h declares the following four functions for converting 16-bit or 32-bit Unicode characters to multibyte characters and vice versa: mbrtoc16(), c16rtomb(), mbrtoc32(), and c32rtomb().

Functions and types for processing wide characters of the type wchar_t are declared in the header wchar.h.

wchar.h

The headers stdio.h, stdlib.h, string.h, and time.h all declare functions for processing byte-character strings—that is, strings of characters with the type char. The header wchar.h declares similar functions for wide strings: strings of wide characters, which have the type wchar_t. The names of these functions generally contain an additional w, as in wprintf(), for example, or start with wcs instead of str, as in wcscpy(), which is the name of the wide-string version of the strcpy() function.

Furthermore, the header wchar.h declares more functions for converting multibyte characters to wide characters and vice versa, in addition to those declared in stdlib.h. wchar.h declares functions for the following kinds of purposes:

• Wide and multibyte character I/O

• Conversion of wide-string numerals

• Copying, concatenating, and comparing wide strings and wide-character arrays

• Formatting date and time information in wide strings

• Conversion of multibyte characters to wide characters and vice versa

The types defined in wchar.h are size_t and wchar_t (explained in “stddef.h”); struct tm (see time.h); and the following two types:

mbstate_t

Objects of this type store the parsing state information involved in the conversion of a multibyte string to a wide-character string, or vice versa.

wint_t

An integer type whose bit width is at least that of int. wint_t must be wide enough to represent the value range of wchar_t and the value of the macro WEOF. The types wint_t and wchar_t may be identical.

The header wchar.h defines the macro NULL (see “stddef.h”), the macros WCHAR_MIN and WCHAR_MAX (see “stdint.h”), and the following macro:

WEOF

The macro WEOF has the type wint_t and a value that is distinct from all the character codes in the extended character set. Unlike EOF, its value may be positive. Various functions return the constant WEOF to indicate an attempt to read at the end of a file, or to indicate an error.

wctype.h

The header wctype.h declares functions to classify and convert wide characters. These functions are analogous to those for byte characters declared in the header ctype.h. In addition, wctype.h declares extensible wide-character classification and conversion functions.

The types defined in wctype.h are wint_t (described in “wchar.h”) and the following two types:

wctrans_t

This is a scalar type to represent locale-specific mapping rules. You can obtain a value of this type by calling the wctrans() function, and use it as an argument to the function towctrans() to perform a locale-specific wide-character conversion.

wctype_t

This is a scalar type to represent locale-specific character categories. You can obtain a value of this type by calling the wctype() function, and pass it as an argument to the function iswctype() to determine whether a given wide character belongs to the given category.

The header wctype.h also defines the macro WEOF, described in “wchar.h”.