Previous Page
Next Page

15.2. Contents of the Standard Headers

The following subsections list the standard headers in alphabetical order, with brief descriptions of their contents , including all the types and macros defined in them.

The standard functions are described in the next two chapters: Chapter 16 summarizes the functions that the standard library provides each area of applicationthe mathematical functions, string manipulation functions, functions for time and date operations, and so on. Chapter 17 then provides a detailed description of each function individually, in alphabetical order, with examples illustrating their use.

15.2.1. assert.h

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

15.2.2. 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 (C99)" in Chapter 2.

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 Chapter 16. 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 (float _Complex) and l (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, and likewise represents the imaginary unit.

15.2.3. 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.

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

15.2.4. errno.h

This header declares the identifier errno for use as a status variable with type int. Various functions in the standard library set errno to a value indicating the type of error encountered during execution. In the function descriptions in Chapter 17, the possible values of errno are listed for each such function.

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( ))

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.

15.2.5. 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" in Chapter 16.) 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.

15.2.5.1. Macro and type definitions for the floating-point environment

The header fenv.h contains the following definitions to manipulate the floating-point environment:


fenv_t

A type capable of representing the floating-point environment as a whole.


FE_DFL_ENV

An object of the type const fenv_t *; points to the default floating-point environment, which is in effect when the program starts.

15.2.5.2. Macro and type definitions for floating-point exceptions

Implementations that support floating-point exceptions also define an integer macro corresponding to the status flag for each kind of exception that can occur. Standard names for these macros are:


FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW, FE_UNDERFLOW

These macros allow you to select one or more kinds of exceptions when accessing the status flags. You can also combine several such macros using the bitwise OR operator (|) to obtain a value that represents several kinds of exceptions.


FE_ALL_EXCEPT

This macro represents the bitwise OR of all the exception macros defined in the given implementation.

If a given implementation does not support one or more of the exceptions indicated by these macros, then the corresponding macro is not defined. Furthermore, implementations may also define other exception macros, with names that begin with FE_ followed by an uppercase letter.

In addition to the macros listed previously, implementations that support floating-point exceptions also define a type for the floating-point exception status flags:


fexcept_t

This type represents all of the floating-point exception status flags, including all the information that the given implementation provides about exceptions. Such information may include the address of the instruction that raised the exception, for example. This type is used by the functions fegetexceptflag( ) and fesetexceptflag( ).

15.2.5.3. Macro definitions for rounding modes

Implementations may allow programs to query or set the way floating-point results are rounded. If so, the header fenv.h defines the following macros as distinct integer constants:

FE_DOWNWARD, FE_TONEAREST, FE_TOWARDZERO, FE_UPWARD

A given implementation might not define all of these macros if it does not support the corresponding rounding direction, and might also define macro names for other rounding modes that it does support. The function fegetround( ) returns the current rounding modethat is, the value of the corresponding macro nameand fesetround( ) sets the rounding mode as specified by its argument.

15.2.6. 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.

15.2.6.1. Normalized representation of floating-point numbers

The values of the macros in float.h refer to the following normalized representation of a floating-point number x:

x = s x 0.d1d2 ... dp x be

The symbols in this representation have the following meanings and conditions:


s

The sign of x; s = 1 or s = -1


di

A base b digit in the significand (also called the mantissa ) of x (0.d1d2...dp in the general representation); d1 > 0 if x 0


p

The number of digits in the significand (or to be more precise, in the fraction part)


b

The base of the exponent; b > 1


e

The integer exponent; emin e emax

The floating-point types may also be able to represent other values besides normalized floating-point numbers, such as the following kinds of values:

  • Subnormal floating-point numbers, or those for which x 0, e = emin, and d1 = 0.

  • Non-normalized floating-point numbers, for which x 0, e > emin, and d1 = 0.

  • Infinities; that is, values that represent + or - .

  • NaNs, or values that do not represent valid floating-point numbers. NaN stands for "not a number."

NaNs can be either quiet or signaling NaNs. When a signaling NaN occurs in the evaluation of an arithmetic expression, it sets the exception flag FE_INVALID in the floating-point environment. Quiet NaNs do not set the exception flag.

15.2.6.2. Rounding mode and evaluation method

The following two macros defined in the header float.h provide details about how floating-point arithmetic is performed:


FLT_ROUNDS

This macro represents the currently active rounding direction, and is the only macro defined in float.h whose value can change during runtime. It can have the following values:

