4.10 GENERAL UTILITIES The header declares four types and several functions of general utility, and defines several macros. The types declared are size_t and wchar_t (both described in $4.1.5), div_t which is a structure type that is the type of the value returned by the div function, and ldiv_t which is a structure type that is the type of the value returned by the ldiv function. The macros defined are NULL (described in $4.1.5); EXIT_FAILURE and EXIT_SUCCESS which expand to integral expressions that may be used as the argument to the exit function to return unsuccessful or successful termination status, respectively, to the host environment; RAND_MAX which expands to an integral constant expression, the value of which is the maximum value returned by the rand function; and MB_CUR_MAX which expands to a positive integer expression whose value is the maximum number of bytes in a multibyte character for the extended character set specified by the current locale (category LC_CTYPE ), and whose value is never greater than MB_LEN_MAX . 4.10.1 String conversion functions The functions atof , atoi , and atol need not affect the value of the integer expression errno on an error. If the value of the result cannot be represented, the behavior is undefined. 4.10.1.1 The atof function Synopsis #include double atof(const char *nptr); Description The atof function converts the initial portion of the string pointed to by nptr to double representation. Except for the behavior on error, it is equivalent to strtod(nptr, (char **)NULL) Returns The atof function returns the converted value. Forward references: the strtod function ($4.10.1.4). 4.10.1.2 The atoi function Synopsis #include int atoi(const char *nptr); Description The atoi function converts the initial portion of the string pointed to by nptr to int representation. Except for the behavior on error, it is equivalent to (int)strtol(nptr, (char **)NULL, 10) Returns The atoi function returns the converted value. Forward references: the strtol function ($4.10.1.5). 4.10.1.3 The atol function Synopsis #include long int atol(const char *nptr); Description The atol function converts the initial portion of the string pointed to by nptr to long int representation. Except for the behavior on error, it is equivalent to strtol(nptr, (char **)NULL, 10) Returns The atol function returns the converted value. Forward references: the strtol function ($4.10.1.5). 4.10.1.4 The strtod function Synopsis #include double strtod(const char *nptr, char **endptr); Description The strtod function converts the initial portion of the string pointed to by nptr to double representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white-space characters (as specified by the isspace function), a subject sequence resembling a floating-point constant; and a final string of one or more unrecognized characters, including the terminating null character of the input string. Then it attempts to convert the subject sequence to a floating-point number, and returns the result. The expected form of the subject sequence is an optional plus or minus sign, then a nonempty sequence of digits optionally containing a decimal-point character, then an optional exponent part as defined in $3.1.3.1, but no floating suffix. The subject sequence is defined as the longest subsequence of the input string, starting with the first non-white-space character, that is an initial subsequence of a sequence of the expected form. The subject sequence contains no characters if the input string is empty or consists entirely of white space, or if the first non-white-space character is other than a sign, a digit, or a decimal-point character. If the subject sequence has the expected form, the sequence of characters starting with the first digit or the decimal-point character (whichever occurs first) is interpreted as a floating constant according to the rules of $3.1.3.1, except that the decimal-point character is used in place of a period, and that if neither an exponent part nor a decimal-point character appears, a decimal point is assumed to follow the last digit in the string. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated. A pointer to the final string is stored in the object pointed to by endptr , provided that endptr is not a null pointer. In other than the C locale, additional implementation-defined subject sequence forms may be accepted. If the subject sequence is empty or does not have the expected form, no conversion is performed; the value of nptr is stored in the object pointed to by endptr , provided that endptr is not a null pointer. Returns The strtod function returns the converted value, if any. If no conversion could be performed, zero is returned. If the correct value would cause overflow, plus or minus HUGE_VAL is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno . If the correct value would cause underflow, zero is returned and the value of the macro ERANGE is stored in errno . 4.10.1.5 The strtol function Synopsis #include long int strtol(const char *nptr, char **endptr, int base); Description The strtol function converts the initial portion of the string pointed to by nptr to long int representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white-space characters (as specified by the isspace function), a subject sequence resembling an integer represented in some radix determined by the value of base , and a final string of one or more unrecognized characters, including the terminating null character of the input string. Then it attempts to convert the subject sequence to an integer, and returns the result. If the value of base is zero, the expected form of the subject sequence is that of an integer constant as described in $3.1.3.2, optionally preceded by a plus or minus sign, but not including an integer suffix. If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base , optionally preceded by a plus or minus sign, but not including an integer suffix. The letters from a (or A ) through z (or Z ) are ascribed the values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and digits, following the sign if present. The subject sequence is defined as the longest subsequence of the input string, starting with the first non-white-space character, that is an initial subsequence of a sequence of the expected form. The subject sequence contains no characters if the input string is empty or consists entirely of white space, or if the first non-white-space character is other than a sign or a permissible letter or digit. If the subject sequence has the expected form and the value of base is zero, the sequence of characters starting with the first digit is interpreted as an integer constant according to the rules of $3.1.3.2. If the subject sequence has the expected form and the value of base is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated. A pointer to the final string is stored in the object pointed to by endptr , provided that endptr is not a null pointer. In other than the C locale, additional implementation-defined subject sequence forms may be accepted. If the subject sequence is empty or does not have the expected form, no conversion is performed; the value of nptr is stored in the object pointed to by endptr , provided that endptr is not a null pointer. Returns The strtol function returns the converted value, if any. If no conversion could be performed, zero is returned. If the correct value would cause overflow, LONG_MAX or LONG_MIN is returned (according to the sign of the value), and the value of the macro ERANGE is stored in errno . 4.10.1.6 The strtoul function Synopsis #include unsigned long int strtoul(const char *nptr, char **endptr, int base); Description The strtoul function converts the initial portion of the string pointed to by nptr to unsigned long int representation. First it decomposes the input string into three parts: an initial, possibly empty, sequence of white-space characters (as specified by the isspace function), a subject sequence resembling an unsigned integer represented in some radix determined by the value of base , and a final string of one or more unrecognized characters, including the terminating null character of the input string. Then it attempts to convert the subject sequence to an unsigned integer, and returns the result. If the value of base is zero, the expected form of the subject sequence is that of an integer constant as described in $3.1.3.2, optionally preceded by a plus or minus sign, but not including an integer suffix. If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence of letters and digits representing an integer with the radix specified by base , optionally preceded by a plus or minus sign, but not including an integer suffix. The letters from a (or A ) through z (or Z ) are ascribed the values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the value of base is 16, the characters 0x or 0X may optionally precede the sequence of letters and digits, following the sign if present. The subject sequence is defined as the longest subsequence of the input string, starting with the first non-white-space character, that is an initial subsequence of a sequence of the expected form. The subject sequence contains no characters if the input string is empty or consists entirely of white space, or if the first non-white-space character is other than a sign or a permissible letter or digit. If the subject sequence has the expected form and the value of base is zero, the sequence of characters starting with the first digit is interpreted as an integer constant according to the rules of $3.1.3.2. If the subject sequence has the expected form and the value of base is between 2 and 36, it is used as the base for conversion, ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, the value resulting from the conversion is negated. A pointer to the final string is stored in the object pointed to by endptr , provided that endptr is not a null pointer. In other than the C locale, additional implementation-defined subject sequence forms may be accepted. If the subject sequence is empty or does not have the expected form, no conversion is performed; the value of nptr is stored in the object pointed to by endptr , provided that endptr is not a null pointer. Returns The strtoul function returns the converted value, if any. If no conversion could be performed, zero is returned. If the correct value would cause overflow, ULONG_MAX is returned, and the value of the macro ERANGE is stored in errno . 4.10.2 Pseudo-random sequence generation functions 4.10.2.1 The rand function Synopsis #include int rand(void); Description The rand function computes a sequence of pseudo-random integers in the range 0 to RAND_MAX . The implementation shall behave as if no library function calls the rand function. Returns The rand function returns a pseudo-random integer. "Environmental limit" The value of the RAND_MAX macro shall be at least 32767. 4.10.2.2 The srand function Synopsis #include void srand(unsigned int seed); Description The srand function uses the argument as a seed for a new sequence of pseudo-random numbers to be returned by subsequent calls to rand . If srand is then called with the same seed value, the sequence of pseudo-random numbers shall be repeated. If rand is called before any calls to srand have been made, the same sequence shall be generated as when srand is first called with a seed value of 1. The implementation shall behave as if no library function calls the srand function. Returns The srand function returns no value. Example The following functions define a portable implementation of rand and srand . Specifying the semantics makes it possible to determine reproducibly the behavior of programs that use pseudo-random sequences. This facilitates the testing of portable applications in different implementations. static unsigned long int next = 1; int rand(void) /* RAND_MAX assumed to be 32767 */ { next = next * 1103515245 + 12345; return (unsigned int)(next/65536) % 32768; } void srand(unsigned int seed) { next = seed; } 4.10.3 Memory management functions The order and contiguity of storage allocated by successive calls to the calloc , malloc , and realloc functions is unspecified. The pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to a pointer to any type of object and then used to access such an object in the space allocated (until the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object disjoint from any other object. The pointer returned points to the start (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer is returned. If the size of the space requested is zero, the behavior is implementation-defined; the value returned shall be either a null pointer or a unique pointer. The value of a pointer that refers to freed space is indeterminate. 4.10.3.1 The calloc function Synopsis #include void *calloc(size_t nmemb, size_t size); Description The calloc function allocates space for an array of nmemb objects, each of whose size is size . The space is initialized to all bits zero. Returns The calloc function returns either a null pointer or a pointer to the allocated space. 4.10.3.2 The free function Synopsis #include void free(void *ptr); Description The free function causes the space pointed to by ptr to be deallocated, that is, made available for further allocation. If ptr is a null pointer, no action occurs. Otherwise, if the argument does not match a pointer earlier returned by the calloc , malloc , or realloc function, or if the space has been deallocated by a call to free or realloc , the behavior is undefined. Returns The free function returns no value. 4.10.3.3 The malloc function Synopsis #include void *malloc(size_t size); Description The malloc function allocates space for an object whose size is specified by size and whose value is indeterminate. Returns The malloc function returns either a null pointer or a pointer to the allocated space. 4.10.3.4 The realloc function Synopsis #include void *realloc(void *ptr, size_t size); Description The realloc function changes the size of the object pointed to by ptr to the size specified by size . The contents of the object shall be unchanged up to the lesser of the new and old sizes. If the new size is larger, the value of the newly allocated portion of the object is indeterminate. If ptr is a null pointer, the realloc function behaves like the malloc function for the specified size. Otherwise, if ptr does not match a pointer earlier returned by the calloc , malloc , or realloc function, or if the space has been deallocated by a call to the free or realloc function, the behavior is undefined. If the space cannot be allocated, the object pointed to by ptr is unchanged. If size is zero and ptr is not a null pointer, the object it points to is freed. Returns The realloc function returns either a null pointer or a pointer to the possibly moved allocated space. 4.10.4 Communication with the environment 4.10.4.1 The abort function Synopsis #include void abort(void); Description The abort function causes abnormal program termination to occur, unless the signal SIGABRT is being caught and the signal handler does not return. Whether open output streams are flushed or open streams closed or temporary files removed is implementation-defined. An implementation-defined form of the status unsuccessful termination is returned to the host environment by means of the function call raise(SIGABRT) . Returns The abort function cannot return to its caller. 4.10.4.2 The atexit function Synopsis #include int atexit(void (*func)(void)); Description The atexit function registers the function pointed to by func , to be called without arguments at normal program termination. "Implementation limits" The implementation shall support the registration of at least 32 functions. Returns The atexit function returns zero if the registration succeeds, nonzero if it fails. Forward references: the exit function ($4.10.4.3). 4.10.4.3 The exit function Synopsis #include void exit(int status); Description The exit function causes normal program termination to occur. If more than one call to the exit function is executed by a program, the behavior is undefined. First, all functions registered by the atexit function are called, in the reverse order of their registration. Next, all open output streams are flushed, all open streams are closed, and all files created by the tmpfile function are removed. Finally, control is returned to the host environment. If the value of status is zero or EXIT_SUCCESS , an implementation-defined form of the status successful termination is returned. If the value of status is EXIT_FAILURE , an implementation-defined form of the status unsuccessful termination is returned. Otherwise the status returned is implementation-defined. Returns The exit function cannot return to its caller. 4.10.4.4 The getenv function Synopsis #include char *getenv(const char *name); Description The getenv function searches an environment list ,provided by the host environment, for a string that matches the string pointed to by name . The set of environment names and the method for altering the environment list are implementation-defined. The implementation shall behave as if no library function calls the getenv function. Returns The getenv function returns a pointer to a string associated with the matched list member. The array pointed to shall not be modified by the program, but may be overwritten by a subsequent call to the getenv function. If the specified name cannot be found, a null pointer is returned. 4.10.4.5 The system function Synopsis #include int system(const char *string); Description The system function passes the string pointed to by string to the host environment to be executed by a command processor in an implementation-defined manner. A null pointer may be used for string to inquire whether a command processor exists. Returns If the argument is a null pointer, the system function returns nonzero only if a command processor is available. If the argument is not a null pointer, the system function returns an implementation-defined value. 4.10.5 Searching and sorting utilities 4.10.5.1 The bsearch function Synopsis #include void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *)); Description The bsearch function searches an array of nmemb objects, the initial member of which is pointed to by base , for a member that matches the object pointed to by key . The size of each member of the array is specified by size . The contents of the array shall be in ascending sorted order according to a comparison function pointed to by compar ,/116/ induces which is called with two arguments that point to the key object and to an array member, in that order. The function shall return an integer less than, equal to, or greater than zero if the key object is considered, respectively, to be less than, to match, or to be greater than the array member. Returns The bsearch function returns a pointer to a matching member of the array, or a null pointer if no match is found. If two members compare as equal, which member is matched is unspecified. 4.10.5.2 The qsort function Synopsis #include void qsort(void *base, size_t nmemb, size_t size, int (*compar)(const void *, const void *)); Description The qsort function sorts an array of nmemb objects, the initial member of which is pointed to by base . The size of each object is specified by size . The contents of the array are sorted in ascending order according to a comparison function pointed to by compar , which is called with two arguments that point to the objects being compared. The function shall return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted array is unspecified. Returns The qsort function returns no value. 4.10.6 Integer arithmetic functions 4.10.6.1 The abs function Synopsis #include int abs(int j); Description The abs function computes the absolute value of an integer j . If the result cannot be represented, the behavior is undefined. Returns The abs function returns the absolute value. 4.10.6.2 The div function Synopsis #include div_t div(int numer, int denom); Description The div function computes the quotient and remainder of the division of the numerator numer by the denominator denom . If the division is inexact, the sign of the resulting quotient is that of the algebraic quotient, and the magnitude of the resulting quotient is the largest integer less than the magnitude of the algebraic quotient. If the result cannot be represented, the behavior is undefined; otherwise, quot * denom + rem shall equal numer . Returns The div function returns a structure of type div_t , comprising both the quotient and the remainder. The structure shall contain the following members, in either order. int quot; /* quotient */ int rem; /* remainder */ 4.10.6.3 The labs function Synopsis #include long int labs(long int j); Description The labs function is similar to the abs function, except that the argument and the returned value each have type long int . 4.10.6.4 The ldiv function Synopsis #include ldiv_t ldiv(long int numer, long int denom); Description The ldiv function is similar to the div function, except that the arguments and the members of the returned structure (which has type ldiv_t ) all have type long int . 4.10.7 Multibyte character functions The behavior of the multibyte character functions is affected by the LC_CTYPE category of the current locale. For a state-dependent encoding, each function is placed into its initial state by a call for which its character pointer argument, s , is a null pointer. Subsequent calls with s as other than a null pointer cause the internal state of the function to be altered as necessary. A call with s as a null pointer causes these functions to return a nonzero value if encodings have state dependency, and zero otherwise. After the LC_CTYPE category is changed, the shift state of these functions is indeterminate. 4.10.7.1 The mblen function Synopsis #include int mblen(const char *s, size_t n); Description If s is not a null pointer, the mblen function determines the number of bytes comprising the multibyte character pointed to by s . Except that the shift state of the mbtowc function is not affected, it is equivalent to mbtowc((wchar_t *)0, s, n); The implementation shall behave as if no library function calls the mblen function. Returns If s is a null pointer, the mblen function returns a nonzero or zero value, if multibyte character encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the mblen function either returns 0 (if s points to the null character), or returns the number of bytes that comprise the multibyte character (if the next n or fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid multibyte character). Forward references: the mbtowc function ($4.10.7.2). 4.10.7.2 The mbtowc function Synopsis #include int mbtowc(wchar_t *pwc, const char *s, size_t n); Description If s is not a null pointer, the mbtowc function determines the number of bytes that comprise the multibyte character pointed to by s . It then determines the code for value of type wchar_t that corresponds to that multibyte character. (The value of the code corresponding to the null character is zero.) If the multibyte character is valid and pwc is not a null pointer, the mbtowc function stores the code in the object pointed to by pwc . At most n bytes of the array pointed to by s will be examined. The implementation shall behave as if no library function calls the mbtowc function. Returns If s is a null pointer, the mbtowc function returns a nonzero or zero value, if multibyte character encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the mbtowc function either returns 0 (if s points to the null character), or returns the number of bytes that comprise the converted multibyte character (if the next n or fewer bytes form a valid multibyte character), or returns -1 (if they do not form a valid multibyte character). In no case will the value returned be greater than n or the value of the MB_CUR_MAX macro. 4.10.7.3 The wctomb function Synopsis #include int wctomb(char *s, wchar_t wchar); Description The wctomb function determines the number of bytes needed to represent the multibyte character corresponding to the code whose value is wchar (including any change in shift state). It stores the multibyte character representation in the array object pointed to by s (if s is not a null pointer). At most MB_CUR_MAX characters are stored. If the value of wchar is zero, the wctomb function is left in the initial shift state. The implementation shall behave as if no library function calls the wctomb function. Returns If s is a null pointer, the wctomb function returns a nonzero or zero value, if multibyte character encodings, respectively, do or do not have state-dependent encodings. If s is not a null pointer, the wctomb function returns -1 if the value of wchar does not correspond to a valid multibyte character, or returns the number of bytes that comprise the multibyte character corresponding to the value of wchar . In no case will the value returned be greater than the value of the MB_CUR_MAX macro. 4.10.8 Multibyte string functions The behavior of the multibyte string functions is affected by the LC_CTYPE category of the current locale. 4.10.8.1 The mbstowcs function Synopsis #include size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n); Description The mbstowcs function converts a sequence of multibyte characters that begins in the initial shift state from the array pointed to by s into a sequence of corresponding codes and stores not more than n codes into the array pointed to by pwcs . No multibyte characters that follow a null character (which is converted into a code with value zero) will be examined or converted. Each multibyte character is converted as if by a call to the mbtowc function, except that the shift state of the mbtowc function is not affected. No more than n elements will be modified in the array pointed to by pwcs . If copying takes place between objects that overlap, the behavior is undefined. Returns If an invalid multibyte character is encountered, the mbstowcs function returns (size_t)-1 . Otherwise, the mbstowcs function returns the number of array elements modified, not including a terminating zero code, if any.rN 4.10.8.2 The wcstombs function Synopsis #include size_t wcstombs(char *s, const wchar_t *pwcs, size_t n); Description The wcstombs function converts a sequence of codes that correspond to multibyte characters from the array pointed to by pwcs into a sequence of multibyte characters that begins in the initial shift state and stores these multibyte characters into the array pointed to by s , stopping if a multibyte character would exceed the limit of n total bytes or if a null character is stored. Each code is converted as if by a call to the wctomb function, except that the shift state of the wctomb function is not affected. No more than n bytes will be modified in the array pointed to by s . If copying takes place between objects that overlap, the behavior is undefined. Returns If a code is encountered that does not correspond to a valid multibyte character, the wcstombs function returns (size_t)-1 . Otherwise, the wcstombs function returns the number of bytes modified, not including a terminating null character, if any.rN