## 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 ## 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 The names of the mathematical functions for complex numbers
all begin with the letter cerf( ) cerfc( ) cexp2( ) cexpm1( ) clog10( ) clog1p( ) clog2( ) clgamma( ) ctgamma( ) The same names with the suffixes The header file 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.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 All names that begin with ## 15.2.4. errno.hThis header declares the identifier The identifier #define errno (* _errno( )) The header 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 ## 15.2.5. fenv.hC99 introduced the ## 15.2.5.1. Macro and type definitions for the floating-point environmentThe header 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 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: 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 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 modesImplementations may allow programs to query or set the way floating-point results are rounded. If so, the header `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 ## 15.2.6. float.hThe header file ## 15.2.6.1. Normalized representation of floating-point numbersThe values of the macros in
x 0.sd_{1}d_{2} ... d_{p} x b^{e}The symbols in this representation have the following meanings and conditions: *s*The sign of ;*x*= 1 or*s*= -1*s**d*_{i}A base digit in the significand (also called the mantissa ) of*b*(0.*x**d*_{1}*d*_{2}...*d*_{p}in the general representation);*d*_{1}> 0 if0*x**p*The number of digits in the significand (or to be more precise, in the fraction part) *b*The base of the exponent; > 1*b**e*The integer exponent; *e*_{min}*e**e*_{max}
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 0,*x*=*e**e*_{min}, and*d*_{1}= 0.Non-normalized floating-point numbers, for which 0,*x*>*e**e*_{min}, and*d*_{1}= 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 ## 15.2.6.2. Rounding mode and evaluation methodThe following two macros defined in the header 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 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_RADIX The *radix*or base () of the exponential representation of floating point numbers; usually 2*b*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`(*e*_{min})FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP The largest positive exponent to the base `FLT_RADIX`(*e*_{max})
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
## 15.2.7. inttypes.hThe header ## 15.2.7.1. TypesThe header 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. FunctionsIn addition to ## 15.2.7.3. MacrosFurthermore, The names of the type specifier macros for the PRId The letter 8, 16, 32, and 64.Other #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 The names of the conversion specifier macros for the SCNd Again, the letter 8, 16, 32, and 64.## 15.2.8. iso646.hThe header
## 15.2.9. limits.hThe header
The range of the type The header 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 The value of ## 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 The function LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME The function The second function defined in ## 15.2.11. math.hThe header The mathematical functions for integer types are declared in ## 15.2.11.1. The types float_t and double_tThe header
Any other value of ## 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 FP_ZERO FP_NORMAL FP_SUBNORMAL FP_INFINITE FP_NAN Implementations may also define additional categories, and corresponding macros whose names begin with
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.hThe header 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*`+`, for*z*,*x*, and*y*of type*z*`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 argumentis zero or NaN.*x*`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 ## 15.2.12. setjmp.hThe header Calling ## 15.2.13. signal.hThe header 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 Each type of signal that programs can receive is identified by a signal number. Accordingly, SIGABRT SIGFPE SIGILL SIGINT SIGSEGV SIGTERM The meanings of these signal types are described along with the The first argument to the function 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.hThe header 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 ## 15.2.15. stdbool.hThe header 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.hThe header 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 The two macros defined in 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. The member must not be a bit-field.*member*
## 15.2.17. stdint.hThe header ## 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 For each type defined in 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
The types In C++ implementations, the macros in Tables 15-5 and 15-6 are defined only if the macro ## 15.2.17.3. Macros for integer constantsFor each decimal number stdint.h defines a type int_leastN_t (an integer type that is at least bits wide), the header also defines two function-like macros to generate values with the type Nint_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 _C(*N*) , UINT*value*_C(*N*)*value*Expands to a signed or unsigned integer constant with the specified and the type*value*`int_least`*N*`_t`or`uint_least`*N*`_t`, which is at leastbits wide. For example, if*N*`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( ) , UINTMAX_C(*value*)*value*These macros expand to a constant with the specified and the type*value*`intmax_t`or`uintmax_t`.
(In C++ implementations, these macros are defined only if ## 15.2.18. stdio.hThe header In addition to 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 _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 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.hThe header 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
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 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.hThe header The header ## 15.2.21. tgmath.hThe header 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 The header #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 Several functions are defined only for complex floating-point types. The type-generic macros for these functions have names that start with 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 The types declared in 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 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.hThe headers Furthermore, the header 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 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 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.hThe header The types defined in 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 |