-1

Undetermined

0

Toward zero

1

Toward the nearest representable value

2

Toward the next greater value

3

Toward the next smaller value

Other values may stand for implementation-defined rounding modes. If the implementation supports different rounding modes, you can change the active rounding mode by calling the function fesetround( ).


FLT_EVAL_METHOD

The macro FLT_EVAL_METHOD has one of several possible values, but does not change during the program's runtime. This macro indicates the floating-point format used internally for operations on floating-point numbers. The internal format may have greater precision and a broader value range than the operands' type. The possible values of FLT_EVAL_METHOD have the following meanings:

-1

Undetermined.

0

Arithmetic operations are performed with the precision of the operands' type.

1

Operations on float or double values are executed in double precision, and operations on long double are executed in long double precision.

2

All operations are performed internally in long double precision.

15.2.6.3. Precision and value range

For a given base, the precision with which numbers are represented is determined by the number of digits in the significand, and the value range is indicated by the least and greatest values of the exponent. These values are provided, for each real floating-point type, by the following macros. The macro names with the prefix FLT_ represent characteristics of the type float; those with the prefix DBL_ refer to double; and those with LDBL_ refer to long double. The value of FLT_RADIX applies to all three floating-point types.


FLT_RADIX

The radix or base (b) of the exponential representation of floating point numbers; usually 2


FLT_MANT_DIG, DBL_MANT_DIG, LDBL_MANT_DIG

The number of digits in the significand or mantissa (p)


FLT_MIN_EXP, DBL_MIN_EXP, LDBL_MIN_EXP

The smallest negative exponent to the base FLT_RADIX (emin)


FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP

The largest positive exponent to the base FLT_RADIX (emax)

In practice, it is useful to have the precision and the value range of a floating-point type in decimal notation. Macros for these characteristics are listed in Table 15-1. The values in the second column represent the C standard's minimum requirements. The values in the third column are the requirements of the IEC 60559 standard for floating-point numbers with single and double precision. In most C implementations, the types float and double have these IEC 60559 characteristics.

Table 15-1. Macros for the range and precision of floating-point types in decimal notation

Macro

ISO 9899

IEC 60559

Meaning

FLT_DIG

DBL_DIG

LDBL_DIG

6

10

10

6

15

The precision as a number of decimal digits. A decimal floating-point number of this many digits, stored in binary representation, always yields the same value to this many digits when converted back to decimal notation.

DECIMAL_DIG

10

17

The number of decimal digits necessary to represent any number of the largest floating-point type supported so that it can be converted to decimal notation and back to binary representation without its value changing.

FLT_MIN_10_EXP

DBL_MIN_10_EXP

LDBL_MIN_10_EXP

-37

-37

-37

-37

-307

The smallest negative exponent to base 10, n, such that 10n is within the positive range of the type.

FLT_MAX_10_EXP

DBL_MAX_10_EXP

LDBL_MAX_10_EXP

+37

+37

+37

+38

+308

The greatest exponent to base 10, n, such that 10n is within the range of the type.

FLT_MIN

DBL_MIN

LDBL_MIN

1E-37

1E-37

1E-37

1.17549435E-38F

2.2250738585072014E-308

The smallest representable positive floating-point number.

FLT_MAX

DBL_MAX

LDBL_MAX

1E+37

1E+37

1E+37

3.40282347E+38F

1.7976931348623157E+308

The greatest representable finite floating-point number.

FLT_EPSILON

DBL_EPSILON

LDBL_EPSILON

1E-5

1E-9

1E-9

1.19209290E-07F

2.2204460492503131E-16

The positive difference between 1 and the smallest representable number greater than 1.

 


15.2.7. 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 with Exact Width" in Chapter 2.)

15.2.7.1. Types

The header inttypes.h defines the following structure type:


imaxdiv_t

This is a structure type of two members named quot and rem, whose type is intmax_t. The function imaxdiv( ) divides one number of type intmax_t by another, and stores the quotient and remainder in an object of type struct imaxdiv_t.

15.2.7.2. Functions

In addition to imaxdiv( ), the header inttypes.h also declares the function imaxabs( ), which returns the absolute value of an integer of the type intmax_t, and four functions to convert strings into integers with the type intmax_t or uintmax_t.

15.2.7.3. Macros

