4. LIBRARY 4.1 INTRODUCTION 4.1.1 Definitions of terms A string is a contiguous sequence of characters terminated by and including the first null character. It is represented by a pointer to its initial (lowest addressed) character and its length is the number of characters preceding the null character. A letter is a printing character in the execution character set corresponding to any of the 52 required lower-case and upper-case letters in the source character set, listed in $2.2.1. The decimal-point character is the character used by functions that convert floating-point numbers to or from character sequences to denote the beginning of the fractional part of such character sequences. It is represented in the text and examples by a period, but may be changed by the setlocale function. Forward references: character handling ($4.3), the setlocale function ($4.4.1.1). 4.1.2 Standard headers Each library function is declared in a header ,/81/ whose contents are made available by the #include preprocessing directive. The header declares a set of related functions, plus any necessary types and additional macros needed to facilitate their use. Each header declares and defines only those identifiers listed in its associated section. All external identifiers declared in any of the headers are reserved, whether or not the associated header is included. All external identifiers that begin with an underscore are reserved. All other identifiers that begin with an underscore and either an upper-case letter or another underscore are reserved. If the program defines an external identifier with the same name as a reserved external identifier, even in a semantically equivalent form, the behavior is undefined. The standard headers are If a file with the same name as one of the above < and > delimited sequences, not provided as part of the implementation, is placed in any of the standard places for a source file to be included, the behavior is undefined. Headers may be included in any order; each may be included more than once in a given scope, with no effect different from being included only once, except that the effect of including depends on the definition of NDEBUG . If used, a header shall be included outside of any external declaration or definition, and it shall first be included before the first reference to any of the functions or objects it declares, or to any of the types or macros it defines. Furthermore, the program shall not have any macros with names lexically identical to keywords currently defined prior to the inclusion. Forward references: diagnostics ($4.2). 4.1.3 Errors The header defines several macros, all relating to the reporting of error conditions. The macros are EDOM ERANGE which expand to distinct nonzero integral constant expressions; and errno which expands to a modifiable lvalue that has type int , the value of which is set to a positive error number by several library functions. It is unspecified whether errno is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual object, or a program defines an external identifier with the name errno , the behavior is undefined. The value of errno is zero at program startup, but is never set to zero by any library function. The value of errno may be set to nonzero by a library function call whether or not there is an error, provided the use of errno is not documented is the description of the function in the Standard. Additional macro definitions, beginning with E and a digit or E and an upper-case letter, may also be specified by the implementation. 4.1.4 Limits and The headers and define several macros that expand to various limits and parameters. The macros, their meanings, and their minimum magnitudes are listed in $2.2.4.2. 4.1.5 Common definitions The following types and macros are defined in the standard header . Some are also defined in other headers, as noted in their respective sections. The types are ptrdiff_t which is the signed integral type of the result of subtracting two pointers; size_t which is the unsigned integral type of the result of the sizeof operator; and wchar_t which is an integral type whose range of values can represent distinct codes for all members of the largest extended character set specified among the supported locales; the null character shall have the code value zero and each member of the basic character set defined in $2.2.1 shall have a code value equal to its value when used as the lone character in an integer character constant. The macros are NULL which expands to an implementation-defined null pointer constant; and offsetof( type, member-designator) which expands to an integral constant expression that has type size_t , the value of which is the offset in bytes, to the structure member (designated by member-designator ), from the beginning of its structure (designated by type ). The member-designator shall be such that given static type t; then the expression &(t. member-designator ) evaluates to an address constant. (If the specified member is a bit-field, the behavior is undefined.) Forward references: localization ($4.4). 4.1.6 Use of library functions Each of the following statements applies unless explicitly stated otherwise in the detailed descriptions that follow. If an argument to a function has an invalid value (such as a value outside the domain of the function, or a pointer outside the address space of the program, or a null pointer), the behavior is undefined. Any function declared in a header may be implemented as a macro defined in the header, so a library function should not be declared explicitly if its header is included. Any macro definition of a function can be suppressed locally by enclosing the name of the function in parentheses, because the name is then not followed by the left parenthesis that indicates expansion of a macro function name. For the same syntactic reason, it is permitted to take the address of a library function even if it is also defined as a macro. The use of #undef to remove any macro definition will also ensure that an actual function is referred to. Any invocation of a library function that is implemented as a macro will expand to code that evaluates each of its arguments exactly once, fully protected by parentheses where necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those function-like macros described in the following sections may be invoked in an expression anywhere a function with a compatible return type could be called. Provided that a library function can be declared without reference to any type defined in a header, it is also permissible to declare the function, either explicitly or implicitly, and use it without including its associated header. If a function that accepts a variable number of arguments is not declared (explicitly or by including its associated header), the behavior is undefined. Examples The function atoi may be used in any of several ways: * by use of its associated header (possibly generating a macro expansion) #include const char *str; /*...*/ i = atoi(str); * by use of its associated header (assuredly generating a true function reference) #include #undef atoi const char *str; /*...*/ i = atoi(str); or #include const char *str; /*...*/ i = (atoi)(str); * by explicit declaration extern int atoi(const char *); const char *str; /*...*/ i = atoi(str); * by implicit declaration const char *str; /*...*/ i = atoi(str); 4.2 DIAGNOSTICS The header defines the assert macro and refers to another macro, NDEBUG which is not defined by . If NDEBUG is defined as a macro name at the point in the source file where is included, the assert macro is defined simply as #define assert(ignore) ((void)0) The assert macro shall be implemented as a macro, not as an actual function. If the macro definition is suppressed in order to access an actual function, the behavior is undefined. 4.2.1 Program diagnostics 4.2.1.1 The assert macro Synopsis #include void assert(int expression); Description The assert macro puts diagnostics into programs. When it is executed, if expression is false (that is, compares equal to 0), the assert macro writes information about the particular call that failed (including the text of the argument, the name of the source file, and the source line number EM the latter are respectively the values of the preprocessing macros __FILE__ and __LINE__ ) on the standard error file in an implementation-defined format. expression , xyz , nnn It then calls the abort function. Returns The assert macro returns no value. Forward references: the abort function ($4.10.4.1). 4.3 CHARACTER HANDLING The header declares several functions useful for testing and mapping characters. In all cases the argument is an int , the value of which shall be representable as an unsigned char or shall equal the value of the macro EOF. If the argument has any other value, the behavior is undefined. The behavior of these functions is affected by the current locale. Those functions that have no implementation-defined aspects in the C locale are noted below. The term printing character refers to a member of an implementation-defined set of characters, each of which occupies one printing position on a display device; the term control character refers to a member of an implementation-defined set of characters that are not printing characters. Forward references: EOF ($4.9.1), localization ($4.4). 4.3.1 Character testing functions The functions in this section return nonzero (true) if and only if the value of the argument c conforms to that in the description of the function. 4.3.1.1 The isalnum function Synopsis #include int isalnum(int c); Description The isalnum function tests for any character for which isalpha or isdigit is true. 4.3.1.2 The isalpha function Synopsis #include int isalpha(int c); Description The isalpha function tests for any character for which isupper or islower is true, or any of an implementation-defined set of characters for which none of iscntrl , isdigit , ispunct , or isspace is true. In the C locale, isalpha returns true only for the characters for which isupper or islower is true. 4.3.1.3 The iscntrl function Synopsis #include int iscntrl(int c); Description The iscntrl function tests for any control character. 4.3.1.4 The isdigit function Synopsis #include int isdigit(int c); Description The isdigit function tests for any decimal-digit character (as defined in $2.2.1). 4.3.1.5 The isgraph function Synopsis #include int isgraph(int c); Description The isgraph function tests for any printing character except space (' '). 4.3.1.6 The islower function Synopsis #include int islower(int c); Description The islower function tests for any lower-case letter or any of an implementation-defined set of characters for which none of iscntrl , isdigit , ispunct , or isspace is true. In the C locale, islower returns true only for the characters defined as lo wer-case letters (as defined in $2.2.1). 4.3.1.7 The isprint function Synopsis #include int isprint(int c); Description The isprint function tests for any printing character including space (' '). 4.3.1.8 The ispunct function Synopsis #include int ispunct(int c); Description The ispunct function tests for any printing character except space (' ') or a character for which isalnum is true. 4.3.1.9 The isspace function Synopsis #include int isspace(int c); Description The isspace function tests for the standard white-space characters or for any of an implementation-defined set of characters for which isalnum is false. The standard white-space characters are the following: space (' '), form feed ('\f'), new-line ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v'). In the C locale, isspace returns true only for the standard white-space characters. 4.3.1.10 The isupper function Synopsis #include int isupper(int c); Description The isupper function tests for any upper-case letter or any of an implementation-defined set of characters for which none of iscntrl , isdigit , ispunct , or isspace is true. In the C locale, isupper returns true only for the characters defined as upper-case letters (as defined in $2.2.1). 4.3.1.11 The isxdigit function Synopsis #include int isxdigit(int c); Description The isxdigit function tests for any hexadecimal-digit character (as defined in $3.1.3.2). 4.3.2 Character case mapping functions 4.3.2.1 The tolower function Synopsis #include int tolower(int c); Description The tolower function converts an upper-case letter to the corresponding lower-case letter. Returns If the argument is an upper-case letter, the tolower function returns the corresponding lower-case letter if there is one; otherwise the argument is returned unchanged. In the C locale, tolower maps only the characters for which isupper is true to the corresponding characters for which islower is true. 4.3.2.2 The toupper function Synopsis #include int toupper(int c); Description The toupper function converts a lower-case letter to the corresponding upper-case letter. Returns If the argument is a lower-case letter, the toupper function returns the corresponding upper-case letter if there is one; otherwise the argument is returned unchanged. In the C locale, toupper maps only the characters for which islower is true to the corresponding characters for which isupper is true. 4.4 LOCALIZATION The header declares two functions, one type, and defines several macros. The type is struct lconv which contains members related to the formatting of numeric values. The structure shall contain at least the following members, in any order. The semantics of the members and their normal ranges is explained in $4.4.2.1. In the C locale, the members shall have the values specified in the comments. char *decimal_point; /* "." */ char *thousands_sep; /* "" */ char *grouping; /* "" */ char *int_curr_symbol; /* "" */ char *currency_symbol; /* "" */ char *mon_decimal_point; /* "" */ char *mon_thousands_sep; /* "" */ char *mon_grouping; /* "" */ char *positive_sign; /* "" */ char *negative_sign; /* "" */ char int_frac_digits; /* CHAR_MAX */ char frac_digits; /* CHAR_MAX */ char p_cs_precedes; /* CHAR_MAX */ char p_sep_by_space; /* CHAR_MAX */ char n_cs_precedes; /* CHAR_MAX */ char n_sep_by_space; /* CHAR_MAX */ char p_sign_posn; /* CHAR_MAX */ char n_sign_posn; /* CHAR_MAX */ The macros defined are NULL (described in $4.1.5); and LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME which expand to distinct integral constant expressions, suitable for use as the first argument to the setlocale function. Additional macro definitions, beginning with the characters LC_ and an upper-case letter,/91/ may also be specified by the implementation. 4.4.1 Locale control 4.4.1.1 The setlocale function Synopsis #include char *setlocale(int category, const char *locale); Description The setlocale function selects the appropriate portion of the program's locale as specified by the category and locale arguments. The setlocale function may be used to change or query the program's entire current locale or portions thereof. The value LC_ALL for category names the program's entire locale; the other values for category name only a portion of the program's locale. LC_COLLATE affects the behavior of the strcoll and strxfrm functions. LC_CTYPE affects the behavior of the character handling functions/92/ and the multibyte functions. LC_MONETARY affects the monetary formatting information returned by the localeconv function. LC_NUMERIC affects the decimal-point character for the formatted input/output functions and the string conversion functions, as well as the non-monetary formatting information returned by the localeconv function. LC_TIME affects the behavior of the strftime function. A value of C for locale specifies the minimal environment for C translation; a value of C for locale specifies the implementation-defined native environment. Other implementation-defined strings may be passed as the second argument to setlocale . At program startup, the equivalent of setlocale(LC_ALL, "C"); is executed. The implementation shall behave as if no library function calls the setlocale function. Returns If a pointer to a string is given for locale and the selection can be honored, the setlocale function returns the string associated with the specified category for the new locale. If the selection cannot be honored, the setlocale function returns a null pointer and the program's locale is not changed. A null pointer for locale causes the setlocale function to return the string associated with the category for the program's current locale; the program's locale is not changed. The string returned by the setlocale function is such that a subsequent call with that string and its associated category will restore that part of the program's locale. The string returned shall not be modified by the program, but may be overwritten by a subsequent call to the setlocale function. Forward references: formatted input/output functions ($4.9.6), the multibyte character functions ($4.10.7), the multibyte string functions ($4.10.8), string conversion functions ($4.10.1), the strcoll function ($4.11.4.3), the strftime function ($4.12.3.2), the strxfrm function ($4.11.4.5). 4.4.2 Numeric formatting convention inquiry 4.4.2.1 The localeconv function Synopsis #include struct lconv *localeconv(void); Description The localeconv function sets the components of an object with type struct lconv with values appropriate for the formatting of numeric quantities (monetary and otherwise) according to the rules of the current locale. The members of the structure with type char * are strings, any of which (except decimal_point ) can point to , to indicate that the value is not available in the current locale or is of zero length. The members with type char are nonnegative numbers any of which can be CHAR_MAX to indicate that the value is not available in the current locale. The members include the following: The decimal-point character used to format non-monetary quantities. The character used to separate groups of digits to the left of the decimal-point character in formatted non-monetary quantities. A string whose elements indicate the size of each group of digits in formatted non-monetary quantities. The international currency symbol applicable to the current locale. The first three characters contain the alphabetic international currency symbol in accordance with those specified in ISO 4217 Codes for the Representation of Currency and Funds. The fourth character (immediately preceding the null character) is the character used to separate the international currency symbol from the monetary quantity. The local currency symbol applicable to the current locale. The decimal-point used to format monetary quantities. The separator for groups of digits to the left of the decimal-point in formatted monetary quantities. A string whose elements indicate the size of each group of digits in formatted monetary quantities. The string used to indicate a nonnegative-valued formatted monetary quantity. The string used to indicate a negative-valued formatted monetary quantity. The number of fractional digits (those to the right of the decimal-point) to be displayed in a internationally formatted monetary quantity. The number of fractional digits (those to the right of the decimal-point) to be displayed in a formatted monetary quantity. Set to 1 or 0 if the currency_symbol respectively precedes or succeeds the value for a nonnegative formatted monetary quantity. Set to 1 or 0 if the currency_symbol respectively is or is not separated by a space from the value for a nonnegative formatted monetary quantity. Set to 1 or 0 if the currency_symbol respectively precedes or succeeds the value for a negative formatted monetary quantity. Set to 1 or 0 if the currency_symbol respectively is or is not separated by a space from the value for a negative formatted monetary quantity. Set to a value indicating the positioning of the positive_sign for a nonnegative formatted monetary quantity. Set to a value indicating the positioning of the negative_sign for a negative formatted monetary quantity. The elements of grouping and mon_grouping are interpreted according to the following: No further grouping is to be performed. The previous element is to be repeatedly used for the remainder of the digits. The value is the number of digits that comprise the current group. The next element is examined to determine the size of the next group of digits to the left of the current group. The value of p_sign_posn and n_sign_posn is interpreted according to the following: Parentheses surround the quantity and currency_symbol . The sign string precedes the quantity and currency_symbol . The sign string succeeds the quantity and currency_symbol . The sign string immediately precedes the currency_symbol . The sign string immediately succeeds the currency_symbol . The implementation shall behave as if no library function calls the localeconv function. Returns The localeconv function returns a pointer to the filled-in object. The structure pointed to by the return value shall not be modified by the program, but may be overwritten by a subsequent call to the localeconv function. In addition, calls to the setlocale function with categories LC_ALL , LC_MONETARY , or LC_NUMERIC may overwrite the contents of the structure. Examples The following table illustrates the rules used by four countries to format monetary quantities. Country Positive format Negative format International format Italy L.1.234 -L.1.234 ITL.1.234 Netherlands F 1.234,56 F -1.234,56 NLG 1.234,56 Norway kr1.234,56 kr1.234,56- NOK 1.234,56 Switzerland SFrs.1,234.56 SFrs.1,234.56C CHF 1,234.56 For these four countries, the respective values for the monetary members of the structure returned by localeconv are: Italy Netherlands Norway Switzerland int_curr_symbol "ITL." "NLG " "NOK " "CHF " currency_symbol "L." "F" "kr" "SFrs." mon_decimal_point "" "," "," "." mon_thousands_sep "." "." "." "," mon_grouping "\3" "\3" "\3" "\3" positive_sign "" "" "" "" negative_sign "-" "-" "-" "C" int_frac_digits 0 2 2 2 frac_digits 0 2 2 2 p_cs_precedes 1 1 1 1 p_sep_by_space 0 1 0 0 n_cs_precedes 1 1 1 1 n_sep_by_space 0 1 0 0 p_sign_posn 1 1 1 1 n_sign_posn 1 4 2 2 4.5 MATHEMATICS The header declares several mathematical functions and defines one macro. The functions take double-precision arguments and return double-precision values. Integer arithmetic functions and conversion functions are discussed later. The macro defined is HUGE_VAL which expands to a positive double expression, not necessarily representable as a float . Forward references: integer arithmetic functions ($4.10.6), the atof function ($4.10.1.1), the strtod function ($4.10.1.4). 4.5.1 Treatment of error conditions The behavior of each of these functions is defined for all representable values of its input arguments. Each function shall execute as if it were a single operation, without generating any externally visible exceptions. For all functions, a domain error occurs if an input argument is outside the domain over which the mathematical function is defined. The description of each function lists any required domain errors; an implementation may define additional domain errors, provided that such errors are consistent with the mathematical definition of the function. On a domain error, the function returns an implementation-defined value; the value of the macro EDOM is stored in errno . Similarly, a range error occurs if the result of the function cannot be represented as a double value. If the result overflows (the magnitude of the result is so large that it cannot be represented in an object of the specified type), the function returns the value of the macro HUGE_VAL , with the same sign as the correct value of the function; the value of the macro ERANGE is stored in errno . If the result underflows (the magnitude of the result is so small that it cannot be represented in an object of the specified type), the function returns zero; whether the integer expression errno acquires the value of the macro ERANGE is implementation-defined. 4.5.2 Trigonometric functions 4.5.2.1 The acos function Synopsis #include double acos(double x); Description The acos function computes the principal value of the arc cosine of x . A domain error occurs for arguments not in the range [-1, +1]. Returns The acos function returns the arc cosine in the range [0, PI] radians. 4.5.2.2 The asin function Synopsis #include double asin(double x); Description The asin function computes the principal value of the arc sine of x . A domain error occurs for arguments not in the range [-1, +1]. Returns The asin function returns the arc sine in the range [-PI/2, +PI/2] radians. 4.5.2.3 The atan function Synopsis #include double atan(double x); Description The atan function computes the principal value of the arc tangent of x . Returns The atan function returns the arc tangent in the range [-PI/2, +PI/2] radians. 4.5.2.4 The atan2 function Synopsis #include double atan2(double y, double x); Description The atan2 function computes the principal value of the arc tangent of y/x , using the signs of both arguments to determine the quadrant of the return value. A domain error may occur if both arguments are zero. Returns The atan2 function returns the arc tangent of y/x , in the range [-PI, +PI] radians. 4.5.2.5 The cos function Synopsis #include double cos(double x); Description The cos function computes the cosine of x (measured in radians). A large magnitude argument may yield a result with little or no significance. Returns The cos function returns the cosine value. 4.5.2.6 The sin function Synopsis #include double sin(double x); Description The sin function computes the sine of x (measured in radians). A large magnitude argument may yield a result with little or no significance. Returns The sin function returns the sine value. 4.5.2.7 The tan function Synopsis #include double tan(double x); Description The tan function returns the tangent of x (measured in radians). A large magnitude argument may yield a result with little or no significance. Returns The tan function returns the tangent value. 4.5.3 Hyperbolic functions 4.5.3.1 The cosh function Synopsis #include double cosh(double x); Description The cosh function computes the hyperbolic cosine of x . A range error occurs if the magnitude of x is too large. Returns The cosh function returns the hyperbolic cosine value. 4.5.3.2 The sinh function Synopsis #include double sinh(double x); Description The sinh function computes the hyperbolic sine of x . A range error occurs if the magnitude of x is too large. Returns The sinh function returns the hyperbolic sine value. 4.5.3.3 The tanh function Synopsis #include double tanh(double x); Description The tanh function computes the hyperbolic tangent of x . Returns The tanh function returns the hyperbolic tangent value. 4.5.4 Exponential and logarithmic functions 4.5.4.1 The exp function Synopsis #include double exp(double x); Description The exp function computes the exponential function of x . A range error occurs if the magnitude of x is too large. Returns The exp function returns the exponential value. 4.5.4.2 The frexp function Synopsis #include double frexp(double value, int *exp); Description The frexp function breaks a floating-point number into a normalized fraction and an integral power of 2. It stores the integer in the int object pointed to by exp . Returns The frexp function returns the value x , such that x is a double with magnitude in the interval [1/2, 1) or zero, and value equals x times 2 raised to the power *exp . If value is zero, both parts of the result are zero. 4.5.4.3 The ldexp function Synopsis #include double ldexp(double x, int exp); Description The ldexp function multiplies a floating-point number by an integral power of 2. A range error may occur. Returns The ldexp function returns the value of x times 2 raised to the power exp . 4.5.4.4 The log function Synopsis #include double log(double x); Description The log function computes the natural logarithm of x. A domain error occurs if the argument is negative. A range error occurs if the argument is zero and the logarithm of zero cannot be represented. Returns The log function returns the natural logarithm. 4.5.4.5 The log10 function Synopsis #include double log10(double x); Description The log10 function computes the base-ten logarithm of x . A domain error occurs if the argument is negative. A range error occurs if the argument is zero and the logarithm of zero cannot be represented. Returns The log10 function returns the base-ten logarithm. 4.5.4.6 The modf function Synopsis #include double modf(double value, double *iptr); Description The modf function breaks the argument value into integral and fractional parts, each of which has the same sign as the argument. It stores the integral part as a double in the object pointed to by iptr . Returns The modf function returns the signed fractional part of value . 4.5.5 Power functions 4.5.5.1 The pow function Synopsis #include double pow(double x, double y); Description The pow function computes x raised to the power y . A domain error occurs if x is negative and y is not an integer. A domain error occurs if the result cannot be represented when x is zero and y is less than or equal to zero. A range error may occur. Returns The pow function returns the value of x raised to the power y . 4.5.5.2 The sqrt function Synopsis #include double sqrt(double x); Description The sqrt function computes the nonnegative square root of x . A domain error occurs if the argument is negative. Returns The sqrt function returns the value of the square root. 4.5.6 Nearest integer, absolute value, and remainder functions 4.5.6.1 The ceil function Synopsis #include double ceil(double x); Description The ceil function computes the smallest integral value not less than x . Returns The ceil function returns the smallest integral value not less than x , expressed as a double. 4.5.6.2 The fabs function Synopsis #include double fabs(double x); Description The fabs function computes the absolute value of a floating-point number x . Returns The fabs function returns the absolute value of x. 4.5.6.3 The floor function Synopsis #include double floor(double x); Description The floor function computes the largest integral value not greater than x . Returns The floor function returns the largest integral value not greater than x , expressed as a double. 4.5.6.4 The fmod function Synopsis #include double fmod(double x, double y); Description The fmod function computes the floating-point remainder of x/y . Returns The fmod function returns the value x i y , for some integer i such that, if y is nonzero, the result has the same sign as x and magnitude less than the magnitude of y . If y is zero, whether a domain error occurs or the fmod function returns zero is implementation-defined. 4.6 NON-LOCAL JUMPS The header defines the macro setjmp , and declares one function and one type, for bypassing the normal function call and return discipline. The type declared is jmp_buf which is an array type suitable for holding the information needed to restore a calling environment. It is unspecified whether setjmp is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the name setjmp , the behavior is undefined. 4.6.1 Save calling environment 4.6.1.1 The setjmp macro Synopsis #include int setjmp(jmp_buf env); Description The setjmp macro saves its calling environment in its jmp_buf argument for later use by the longjmp function. Returns If the return is from a direct invocation, the setjmp macro returns the value zero. If the return is from a call to the longjmp function, the setjmp macro returns a nonzero value. "Environmental constraint" An invocation of the setjmp macro shall appear only in one of the following contexts: * the entire controlling expression of a selection or iteration statement; * one operand of a relational or equality operator with the other operand an integral constant expression, with the resulting expression being the entire controlling expression of a selection or iteration statement; * the operand of a unary ! operator with the resulting expression being the entire controlling expression of a selection or iteration statement; or * the entire expression of an expression statement (possibly cast to void ). 4.6.2 Restore calling environment 4.6.2.1 The longjmp function Synopsis #include void longjmp(jmp_buf env, int val); Description The longjmp function restores the environment saved by the most recent invocation of the setjmp macro in the same invocation of the program, with the corresponding jmp_buf argument. If there has been no such invocation, or if the function containing the invocation of the setjmp macro has terminated execution/96/ in the interim, the behavior is undefined. All accessible objects have values as of the time longjmp was called, except that the values of objects of automatic storage duration that do not have volatile type and have been changed between the setjmp invocation and longjmp call are indeterminate . As it bypasses the usual function call and return mechanisms, the longjmp function shall execute correctly in contexts of interrupts, signals and any of their associated functions. However, if the longjmp function is invoked from a nested signal handler (that is, from a function invoked as a result of a signal raised during the handling of another signal), the behavior is undefined. Returns After longjmp is completed, program execution continues as if the corresponding invocation of the setjmp macro had just returned the value specified by val . The longjmp function cannot cause the setjmp macro to return the value 0; if val is 0, the setjmp macro returns the value 1. 4.7 SIGNAL HANDLING The header declares a type and two functions and defines several macros, for handling various signals (conditions that may be reported during program execution). The type defined is sig_atomic_t which is the integral type of an object that can be accessed as an atomic entity, even in the presence of asynchronous interrupts. The macros defined are SIG_DFL SIG_ERR SIG_IGN which expand to distinct constant expressions that have type compatible with the second argument to and the return value of the signal function, and whose value compares unequal to the address of any declarable function; and the following, each of which expands to a positive integral constant expression that is the signal number corresponding to the specified condition: abnormal termination, such as is initiated by the abort function an erroneous arithmetic operation, such as zero divide or an operation resulting in overflow detection of an invalid function image, such as an illegal instruction receipt of an interactive attention signal an invalid access to storage a termination request sent to the program An implementation need not generate any of these signals, except as a result of explicit calls to the raise function. Additional signals and pointers to undeclarable functions, with macro definitions beginning, respectively, with the letters SIG and an upper-case letter or with SIG_ and an upper-case letter,/97/ may also be specified by the implementation. The complete set of signals, their semantics, and their default handling is implementation-defined; all signal values shall be positive. 4.7.1 Specify signal handling 4.7.1.1 The signal function Synopsis #include void (*signal(int sig, void (*func)(int)))(int); Description The signal function chooses one of three ways in which receipt of the signal number sig is to be subsequently handled. If the value of func is SIG_DFL , default handling for that signal will occur. If the value of func is SIG_IGN , the signal will be ignored. Otherwise, func shall point to a function to be called when that signal occurs. Such a function is called a signal handler . When a signal occurs, if func points to a function, first the equivalent of signal(sig, SIG_DFL); is executed or an implementation-defined blocking of the signal is performed. (If the value of sig is SIGILL, whether the reset to SIG_DFL occurs is implementation-defined.) Next the equivalent of (*func)(sig); is executed. The function func may terminate by executing a return statement or by calling the abort , exit , or longjmp function. If func executes a return statement and the value of sig was SIGFPE or any other implementation-defined value corresponding to a computational exception, the behavior is undefined. Otherwise, the program will resume execution at the point it was interrupted. If the signal occurs other than as the result of calling the abort or raise function, the behavior is undefined if the signal handler calls any function in the standard library other than the signal function itself or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile sig_atomic_t. Furthermore, if such a call to the signal function results in a SIG_ERR return, the value of errno is indeterminate. At program startup, the equivalent of signal(sig, SIG_IGN); may be executed for some signals selected in an implementation-defined manner; the equivalent of signal(sig, SIG_DFL); is executed for all other signals defined by the implementation. The implementation shall behave as if no library function calls the signal function. Returns If the request can be honored, the signal function returns the value of func for the most recent call to signal for the specified signal sig . Otherwise, a value of SIG_ERR is returned and a positive value is stored in errno . Forward references: the abort function ($4.10.4.1). 4.7.2 Send signal 4.7.2.1 The raise function Synopsis #include int raise(int sig); Description The raise function sends the signal sig to the executing program. Returns The raise function returns zero if successful, nonzero if unsuccessful. 4.8 VARIABLE ARGUMENTS The header declares a type and defines three macros, for advancing through a list of arguments whose number and types are not known to the called function when it is translated. A function may be called with a variable number of arguments of varying types. As described in $3.7.1, its parameter list contains one or more parameters. The rightmost parameter plays a special role in the access mechanism, and will be designated permN in this description. The type declared is va_list which is a type suitable for holding information needed by the macros va_start , va_arg , and va_end . If access to the varying arguments is desired, the called function shall declare an object (referred to as ap in this section) having type va_list . The object ap may be passed as an argument to another function; if that function invokes the va_arg macro with parameter ap , the value of ap in the calling function is indeterminate and shall be passed to the va_end macro prior to any further reference to ap . 4.8.1 Variable argument list access macros The va_start and va_arg macros described in this section shall be implemented as macros, not as actual functions. It is unspecified whether va_end is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the name va_end , the behavior is undefined. The va_start and va_end macros shall be invoked in the function accepting a varying number of arguments, if access to the varying arguments is desired. 4.8.1.1 The va_start macro Synopsis #include void va_start(va_list ap, parmN); Description The va_start macro shall be invoked before any access to the unnamed arguments. The va_start macro initializes ap for subsequent use by va_arg and va_end . The parameter parmN is the identifier of the rightmost parameter in the variable parameter list in the function definition (the one just before the , ... ). If the parameter parmN is declared with the register storage class, with a function or array type, or with a type that is not compatible with the type that results after application of the default argument promotions, the behavior is undefined. Returns The va_start macro returns no value. 4.8.1.2 The va_arg macro Synopsis #include type va_arg(va_list ap, type); Description The va_arg macro expands to an expression that has the type and value of the next argument in the call. The parameter ap shall be the same as the va_list ap initialized by va_start . Each invocation of va_arg modifies ap so that the values of successive arguments are returned in turn. The parameter type is a type name specified such that the type of a pointer to an object that has the specified type can be obtained simply by postfixing a * to type . If there is no actual next argument, or if type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), the behavior is undefined. Returns The first invocation of the va_arg macro after that of the va_start macro returns the value of the argument after that specified by parmN . Successive invocations return the values of the remaining arguments in succession. 4.8.1.3 The va_end macro Synopsis #include void va_end(va_list ap); Description The va_end macro facilitates a normal return from the function whose variable argument list was referred to by the expansion of va_start that initialized the va_list ap . The va_end macro may modify ap so that it is no longer usable (without an interfening invocation of va_start ). If there is no corresponding invocation of the va_start macro, or if the va_end macro is not invoked before the return, the behavior is undefined. Returns The va_end macro returns no value. Example The function f1 gathers into an array a list of arguments that are pointers to strings (but not more than MAXARGS arguments), then passes the array as a single argument to function f2 . The number of pointers is specified by the first argument to f1. #include #define MAXARGS 31 void f1(int n_ptrs, ...) { va_list ap; char *array[MAXARGS]; int ptr_no = 0; if (n_ptrs > MAXARGS) n_ptrs = MAXARGS; va_start(ap, n_ptrs); while (ptr_no < n_ptrs) array[ptr_no++] = va_arg(ap, char *); va_end(ap); f2(n_ptrs, array); } Each call to f1 shall have visible the definition of the function or a declaration such as void f1(int, ...);