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.
|
Printer-friendly version
The C Book
This book is published as a matter of historical interest.
Please read the
copyright and disclaimer information.
GBdirect Ltd provides up-to-date training and consultancy in
C,
Embedded C,
C++
and a wide range of
other subjects based on
open standards if you happen to be interested.
|