Furthermore, inttypes.h defines macros for string literals that you can use as type specifiers in format string arguments to the printf and scanf functions. The header contains macros to specify each of the types defined in stdint.h. (In C++ implementations, these macros are defined conditionally: if you want the type specifiers to be defined, you must make sure that the macro _ _STDC_FORMAT_MACROS is defined before you include inttypes.h.)

The names of the type specifier macros for the printf family of functions begin with the prefix PRI, followed by a conversion specifier (d, i, o, x, or X) and a sequence of uppercase letters that refers to a type name. For example, the macro names with the conversion specifier d are:

     PRIdN  PRIdLEASTN  PRIdFASTN  PRIdMAX  PRIdPTR

The letter N at the end of the first three macro names listed here is a placeholder for a decimal number indicating the bit width of a given type. Commonly implemented values are 8, 16, 32, and 64.

Other PRI... macro names are analogous to the five just listed, but have different conversion specifiers in place of the letter d, such as i, o, x, or X. The following example uses a variable with the type int_fast32_t:

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

The preprocessor concatenates the string literals "%10" and PRIxFAST32 to form the full conversion specification. The resulting output of i32Var has a field width of 10 characters.

The names of the conversion specifier macros for the scanf family of functions begins with the prefix SCN. The remaining characters are the same as the corresponding PRI... macros, except that there is no conversion specifier X for scanf( ). For example, the macro names with the conversion specifier d are:

    SCNdN  SCNdLEASTN  SCNdFASTN  SCNdMAX  SCNdPTR

Again, the letter N at the end of the first three macro names as listed here is a placeholder for a decimal number indicating the bit width of a given type. Commonly implemented values are 8, 16, 32, and 64.

15.2.8. iso646.h

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

Table 15-2. ISO 646 operator names

Macro

Meaning

and

&&

or

||

not

!

bitand

&

bitor

|

xor

^

compl

~

and_eq

&=

or_eq

|=

xor_eq

^=

not_eq

!=


15.2.9. 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 15-3. The numeric values in the table represent the minimum requirements of the C standard.

Table 15-3. Value ranges of the integer types

Type

Minimum

Maximum

Maximum value of the unsigned type

char

CHAR_MIN

CHAR_MAX

UCHAR_MAX

28 - 1

signed char

SCHAR_MIN

-(27 - 1)

SCHAR_MAX

27 - 1

 

short

SHRT_MIN

-(215 - 1)

SHRT_MAX

215 - 1

USHRT_MAX

216 - 1

int

INT_MIN

-(215 - 1)

INT_MAX

215 - 1

UINT_MAX

216 - 1

long

LONG_MIN

-(231 - 1)

LONG_MAX

231 - 1

ULONG_MAX

232 - 1

long long

LLONG_MIN

-(263 - 1)

LLONG_MAX

263 - 1

ULLONG_MAX

264 - 1


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 2CHAR_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 17 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.

15.2.10. 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 17. Implementations may also define additional macros whose names start with LC_ followed by an uppercase letter.

The second function defined 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 17.

15.2.11. 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" in Chapter 16.

15.2.11.1. The types float_t and double_t

The header math.h defines the two types float_t and double_t. These types represent the floating-point precision used internally by the given implementation in evaluating arithmetic expressions of the types float and double. (If you use operands of the type float_t or double_t in your programs, they will not need to be converted before arithmetic operations, as float and double may.) The value of the macro FLT_EVAL_METHOD, defined in the header float.h, indicates which basic types correspond to float_t and double_t. The possible values of FLT_EVAL_METHOD are explained in Table 15-4.

Table 15-4. The types float_t and double_t

FLT_EVAL_METHOD

float_t

double_t

0

float

double

1

double

double

2

long double

long double


Any other value of FLT_EVAL_METHOD indicates that the evaluation of floating-point expressions is implementation-defined.

15.2.11.2. Classification macros

In addition to normalized floating-point numbers, the floating-point types can also represent other values, such as infinities and NaNs (see "Normalized representation of floating-point numbers" in the description of float.h in this chapter). C99 specifies five classes of floating-point values, and defines an integer macro to designate each of these categories. The five macros are:

    FP_ZERO  FP_NORMAL  FP_SUBNORMAL  FP_INFINITE  FP_NAN

Implementations may also define additional categories, and corresponding macros whose names begin with FP_ followed by an uppercase letter.

math.h defines the following function-like macros to classify floating-point values:


