9.15. General Utilities

These all involve the use of the header <stdlib.h>, which declares a number of types and macros and several functions of general use. The types and macros are as follows:

size_t: Described at the start of this chapter.
div_t: This is the type of the structure returned by div.
ldiv_t: This is the type of the structure returned by ldiv.
NULL: Again, described at the start of this chapter.
EXIT_FAILURE
EXIT_SUCCESS: These may be used as arguments to exit.
MB_CUR_MAX: The maximum number of bytes in a multibyte character from the extended character set specified by the current locale.
RAND_MAX: This is the maximum value returned by the rand function.

9.15.1. String conversion functions

Three functions take a string as an argument and convert it to a number of the type shown below:

#include <stdlib.h>

double atof(const char *nptr);
long atol(const char *nptr);
int atoi(const char *nptr);

For each of the functions, the number is converted and the result returned. None of them guarantees to set errno (although they may do in some implementations), and the results of a conversion which overflows or cannot be represented is undefined.

More sophisticated functions are:

#include <stdlib.h>

double strtod(const char *nptr, char **endptr);
long strtol(const char *nptr, char **endptr, int base);
unsigned long strtoul(const char *nptr,char **endptr, int base);

All three functions work in a similar way. Leading white space is skipped, then a subject sequence, resembling an appropriate constant, is found, followed by a sequence of unrecognized characters. The trailing null at the end of a string is always unrecognized. The subject sequence can be empty. The subject sequences are determined as follows:

strtod: Optional + or -, followed by a digit sequence containing an optional decimal point character, followed by an optional exponent. No floating suffix will be recognized. If there is no decimal point present, it is assumed to follow the digit sequence.
strtol: Optional + or -, followed by a digit sequence. The digits are taken from the decimal digits or an upper or lower case letter in the range a–z of the English alphabet; the letters are given the values 10–35 respectively. The base argument determines which values are permitted, and may be zero, or otherwise 2–36. Only ‘digits’ with a value less than that of base are recognized. A base of 16 permits the characters 0x or 0X to follow the optional sign. A base of zero permits the input of characters in the form of a C integer constant. No integer suffix will be recognized.
strtoul: Identical to strtol but with no sign permitted.

If endptr is non-null, the address of the first unrecognized character is stored in the object that it points to. If the subject sequence is empty or has the wrong form, this is the value of nptr.

If a conversion can be performed, the functions convert the number and return its value, taking into account a leading sign where permitted. Otherwise they return zero. On overflow or error the action is as follows:

strtod: On overflow, returns ±HUGE_VAL according to the sign of the result; on underflow, returns zero. In either case, errno is set to ERANGE.
strtol: On overflow, LONG_MAX or LONG_MIN is returned according to the sign of the result, errno is set to ERANGE.
strtoul: On overflow, ULONG_MAX is returned, errno is set to ERANGE.

If the locale is not the "C" locale, there may be other subject sequences recognised depending on the implementation.

9.15.2. Random number generation

Provision for pseudo-random number generation is made by the following functions.

#include <stdlib.h>

int rand(void);
void srand(unsigned int seed);

Rand returns a pseudo-random number in the range 0 to RAND_MAX, which has a value of at least 32767.

Srand allows a given starting point in the sequence to be chosen according to the value of seed. If srand is not called before rand, the value of the seed is taken to be 1. The same sequence of values will always be returned from rand for a given value of seed.

The Standard describes an algorithm which may be used to implement rand and srand. In practice, most implementations will probably use this algorithm.

9.15.3. Memory allocation

These functions are used to allocate and free storage. The storage so obtained is only guaranteed to be large enough to store an object of the specified type and aligned appropriately so as not to cause addressing exceptions. No further assumptions can be made.

#include <stdlib.h>

void *malloc(size_t size);
void *calloc(size_t nmemb, size_t size);
void *realloc(void *ptr, size_t size);

void *free(void *ptr);

All of the memory allocation functions return a pointer to allocated storage of size size bytes. If there is no free storage, they return a null pointer. The differences between them are that calloc takes an argument nmemb which specifies the number of elements in an array, each of whose members is size bytes, and so allocates a larger piece of store (in general) than malloc. Also, the store allocated by malloc is not initialized, whereas calloc sets all bits in the storage to zero. This is not necessarily the equivalent representation of floating-point zero, or the null pointer.

Realloc is used to change the size of the thing pointed to by ptr, which may require some copying to be done and the old storage freed. The contents of the object pointed to by ptr is unchanged up to the smaller of the old and the new sizes. If ptr is null, the behaviour is identical to malloc with the appropriate size.

Free is used to free space previously obtained with one of the allocation routines. It is permissible to give free a null pointer as the argument, in which case nothing is done.

If an attempt is made to free store which was never allocated, or has already been freed, the behaviour is undefined. In many environments this causes an addressing exception which aborts the program, but this is not a reliable indicator.

9.15.4. Communication with the environment

A miscellany of functions is found here.

#include <stdlib.h>

void abort(void);
int atexit(void (*func)(void));
void exit(int status);
char *getenv(const char *name);
int system(const char *string);

abort

Causes abnormal program termination to occur, by raising the SIGABRT signal. Abnormal termination is only prevented if the signal is being caught, and the signal handler does not return. Otherwise, output files may be flushed and temporary files may be removed according to implementation definition, and an ‘unsuccessful termination’ status returned to the host environment. This function cannot return.

atexit

