|
|
15.2. Contents of the Standard HeadersThe 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.hThis 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.hC99 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:
15.2.3. ctype.hThis 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.hThis 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:
All macro names that begin with E followed by a digit or an uppercase letter are reserved for future extensions. 15.2.5. fenv.hC99 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 environmentThe header fenv.h contains the following definitions to manipulate the floating-point environment:
15.2.5.2. Macro and type definitions for floating-point exceptionsImplementations 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:
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:
15.2.5.3. Macro definitions for rounding modesImplementations 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:
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.hThe 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 numbersThe 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:
The floating-point types may also be able to represent other values besides normalized floating-point numbers, such as the following kinds of values:
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 methodThe following two macros defined in the header float.h provide details about how floating-point arithmetic is performed:
15.2.6.3. Precision and value rangeFor 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.
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.
15.2.7. inttypes.hThe 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. TypesThe header inttypes.h defines the following structure type:
15.2.7.2. FunctionsIn 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. MacrosFurthermore, 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.hThe 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.
15.2.9. limits.hThe 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.
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:
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.hThe 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.hThe 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_tThe 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.
Any other value of FLT_EVAL_METHOD indicates that the evaluation of floating-point expressions is implementation-defined. 15.2.11.2. Classification macrosIn 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:
15.2.11.3. Other macros in math.hThe header math.h also defines the following macros:
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.hThe 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.hThe header signal.h declares the functions raise( ) and signal( ), as well as related macros and the following integer type:
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:
15.2.14. stdarg.hThe 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):
The macros va_copy( ) and va_end( ) may also be implemented as functions. 15.2.15. stdbool.hThe header stdbool.h defines the following four macros:
15.2.16. stddef.hThe header stddef.h defines three types and two macros for use in all kinds of programs. The three types are:
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:
15.2.17. stdint.hThe 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 widthsIf 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.
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 typesThe 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.
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 constantsFor 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:
(In C++ implementations, these macros are defined only if _ _STDC_CONSTANT_MACROS is defined when you include stdint.h.) 15.2.18. stdio.hThe 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:
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:
The header stdio.h also declares three objects:
15.2.19. stdlib.hThe header stdlib.h declares general utility functions for the following purposes:
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:
The header stdlib.h defines the macro NULL (see stddef.h) as well as the following four macros:
15.2.20. string.hThe 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.hThe 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.
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.hThe 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:
The header time.h defines the macro NULL (see stddef.h) and the following macro:
15.2.23. wchar.hThe 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:
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:
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:
15.2.24. wctype.hThe 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:
The header wctype.h also defines the macro WEOF, described under wchar.h.  |
|
|
0
e 
or -