fpclassify( )

This macro expands to the value of the FP_ ... macro that designates the category of its floating-point argument.


isfinite( ), isinf( ), isnan( ), isnormal( ), signbit( )

These function-like macros test whether their argument belongs to a specific category.

15.2.11.3. Other macros in math.h

The header math.h also defines the following macros:


HUGE_VAL, HUGE_VALF, HUGE_VALL

HUGE_VAL represents a large positive value with the type double. Mathematical functions that return double can return the value of HUGE_VAL, with the appropriate sign, when the result exceeds the finite value range of double. The value of HUGE_VAL may also represent a positive infinity, if the implementation supports such a value.

HUGE_VALF and HUGE_VALL are analogous to HUGE_VAL, but have the types float and long double.


INFINITY

This macro's value is constant expression of type float that represents a positive or unsigned infinity, if such a value is representable in the given implementation. If not, then INFINITY represents a constant expression of type float that yields an overflow when evaluated, so that the compiler generates an error message when processing it.


NAN

NaN stands for "not a number." The macro NAN is a constant of type float whose value is not a valid floating-point number. It is defined only if the implementation supports quiet NaNsthat is, if a NaN can occur without raising a floating-point exception.


FP_FAST_FMA, FP_FAST_FMAF, FP_FAST_FMAL

FMA stands for "fused multiply-and-add." The macro FP_FAST_FMA is defined if the function call fma(x,y,z) can be evaluated at least as fast as the mathematically equivalent expression x*y+z, for x, y, and z of type double. This is typically the case if the fma( ) function makes use of a special FMA machine operation.

The macros FP_FAST_FMAF and FP_FAST_FMAL are analogous to FP_FAST_FMA, but refer to the types float and long double.


FP_ILOGB0, FP_ILOGBNAN

These macros represent the respective values returned by the function call ilogb(x) when the argument x is zero or NaN. FP_ILOGB0 is equal either to INT_MIN or to -INT_MAX, and FP_ILOGBNAN equals either INT_MIN or INT_MAX.


MATH_ERRNO, MATH_ERREXCEPT, math_errhandling

MATH_ERRNO is the constant 1 and MATH_ERREXCEPT the constant 2. These values are represented by distinct bits, and hence can be used as bit masks in querying the value of math_errhandling. The identifier math_errhandling is either a macro or an external variable with the type int. Its value is constant throughout runtime, and you can query it in your programs to determine whether the mathematical functions indicate errors by raising exceptions or by providing an error code, or both. If the expression math_errhandling & MATH_ERRNO is not equal to zero, then the program can read the global error variable errno to identify domain and range errors in math function calls. Similarly, if math_errhandling & MATH_ERREXCEPT is nonzero, then the math functions indicate errors using the floating-point environment's exception flags. For more details, see "Error Handling" in Chapter 16.

If a given implementation supports programs that use floating-point exceptions, then the header fenv.h must define at least the macros FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW.

15.2.12. 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."

15.2.13. 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:

    SIGABRT  SIGFPE  SIGILL  SIGINT  SIGSEGV  SIGTERM

The meanings of these signal types are described along with the signal( ) function in Chapter 17. 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.

15.2.14. 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" in Chapter 7):


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.

15.2.15. 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

15.2.16. 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 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 .

The two macros defined in stddef.h are:


NULL

This macro represents a null pointer constantan 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.

15.2.17. 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.

15.2.17.1. Value ranges of the integer types with specific widths

If a signed type of a given specific width is defined, then the corresponding unsigned type is also defined, and vice versa. Unsigned types have names that start with u (such as uint64_t, for example), which is followed by the name of the corresponding signed type (such as int64_t).

For each type defined in stdint.h, macros are also defined to designate the type's least and greatest representable values. Table 15-5 lists the names of these macros, with the standard's requirements for their values. The word "exactly" in the table indicates that the standard specifies an exact value rather than a maximum or minimum. Otherwise, the standard allows the implementation to exceed the ranges given in the table. The letter N before an underscore in the type names as listed here is a placeholder for a decimal number indicating the bit width of a given type. Commonly implemented values are 8, 16, 32, and 64.

Table 15-5. Value ranges of the integer types with specific widths

Type

Minimum

Maximum

Maximum value of the unsigned type

intN_t

INTN_MIN

Exactly -(2N-1)

INTN_MAX

Exactly 2N-1 - 1