The argument func becomes a function to be called, without arguments, when the program terminates. Up to at least 32 such functions may be registered, and are called on program termination in reverse order of their registration. Zero is returned for success, non-zero for failure.

exit

Normal program termination occurs when this is called. First, all of the functions registered using atexit are called, but beware—by now, main is considered to have returned and no objects with automatic storage duration may safely be used. Then, all the open output streams are flushed, then closed, and all temporary files created by tmpfile are removed. Finally, the program returns control to the host environment, returning an implementation-defined form of successful or unsuccessful termination status depending on whether the argument to exit was EXITSUCCESS or EXIT FAILURE respectively. For compatibility with Old C, zero can be used in place of EXITSUCCESS, but other values have implementation-defined effects. Exit cannot return.

getenv

The implementation-defined environment list is searched to find an item which corresponds to the string pointed to by name. A pointer to the item is returned—it points to an array which must not be modified by the program, but may be overwritten by a subsequent call to getenv. A null pointer is returned if no item matches.

The purpose and implementation of the environment list depends on the host environment.

system

An implementation-defined command processor is passed the string string. A null pointer will cause a return of zero if no command processor exists, non-zero otherwise. A non-null pointer causes the command to be processed. The effect of the command and the value returned are implementation defined.

9.15.5. Searching and sorting

Two functions exist in this category: one for searching an already sorted list, the other for sorting an unsorted list. They are completely general, handling arrays of arbitrary size with elements of arbitrary size.

To enable them to compare two elements, the user provides a comparison function, which is called with pointers to two of the elements as its arguments. It returns a value less than, equal to or greater than zero depending on whether the first pointer points to an element considered to be less than, equal to or greater than the object pointed to by the second pointer, respectively.

#include <stdlib.h>

void *bsearch(const void *key, const void *base,
        size_t nmemb, size_t size,
        int (*compar)(const void *, const void *));

void *qsort(const void *base, size_t nmemb,
        size_t size,
        int (*compar)(const void *, const void *));

For both functions, nmemb is the number of elements in the array, size is the size in bytes of an array element and compar is the function to be called to compare them. Base is a pointer to the base of the array.

Qsort will sort the array into ascending order.

Bsearch assumes that the array is already sorted and returns a pointer to any element it finds that compares equal to the object pointed to by key. A null pointer is returned if no match is found.

9.15.6. Integer arithmetic functions

These provide ways of finding the absolute value of an integral argument and the quotient and remainder of a division, for both int and long types.

#include <stdlib.h>

int abs(int j);
long labs(long j);

div_t div(int numerator, int denominator);
ldiv_t ldiv(long numerator, long denominator);

abs
labs: These return the absolute value of their argument—choose the appropriate one for your needs. The behaviour is undefined if the value cannot be represented—this can happen in two's complement systems where the most negative number has no positive equivalent.
div
ldiv: These divide the numerator by the denominator and return a structure of the indicated type. In each case the structure will contain a member called quot which contains the quotient of the division truncated towards zero, and a member called rem which will contain the remainder. The type of each member is int for div and long for ldiv. Provided that the result could be represented, quot*denominator+rem == numerator.

9.15.7. Functions using multibyte characters

The LC_CTYPE category of the current locale affects the behaviour of these functions. For an encoding that is state-dependent, each function is put in its initial state by a call in which its character pointer argument, s, is a null pointer. The internal state of the function is altered as necessary by subsequent calls when s is not a null pointer. If s is a null pointer, the functions return a non-zero value if encodings are state-dependent, otherwise zero. If the LC_CTYPE category is changed, the shift state of the functions will become indeterminate.

The functions are:

#include <stdlib.h>

int mblen(const char *s, size_t n);
int mbtowc(wchar_t *pwc, const char *s, size_t n);
int wctomb(char *s, wchar_t wchar);
size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);
size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);

mblen

Returns the number of bytes that are contained in the multibyte character pointed to by s, or −1 if the first n bytes do not form a valid multibyte character. If s points to the null character, zero is returned.

mbtowc

Converts the multibyte character pointed to by s to the corresponding code of type wchar_t and stores the result in the object pointed to by pwc, unless pwc is a null pointer. Returns the number of bytes successfully converted, or −1 if the first n bytes do not form a valid multibye character. No more than n bytes pointed to by s are examined. The value returned will not be more than n or MB_CUR_MAX.

wctomb

Converts the code whose value is in wchar to a sequence of bytes representing the corresponding multibyte character, and stores the result in the array pointed to by s, if s is not a null pointer. Returns the number of bytes that are contained in the multibyte character, or −1 if the value in wchar does not correspond to a valid multibyte character. At most, MB_CUR_MAX bytes are processed.

mbstowcs

Converts the sequence of multibyte characters, beginning in the initial shift state, in the array pointed to by s, into a sequence of corresponding codes which are then stored in the array pointed to by pwcs. Not more than n values will be placed in pwcs. Returns −1 if an invalid multibyte character is encountered, otherwise returns the number of array elements modified, excluding the terminating null-code.

If the two objects overlap, the behaviour is undefined.

wcstombs

Converts the sequence of codes pointed to by pwcs to a sequence of multibyte characters, beginning in the initial shift state, which are then stored in the array pointed to by s. Conversion stops when either a null-code is encountered or n bytes have been written to s. Returns −1 if a code is encountered which does not correspond to a valid multibyte character, otherwise the number of bytes written, excluding the terminating null-code.

If the two objects overlap, the behaviour is undefined.

Previous section | Chapter contents | Next section