DEC C
Language Reference Manual
9.12 General Utilities (<stdlib.h>)
The <stdlib.h> header file declares
four types and several functions of general use, and defines several
macros. The functions perform string conversion, random number
generation, searching and sorting, memory management, and similar tasks.
Types
size_t
- An unsigned integral type of the result of the sizeof operator.
wchar_t
- 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.
div_t
- A structure type that is the type of the value returned by the
div function.
ldiv_t
- A structure type that is the type of the value returned by the
ldiv function.
Macros
NULL
- Expands to an implementation-defined null pointer constant.
EXIT_FAILURE/EXIT_SUCCESS
- Expand to integral expressions for use as the argument to the exit function to return unsuccessful or
successful termination status, respectively, to the host environment.
These macros are useful as return values from the main function as well.
RAND_MAX
- Expands to an integral constant expression whose value is the
maximum value returned by the rand
function.
MB_CUR_MAX
- 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_TYPE), and whose value is never greater than
MB_LEN_MAX.
String Conversion Functions
double atof(const char*nptr);
- Converts the string pointed to by nptr to double representation and returns the converted
value. Except for its behavior when an error occurs, this function is
equivalent to:
strtod(nptr, (char **)NULL)
|
int atoi(const char*nptr);
- Converts the string pointed to by nptr to int representation and returns the converted
value. Except for its behavior when an error occurs, this function is
equivalent to:
(int)strtol(nptr, (char **)NULL, 10)
|
long int atol(const char*nptr);
- Converts the string pointed to by nptr to long int representation and returns the
converted value. Except for its behavior when an error occurs, this
function is equivalent to:
strtol(nptr, (char **)NULL, 10)
|
double strtod(const char*nptr, char
**endptr);
- Converts the string pointed to by nptr to double representation.
See your
DEC C library routine documentation for a detailed description
of this function.
long int strtol(const char*nptr, char
**endptr, int base);
- Converts the string pointed to by nptr to long int representation.
See your
DEC C library routine documentation for a detailed description
of this function.
unsigned long int strtoul(const char *nptr,
char **endptr, int base);
- Converts the string pointed to by nptr to unsigned long int representation.
See your
DEC C library routine documentation for a detailed description
of this function.
Pseudo-Random Sequence Generation Functions
int rand(void);
- Returns a sequence of pseudo-random integers in the range 0 to
RAND_MAX.
void srand(unsigned intseed);
- Uses the argument as a seed for a new sequence of pseudo-random
integers to be returned by subsequent calls to rand. If srand is
then called with the same seed value, the sequence of pseudo-random
integers is repeated. If rand is called
before any calls to srand are made, the
sequence generated is the same as when srand is first called with a seed value of 1.
The srand function returns no value.
Memory Management Functions
void*calloc(size_t nmemb, size_t
size);
- Allocates an area in memory for an array of nmemb items,
each with size size. The area is initialized to all bits 0.
The calloc function returns either a null
pointer if unable to allocate, or a pointer to the allocated area.
void free(void*ptr);
- Deallocates the memory area pointed to by ptr that was
allocated by a previous calloc, malloc, or realloc. If ptr is null, no action
occurs. No value is returned.
void*malloc(size_t size);
- Allocates a contiguous area in memory for an object of size
size. The area is not initialized. This function returns a
pointer to the allocated area, or it returns a null pointer if unable
to allocate.
void*realloc(void *ptr, size_t
size);
- Changes the size of the area pointed to by ptr to the
number of bytes specified by size. If ptr is null,
the behavior of realloc is identical to
malloc. The contents of the area are
unchanged up to the lesser of the old and new sizes. This function
returns either a null pointer if unable to resize, or a pointer to the
possibly moved reallocated area.
Communication with the Environment
void abort(void);
- Causes abnormal program termination to occur, unless the SIGABRT signal is being caught and the signal
handler does not return. The abort
function cannot return to its caller.
int atexit(void (*func)(void));
- Registers the function pointed to by func to be called
without arguments at normal program termination. Up to 32 functions can
be registered. The atexit function
returns 0 if the registration succeeds; otherwise, it returns nonzero.
void exit(intstatus);
- Causes normal program termination to occur. If a program executes
more than one call to exit, the behavior
is undefined. Upon execution, the following occurs:
- All functions registered by atexit
are called in the reverse order of their registration.
- All open output streams are flushed, all open streams are closed,
and all files created by tmpfile are
removed.
- Control is returned to the host environment. The value of
status corresponds to an errno
value:
- If the value status is 0 or EXIT_SUCCESS, a successful termination
status is returned.
- If the value status is EXIT_FAILURE, an unsuccessful
termination status is returned.
- Otherwise, an unsuccessful termination status is returned.
char*getenv(const char *name);
- Searches an environment list provided by the host environment.
See your DEC C library routine documentation for a detailed
description of this function.
int*system(const char *string);
- Passes the string pointed to by string to the host
environment for execution by a command processor. A null pointer can be
specified to inquire whether a command processor exists. If the
argument is a null pointer, the system
function returns nonzero if a command processor is available or 0 if
one is not available. If the argument is not a null pointer, the return
value is the status returned by the command processor or 0 if a command
processor is not available.
See your DEC C library routine
documentation for a detailed description of this function.
Searching and Sorting Utilities
void *bsearch(const void *key, const void *base,
size_t nmemb, size_t size, int (*compar)
(const void *, const void *));
|
- Searches an array of nmemb objects for an element that
matches the object pointed to by key. The first element of the
array is pointed to by base; the size of each element is
specified by size.
You must first sort the array in
ascending order according to the function pointed to by
compar. The bsearch function
calls the specified comparison function pointed to by compar
with two arguments that point to the objects being compared (the
key object and an array element). The comparison function
returns:
- An integer less than 0, if the first argument is less than the
second argument
- An integer greater than 0, if the first argument is greater than
the second argument
- An integer equal to 0, if the first argument equals the second
argument
The bsearch function returns a
pointer to the matching element of the array, or a null pointer if no
match is found.
void qsort(void *base, size_t nmemb,
size_t size, int (*compar) (const void *,
const void *));
|
- Sorts an array of nmemb objects in place. The first
element of the array is pointed to by base; the size of each
element 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
comparison function returns:
- An integer less than 0, if the first argument is less than the
second argument
- An integer greater than 0, if the first argument is greater than
the second argument
- An integer equal to 0, if the first argument equals the second
argument
If two compared elements are equal, their order in the sorted array
is unspecified.
The qsort function
returns no value.
Integer Arithmetic Functions
int abs(intj);
- Returns the absolute value of an integer j.
div_t div(int numer, int
denom);
- Computes the quotient and remainder of the division of
numer by denom. The div
function returns a structure of type div_t containing the quotient and remainder:
int quot; /* quotient */
int rem; /* remainder */
|
long int labs(long intj);
- Returns the absolute value of a long integer j.
ldiv_t ldiv(long int numer, long int
denom);
- 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.
Multibyte Character Functions
int mblen(const char*s, size_t
n);
- If s is not a null pointer, mblen determines the number of bytes comprising
the multibyte character pointed to by s. The mblen function is equivalent to the following,
except that the shift state of the mbtowc
is not affected:
mbtowc((wchar_t *)0, s, n);
|
If s is a null pointer, the mblen function returns a nonzero value if
multibyte character encodings have state-dependent encodings, and 0 if
they do not.
If s is not a null pointer, the mblen function returns one of the following
values:
- 0, if s points to the null character
- The number of bytes that comprise the multibyte character, if the
next n or fewer bytes form a valid multibyte character
- --1, if they do not form a valid multibyte character
int mbtowc(wchar_t *pwc, const char
*s, size_t n);
- If s is not a null pointer, mbtowc determines the number of bytes
comprising the multibyte character pointed to by s. It then
determines the code for the value of type wchar_t that corresponds to that multibyte
character. (The value of the code corresponding to the null character
is 0.) If the multibyte character is valid and pwc is not a
null pointer, mbtowc stores the code in
the object pointed to by pwc. At most, n bytes of the
array pointed to by s are examined.
If s is a
null pointer, the mbtowc function returns
a nonzero value if multibyte character encodings have state-dependent
encodings, and 0 if they do not.
If s is not a null
pointer, the mbtowc function returns one
of the following values:
- 0, if s points to the null character
- The number of bytes that comprise the converted multibyte
character, if the next n or fewer bytes form a valid multibyte
character
- --1, if they do not form a valid multibyte character
int wctomb(char*s, wchar_t
wchar);
- 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. This function then 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 0, the wctomb
function is left in the initial shift state.
If s is a
null pointer, the wctomb function returns
a nonzero value if multibyte character encodings have state-dependent
encodings, and 0 if they do not.
If s is not a null
pointer, the wctomb function returns one
of the following values:
- --1, if the value of wchar does not correspond to a valid
multibyte character
- the number of bytes that comprise the multibyte character
corresponding to the value of wchar
Multibyte String Functions
size_t mbstowcs(wchar_t *pwcs, const char
*s, size_t n);
- Converts a sequence of multibyte characters that begin 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. A null character is
converted to a code value of zero. No multibyte characters that follow
a null character are examined or converted. Each multibyte character is
converted as if by a call to mbtowc,
except that the shift state of mbtowc is
not affected.
If an invalid multibyte character is encountered, the
mbstowcs function returns (size_t) - 1. Otherwise, it returns the number
of array elements modified, not including a terminating zero code, if
any.
size_t wcstombs(char *s, const wchar_t
*pwcs, size_t n);
- 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. The conversion stops 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 wctomb, except that the shift state of wctomb is not affected.
If a code is
encountered that does not correspond to a valid multibyte character,
the wcstombs function returns (size_t) - 1. Otherwise, it returns the number
of bytes modified, not including a terminating null character, if any.
9.13 String Processing (<string.h>)
The <string.h> header file declares
one type and several functions, and defines one macro useful for
manipulating character arrays that other objects treat as character
arrays.
There are two kinds of string functions declared. The first, with names
beginning with str, manipulate character
arrays; the second, with names beginning with mem, manipulate other objects treated as
character arrays. Except for memmove,
function behavior is undefined if copying takes place between
overlapping objects.
Type
size_t
- An unsigned integral type of the result of the sizeof operator.
Macro
NULL
- Expands to an implementation-defined null pointer constant.
Functions
void*memcpy(void *s1, const void
*s2, size_t n);
- Copies n characters from the object pointed to by
s2 to the object pointed to by s1. The function
returns s1.
void*memmove(void *s1, const void
*s2, size_t n);
- Copies n characters from the object pointed to by
s2 to the object pointed to by s1. Copying takes
place as if the n characters from the object pointed to by
s2 are first copied into a temporary array of n
characters that does not overlap the object pointed to by s1
and s2, and then the n characters from the temporary
array are copied into the object pointed to by s1. The memmove function returns s1.
void*memchr(const void *s, int c,
size_t n);
- Locates the first occurrence of c (converted to an
unsigned char) in the first n
unsigned characters of the object pointed to by s. The memchr function returns a pointer to the
located character, or a null pointer if the character was not found.
int memcmp(const void*s1, const void
*s2, size_t n);
- Compares the first n characters of the object pointed to
by s1 to the first n characters of the object pointed
to by s2. The memcmp function
returns an integer less than, equal to, or greater than 0, depending on
whether the object pointed to by s1 is less than, equal to, or
greater than the object pointed to by s2.
void*memset(void *s, int c, size_t
n);
- Copies the value of c (converted to an unsigned char) into
each of the first n characters pointed to by s. The
function returns s.
char*strcpy(char *s1, const char
*s2);
- Copies the string pointed to by s2 (including the
terminating null character) to the string pointed to by s1.
The strcpy function returns s1.
char*strncpy(char *s1, const char
*s2, size_t n);
- Copies no more than n characters from the string pointed
to by s2 to the string pointed to by s1, up to but
not including the null terminator of the string pointed to by
s2; returns s1. If the string pointed to by
s2 is less than n characters, strncpy pads the copy with null characters.
char*strcat(char *s1, const char
*s2);
- Appends a copy of the the string pointed to by s2
(including the terminating null character) to the end of the string
pointed to by s1. The strcat
function returns s1. The first character of s2
overwrites the null character of s1.
char*strncat(char *s1, const char
*s2, size_t n);
- Appends no more than n characters from the string pointed
to by s2 (up to but not including a null character) to the
string pointed to by s1. The strncat function returns s1. The first
character of s2 overwrites the null character of s1.
A terminating null character is appended to the result. The first
character of s2 overwrites the null character of s1.
int strcmp(const char*s1, const char
*s2);
- Compares the string pointed to by s1 to the string pointed
to by s2. The strcmp function
returns an integer less than, equal to, or greater than 0, depending on
whether the string pointed to by s1 is less than, equal to, or
greater than the string pointed to by s2.
int strcoll(const char*s1, const char
*s2);
- Compares the string pointed to by s1 to the string pointed
to by s2, both interpreted as appropriate to the LC_COLLATE category of the current locale (see
Section 9.5). The strcoll function
returns an integer less than, equal to, or greater than 0, depending on
whether the string pointed to by s1 is less than, equal to, or
greater than the string pointed to by s2, when both are
interpreted as appropriate to the current locale.
int strncmp(const char*s1, const char
*s2, size_t n);
- Compares no more than n characters from the string pointed
to by s1 to the string pointed to by s2. The strings
are compared until a null character is encountered, the strings differ,
or n is reached. The strncmp
function returns an integer less than, equal to, or greater than 0,
depending on whether the string pointed to by s1 is less than,
equal to, or greater than the string pointed to by s2.
size_t strxfrm(char *s1, const char
*s2, size_t n);
- Transforms the string pointed to by s2 and places the
resulting string into the array pointed to by s1.
See your
DEC C library routine documentation for a detailed description
of this function.