UINTN_MAX

Exactly 2N - 1

int_leastN_t

INT_LEASTN_MIN

-(2N-1 - 1)

INT_LEASTN_MAX

2N-1 - 1

UINT_LEASTN_MAX

2N - 1

int_fastN_t

INT_FASTN_MIN

-(2N-1 - 1)

INT_FASTN_MAX

2N-1 - 1

UINT_FASTN_MAX

2N - 1

intmax_t

INTMAX_MIN

-(263 - 1)

INTMAX_MAX

263 - 1

UINTMAX_MAX

264 - 1

intptr_t

INTPTR_MIN

-(215 - 1)

INTPTR_MAX

215 - 1

UINTPTR_MAX

216- 1


For the meanings of the fixed-width integer type names, and the C standard's requirements as to which of them must be defined, please see "Integer Types with Exact Width" in Chapter 2.

15.2.17.2. Value ranges of other integer types

The header stdint.h also contains macros to document the value ranges of types defined in other headers. These types are listed in Table 15-6. The numbers in the table represent the minimum requirements of the C standard. The types sig_atomic_t, wchar_t, and wint_t may be defined as signed or unsigned.

Table 15-6. Value ranges of other integer types

Type

Minimum

Maximum

ptrdiff_t

PTRDIFF_MIN

-65535

PTRDIFF_MAX

+65535

sig_atomic_t

SIG_ATOMIC_MIN

If signed: -127

If unsigned: 0

SIG_ATOMIC_MAX

If signed: 127

If unsigned: 255

size_t

N/A

SIZE_MAX

65535

wchar_t

WCHAR_MIN

If signed: -127

If unsigned: 0

WCHAR_MAX

If signed: 127

If unsigned: 255

wint_t

WINT_MIN

If signed: -32767

If unsigned: 0

WINT_MAX

If signed: 32767

If unsigned: 65535


The types ptrdiff_t, size_t, and wchar_t are described in the section on stddef.h in this chapter. The type sig_atomic_t is described under signal.h, and wint_t is described under wchar.h.

In C++ implementations, the macros in Tables 15-5 and 15-6 are defined only if the macro _ _STDC_LIMIT_MACROS is defined when you include stdint.h.

15.2.17.3. Macros for integer constants

For each decimal number N for which the header stdint.h defines a type int_leastN_t (an integer type that is at least N bits wide), the header also defines two function-like macros to generate values with the type int_leastN_t. Arguments to these macros must be constants in decimal, octal, or hexadecimal notation, and must be within the value range of the intended type (see "Integer Constants" in Chapter 3). The macros are:


INT N_C( value) , UINT N_C( value)

Expands to a signed or unsigned integer constant with the specified value and the type int_leastN_t or uint_leastN_t, which is at least N bits wide. For example, if uint_least32_t is defined as a synonym for the type unsigned long, then the macro call UINT32_C(123) may expand to the constant 123UL.

The following macros are defined for the types intmax_t and uintmax_t:


INTMAX_C( value) , UINTMAX_C( value)

These macros expand to a constant with the specified value and the type intmax_t or uintmax_t.

(In C++ implementations, these macros are defined only if _ _STDC_CONSTANT_MACROS is defined when you include stdint.h.)

15.2.18. 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 functionsthat is, for input and output of characters with the type wchar_tare contained in the header file wchar.h (see also Chapter 13).

In addition to size_t, which is discussed under stddef.h in this chapter, 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 under 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.

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.

15.2.19. 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 under stddef.h in this chapter, 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.

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( ).

15.2.20. 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 under stddef.h in this section.

15.2.21. 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 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 doublethat 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 15-7 then expands to the function call shown in the right column.

Table 15-7. Expansion of type-generic macros

Type-generic macro call

Expansion

sqrt(f)

sqrtf(f)

sqrt(d)

sqrt(d)

sqrt(z1)

csqrt(z1)

sqrt(z2)

csqrtl(z2)


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" in Chapter 4). 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.

15.2.22. time.h

The header time.h declares the standard functions, macros and types for manipulating date and time information. These functions are listed in the section "Date and Time" in Chapter 16.

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 17.

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.

15.2.23. wchar.h

The headers stdio.h, stdlib.h, string.h, and time.h all declare functions for processing byte-character stringsthat 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 under 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.

15.2.24. 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 under 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 under wchar.h.


Previous Page
Next Page