789 lines
33 KiB
HTML
789 lines
33 KiB
HTML
<HTML><HEAD><TITLE><stdlib.h></TITLE></HEAD><BODY BGCOLOR="#FFFFFF">
|
|
|
|
<H1><A NAME="<stdlib.h>"><CODE><stdlib.h></CODE></A></H1><HR>
|
|
|
|
<P><B><CODE><A HREF="#EXIT_FAILURE">EXIT_FAILURE</A>
|
|
· <A HREF="#EXIT_SUCCESS">EXIT_SUCCESS</A>
|
|
· <A HREF="#MB_CUR_MAX">MB_CUR_MAX</A>
|
|
· <A HREF="#NULL">NULL</A>
|
|
· <A HREF="#RAND_MAX">RAND_MAX</A>
|
|
· <A HREF="#abort">abort</A>
|
|
· <A HREF="#abs">abs</A>
|
|
· <A HREF="#atexit">atexit</A>
|
|
· <A HREF="#atof">atof</A>
|
|
· <A HREF="#atoi">atoi</A>
|
|
· <A HREF="#atol">atol</A>
|
|
· <A HREF="#bsearch">bsearch</A>
|
|
· <A HREF="#calloc">calloc</A>
|
|
· <A HREF="#div">div</A>
|
|
· <A HREF="#div_t">div_t</A>
|
|
· <A HREF="#exit">exit</A>
|
|
· <A HREF="#free">free</A>
|
|
· <A HREF="#getenv">getenv</A>
|
|
· <A HREF="#labs">labs</A>
|
|
· <A HREF="#ldiv">ldiv</A>
|
|
· <A HREF="#ldiv_t">ldiv_t</A>
|
|
· <A HREF="#malloc">malloc</A>
|
|
· <A HREF="#mblen">mblen</A>
|
|
· <A HREF="#mbstowcs">mbstowcs</A>
|
|
· <A HREF="#mbtowc">mbtowc</A>
|
|
· <A HREF="#qsort">qsort</A>
|
|
· <A HREF="#rand">rand</A>
|
|
· <A HREF="#realloc">realloc</A>
|
|
· <A HREF="#size_t">size_t</A>
|
|
· <A HREF="#srand">srand</A>
|
|
· <A HREF="#strtod">strtod</A>
|
|
· <A HREF="#strtol">strtol</A>
|
|
· <A HREF="#strtoul">strtoul</A>
|
|
· <A HREF="#system">system</A>
|
|
· <A HREF="#wchar_t">wchar_t</A>
|
|
· <A HREF="#wcstombs">wcstombs</A>
|
|
· <A HREF="#wctomb">wctomb</A>
|
|
</CODE></B></P>
|
|
<HR>
|
|
|
|
<P><CODE>
|
|
#define <A HREF="#EXIT_FAILURE"><B>EXIT_FAILURE</B></A>
|
|
<I><rvalue integer expression></I><BR>
|
|
#define <A HREF="#EXIT_SUCCESS"><B>EXIT_SUCCESS</B></A>
|
|
<I><rvalue integer expression></I><BR>
|
|
#define <A HREF="#MB_CUR_MAX"><B>MB_CUR_MAX</B></A>
|
|
<I><rvalue integer expression >= 1></I><BR>
|
|
#define <A HREF="#NULL"><B>NULL</B></A>
|
|
<I><either 0, 0L, or (void *)0></I> <B>[0 in C++]</B><BR>
|
|
#define <A HREF="#RAND_MAX"><B>RAND_MAX</B></A>
|
|
<I><integer constant expression >= 32,767></I><BR>
|
|
void <A HREF="#abort"><B>abort</B></A>(void);<BR>
|
|
int <A HREF="#abs"><B>abs</B></A>(int i);<BR>
|
|
long <A HREF="#abs"><B>abs</B></A>(long i); <B>[C++ only]</B><BR>
|
|
int <A HREF="#atexit"><B>atexit</B></A>(void (*func)(void));<BR>
|
|
double <A HREF="#atof"><B>atof</B></A>(const char *s);<BR>
|
|
int <A HREF="#atoi"><B>atoi</B></A>(const char *s);<BR>
|
|
long <A HREF="#atol"><B>atol</B></A>(const char *s);<BR>
|
|
void *<A HREF="#bsearch"><B>bsearch</B></A>(const void *key,
|
|
const void *base, size_t nelem, size_t size, int (*cmp)(const void *ck,
|
|
const void *ce));<BR>
|
|
void *<A HREF="#calloc"><B>calloc</B></A>(size_t nelem,
|
|
size_t size);<BR>
|
|
div_t <A HREF="#div"><B>div</B></A>(int numer, int denom);<BR>
|
|
ldiv_t <A HREF="#div"><B>div</B></A>(long numer, long denom);
|
|
<B>[C++ only]</B><BR>
|
|
typedef <I>T</I> <A HREF="#div_t"><B>div_t</B></A>;<BR>
|
|
void <A HREF="#exit"><B>exit</B></A>(int status);<BR>
|
|
void <A HREF="#free"><B>free</B></A>(void *ptr);<BR>
|
|
char *<A HREF="#getenv"><B>getenv</B></A>(const char *name);<BR>
|
|
long <A HREF="#labs"><B>labs</B></A>(long i);<BR>
|
|
ldiv_t <A HREF="#ldiv"><B>ldiv</B></A>(long numer,
|
|
long denom);<BR>
|
|
typedef <I>T</I> <A HREF="#ldiv_t"><B>ldiv_t</B></A>;<BR>
|
|
void *<A HREF="#malloc"><B>malloc</B></A>(size_t size);<BR>
|
|
int <A HREF="#mblen"><B>mblen</B></A>(const char *s,
|
|
size_t n);<BR>
|
|
size_t <A HREF="#mbstowcs"><B>mbstowcs</B></A>(wchar_t *wcs,
|
|
const char *s, size_t n);<BR>
|
|
int <A HREF="#mbtowc"><B>mbtowc</B></A>(wchar_t *pwc,
|
|
const char *s, size_t n);<BR>
|
|
void <A HREF="#qsort"><B>qsort</B></A>(void *base, size_t nelem,
|
|
size_t size, int (*cmp)(const void *e1, const void *e2));<BR>
|
|
int <A HREF="#rand"><B>rand</B></A>(void);<BR>
|
|
void *<A HREF="#realloc"><B>realloc</B></A>(void *ptr,
|
|
size_t size);<BR>
|
|
typedef <I>ui-type</I> <A HREF="#size_t"><B>size_t</B></A>;<BR>
|
|
void <A HREF="#srand"><B>srand</B></A>(unsigned int seed);<BR>
|
|
double <A HREF="#strtod"><B>strtod</B></A>(const char *s,
|
|
char **endptr);<BR>
|
|
long <A HREF="#strtol"><B>strtol</B></A>(const char *s,
|
|
char **endptr, int base);<BR>
|
|
unsigned long <A HREF="#strtoul"><B>strtoul</B></A>(const
|
|
char *s, char **endptr, int base);<BR>
|
|
int <A HREF="#system"><B>system</B></A>(const char *s);<BR>
|
|
typedef <I>i-type</I> <A HREF="#wchar_t"><B>wchar_t</B></A>;
|
|
<B>[keyword in C++]</B><BR>
|
|
size_t <A HREF="#wcstombs"><B>wcstombs</B></A>(char *s,
|
|
const wchar_t *wcs, size_t n);<BR>
|
|
int <A HREF="#wctomb"><B>wctomb</B></A>(char *s,
|
|
wchar_t wchar);<BR>
|
|
</CODE></P>
|
|
|
|
<P>Include the standard header <B><CODE><stdlib.h></CODE></B> to declare an
|
|
assortment of useful functions and to define the macros and types
|
|
that help you use them.</P>
|
|
|
|
<H2><A NAME="EXIT_FAILURE"><CODE>EXIT_FAILURE</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>EXIT_FAILURE</B> <I><rvalue integer expression></I>
|
|
<CODE></P>
|
|
|
|
<P>The macro yields the value of the <CODE>status</CODE> argument to
|
|
<A HREF="#exit"><CODE>exit</CODE></A>
|
|
that reports unsuccessful termination.</P>
|
|
|
|
<H2><A NAME="EXIT_SUCCESS"><CODE>EXIT_SUCCESS</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>EXIT_SUCCESS</B> <I><rvalue integer expression></I>
|
|
<CODE></P>
|
|
|
|
<P>The macro yields the value of the <CODE>status</CODE> argument to
|
|
<A HREF="#exit"><CODE>exit</CODE></A>
|
|
that reports successful termination.</P>
|
|
|
|
<H2><A NAME="MB_CUR_MAX"><CODE>MB_CUR_MAX</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>MB_CUR_MAX</B> <I><rvalue integer expression >= 1></I>
|
|
<CODE></P>
|
|
|
|
<P>The macro yields the maximum number of characters that constitute a
|
|
<A HREF="charset.html#Multibyte Characters" tppabs="http://ccs.ucsd.edu/c/charset.html#Multibyte Characters">multibyte character</A>
|
|
in the current
|
|
<A HREF="locale.html" tppabs="http://ccs.ucsd.edu/c/locale.html">locale</A>. Its value is <=
|
|
<A HREF="limits.html#MB_LEN_MAX" tppabs="http://ccs.ucsd.edu/c/limits.html#MB_LEN_MAX"><CODE>MB_LEN_MAX</CODE></A>.</P>
|
|
|
|
<H2><A NAME="NULL"><CODE>NULL</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>NULL</B> <I><either 0, 0L, or (void *)0></I> <B>[0 in C++]</B>
|
|
<CODE></P>
|
|
|
|
<P>The macro yields a null pointer constant that is usable as an
|
|
<A HREF="express.html#address constant expression" tppabs="http://ccs.ucsd.edu/c/express.html#address constant expression">
|
|
address constant expression</A>.</P>
|
|
|
|
<H2><A NAME="RAND_MAX"><CODE>RAND_MAX</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
#define <B>RAND_MAX</B> <I><integer constant expression >= 32,767></I>
|
|
<CODE></P>
|
|
|
|
<P>The macro yields the maximum value returned by <CODE>rand</CODE>.</P>
|
|
|
|
<H2><A NAME="abort"><CODE>abort</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void <B>abort</B>(void);
|
|
<CODE></P>
|
|
|
|
<P>The function calls
|
|
<CODE><A HREF="signal.html#raise" tppabs="http://ccs.ucsd.edu/c/signal.html#raise">raise</A>(SIGABRT)</CODE>,
|
|
which reports the abort signal,
|
|
<A HREF="signal.html#SIGABRT" tppabs="http://ccs.ucsd.edu/c/signal.html#SIGABRT"><CODE>SIGABRT</CODE></A>.
|
|
Default handling for the abort signal is to cause abnormal
|
|
program termination and report unsuccessful termination to the target
|
|
environment. Whether or not the target environment flushes output
|
|
streams, closes open files, or removes temporary files on abnormal
|
|
termination is implementation defined. If you specify handling that causes
|
|
<A HREF="signal.html#raise" tppabs="http://ccs.ucsd.edu/c/signal.html#raise"><CODE>raise</CODE></A>
|
|
to return control to <CODE>abort</CODE>, the function calls
|
|
<CODE><A HREF="#exit">exit</A>(EXIT_FAILURE)</CODE>,
|
|
to report unsuccessful termination with
|
|
<A HREF="#EXIT_FAILURE"><CODE>EXIT_FAILURE</CODE></A>.
|
|
<CODE>abort</CODE> never returns control to its caller.</P>
|
|
|
|
<H2><A NAME="abs"><CODE>abs</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>abs</B>(int i);<BR>
|
|
long <B>abs</B>(long i); <B>[C++ only]</B>
|
|
<CODE></P>
|
|
|
|
<P>The function returns the absolute value of
|
|
<CODE>i</CODE>, <CODE>|i|</CODE>. The version that accepts
|
|
a <I>long</I> argument behaves the same as
|
|
<A HREF="#abs"><CODE>labs</CODE></A></P>
|
|
|
|
<H2><A NAME="atexit"><CODE>atexit</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>atexit</B>(void (*func)(void));
|
|
<CODE></P>
|
|
|
|
<P>The function registers the function whose address is <CODE>func</CODE>
|
|
to be called by
|
|
<A HREF="#exit"><CODE>exit</CODE></A> (or when
|
|
<A HREF="lib_over.html#main" tppabs="http://ccs.ucsd.edu/c/lib_over.html#main"><CODE>main</CODE></A> returns)
|
|
and returns zero if successful.
|
|
The functions are called in reverse order of registry. You can register at
|
|
least 32 functions.</P>
|
|
|
|
<H2><A NAME="atof"><CODE>atof</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
double <B>atof</B>(const char *s);
|
|
<CODE></P>
|
|
|
|
<P>The function converts the initial characters of the string <CODE>s</CODE>
|
|
to an equivalent value <CODE>x</CODE> of type <I>double</I> and then returns
|
|
<CODE>x.</CODE> The conversion is the same as for
|
|
<CODE><A HREF="#strtod">strtod</A>(s, 0)</CODE>,
|
|
except that a value is not necessarily stored in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A>
|
|
if a conversion error occurs.</P>
|
|
|
|
<H2><A NAME="atoi"><CODE>atoi</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>atoi</B>(const char *s);
|
|
<CODE></P>
|
|
|
|
<P>The function converts the initial characters of the string <CODE>s</CODE>
|
|
to an equivalent value <CODE>x</CODE> of type <I>int</I> and then returns
|
|
<CODE>x.</CODE> The conversion is the same as for
|
|
<CODE>(int)<A HREF="#strtol">strtol</A>(s, 0, 10)</CODE>,
|
|
except that a value is not necessarily stored in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A>
|
|
if a conversion error occurs.</P>
|
|
|
|
<H2><A NAME="atol"><CODE>atol</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
long <B>atol</B>(const char *s);
|
|
<CODE></P>
|
|
|
|
<P>The function converts the initial characters of the string <CODE>s</CODE>
|
|
to an equivalent value <CODE>x</CODE> of type <I>long</I> and then returns
|
|
<CODE>x.</CODE> The conversion is the same as for
|
|
<CODE><A HREF="#strtol">strtol</A>(s, 0, 10)</CODE>,
|
|
except that a value is not necessarily stored in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A>
|
|
if a conversion error occurs.</P>
|
|
|
|
<H2><A NAME="bsearch"><CODE>bsearch</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void *<B>bsearch</B>(const void *key, const void *base, size_t nelem,
|
|
size_t size, int (*cmp)(const void *ck, const void *ce));
|
|
</CODE></P>
|
|
|
|
<P>The function searches an array of ordered values and returns
|
|
the address of an array element that equals the search key <CODE>key</CODE>
|
|
(if one exists); otherwise, it returns a null pointer. The array consists
|
|
of <CODE>nelem</CODE> elements, each of <CODE>size</CODE> bytes,
|
|
beginning with the element whose address is <CODE>base</CODE>.</P>
|
|
|
|
<P><CODE>bsearch</CODE> calls the comparison function whose address is
|
|
<CODE>cmp</CODE> to compare the search key with elements of the array. The
|
|
comparison function must return:</P>
|
|
|
|
<UL>
|
|
<LI>a negative value if the search key <CODE>ck</CODE> is less than the
|
|
array element <CODE>ce</CODE>
|
|
|
|
<LI>zero if the two are equal
|
|
|
|
<LI>a positive value if the search key is greater than the array
|
|
element
|
|
</UL>
|
|
|
|
<P><CODE>bsearch</CODE> assumes that the array elements are in ascending
|
|
order according to the same comparison rules that are used by the
|
|
comparison function.</P>
|
|
|
|
<H2><A NAME="calloc"><CODE>calloc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void *<B>calloc</B>(size_t nelem, size_t size);
|
|
<CODE></P>
|
|
|
|
<P>The function allocates an array object containing <CODE>nelem</CODE>
|
|
elements each of size <CODE>size</CODE>, stores zeros in all bytes of the
|
|
array, and returns the address of the first element of the array if
|
|
successful; otherwise, it returns a null pointer. You can safely convert
|
|
the return value to an object pointer of any type whose size in bytes
|
|
is not greater than <CODE>size</CODE>.</P>
|
|
|
|
<H2><A NAME="div"><CODE>div</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
div_t <B>div</B>(int numer, int denom);<BR>
|
|
ldiv_t <B>div</B>(long numer, long denom); <B>[C++ only]</B>
|
|
<CODE></P>
|
|
|
|
<P>The function divides <CODE>numer</CODE> by <CODE>denom</CODE> and returns
|
|
both quotient and remainder in the structure
|
|
<A HREF="#div_t"><CODE>div_t</CODE></A>
|
|
(or <A HREF="#ldiv_t"><CODE>ldiv_t</CODE></A>)
|
|
result <CODE>x</CODE>, if the quotient can be represented.
|
|
The structure member <CODE>x.quot</CODE>
|
|
is the algebraic quotient truncated toward zero.
|
|
The structure member <CODE>x.rem</CODE> is the remainder, such
|
|
that <CODE>numer == x.quot*denom + x.rem</CODE>.</P>
|
|
|
|
<H2><A NAME="div_t"><CODE>div_t</CODE></A></H2>
|
|
|
|
<PRE>typedef struct {
|
|
int quot, rem;
|
|
} <B>div_t</B>;
|
|
</PRE>
|
|
|
|
<P>The type is the structure type returned by the function
|
|
<A HREF="#div"><CODE>div</CODE></A>.
|
|
The structure contains members that represent the quotient
|
|
(<CODE>quot</CODE>) and remainder (<CODE>rem</CODE>)
|
|
of a signed integer division with operands of type <I>int.</I> The
|
|
members shown above can occur in either order.</P>
|
|
|
|
<H2><A NAME="exit"><CODE>exit</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void <B>exit</B>(int status);
|
|
<CODE></P>
|
|
|
|
<P>The function calls all functions registered by
|
|
<A HREF="#atexit"><CODE>atexit</CODE></A>,
|
|
closes all files, and returns control to the target environment. If
|
|
<CODE>status</CODE> is zero or
|
|
<A HREF="#EXIT_SUCCESS"><CODE>EXIT_SUCCESS</CODE></A>,
|
|
the program reports successful termination. If <CODE>status</CODE> is
|
|
<A HREF="#EXIT_FAILURE"><CODE>EXIT_FAILURE</CODE></A>, the
|
|
program reports unsuccessful termination. An implementation can define
|
|
additional values for <CODE>status</CODE>.</P>
|
|
|
|
<H2><A NAME="free"><CODE>free</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void <B>free</B>(void *ptr);
|
|
<CODE></P>
|
|
|
|
<P>If <CODE>ptr</CODE> is not a null pointer, the function deallocates
|
|
the object whose address is <CODE>ptr</CODE>; otherwise, it does nothing.
|
|
You can deallocate only objects that you first allocate by calling
|
|
<A HREF="#calloc"><CODE>calloc</CODE></A>,
|
|
<A HREF="#malloc"><CODE>malloc</CODE></A>, or
|
|
<A HREF="#realloc"><CODE>realloc</CODE></A>.</P>
|
|
|
|
<H2><A NAME="getenv"><CODE>getenv</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
char *<B>getenv</B>(const char *name);
|
|
<CODE></P>
|
|
|
|
<P>The function searches an
|
|
<B><A NAME="environment list">environment list</A></B>,
|
|
which each implementation defines, for an entry
|
|
whose name matches the string <CODE>name</CODE>. If
|
|
the function finds a match, it returns a pointer to a static-duration
|
|
object that holds the definition associated with the target environment
|
|
name. Otherwise, it returns a null pointer. Do not alter the value
|
|
stored in the object. If you call <CODE>getenv</CODE> again, the value stored
|
|
in the object can change. No target environment names are required
|
|
of all environments.</P>
|
|
|
|
<H2><A NAME="labs"><CODE>labs</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
long <B>labs</B>(long i);
|
|
<CODE></P>
|
|
|
|
<P>The function returns the absolute value of <CODE>i</CODE>,
|
|
<CODE>|i|</CODE>, the same as
|
|
<A HREF="#abs"><CODE>abs</CODE></A>.</P>
|
|
|
|
<H2><A NAME="ldiv"><CODE>ldiv</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
ldiv_t <B>ldiv</B>(long numer, long denom);
|
|
<CODE></P>
|
|
|
|
<P>The function divides <CODE>numer</CODE> by <CODE>denom</CODE> and returns
|
|
both quotient and remainder in the structure
|
|
<A HREF="#ldiv_t"><CODE>ldiv_t</CODE></A>
|
|
result <CODE>x</CODE>, if the quotient can be represented.
|
|
The structure member <CODE>x.quot</CODE>
|
|
is the algebraic quotient truncated toward zero.
|
|
The structure member <CODE>x.rem</CODE> is the remainder, such
|
|
that <CODE>numer == x.quot*denom + x.rem</CODE>.</P>
|
|
|
|
<H2><A NAME="ldiv_t"><CODE>ldiv_t</CODE></A></H2>
|
|
|
|
<PRE>typedef struct {
|
|
long quot, rem;
|
|
} <B>ldiv_t</B>;
|
|
</PRE>
|
|
|
|
<P>The type is the structure type returned by the function
|
|
<A HREF="#ldiv"><CODE>ldiv</CODE></A>.
|
|
The structure contains members that represent the quotient
|
|
(<CODE>quot</CODE>) and remainder (<CODE>rem</CODE>)
|
|
of a signed integer division with operands of type <I>long.</I> The
|
|
members shown above can occur in either order.</P>
|
|
|
|
<H2><A NAME="malloc"><CODE>malloc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void *<B>malloc</B>(size_t size);
|
|
<CODE></P>
|
|
|
|
<P>The function allocates an object of size <CODE>size</CODE>, and returns
|
|
the address of the object if successful; otherwise, it returns a null
|
|
pointer. The values stored in the object are indeterminate. You can
|
|
safely convert the return value to an object pointer of any type whose
|
|
size is not greater than <CODE>size</CODE>.</P>
|
|
|
|
<H2><A NAME="mblen"><CODE>mblen</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>mblen</B>(const char *s, size_t n);
|
|
<CODE></P>
|
|
|
|
<P>If <CODE>s</CODE> is not a null pointer, the function returns the
|
|
number of bytes in the multibyte string <CODE>s</CODE> that constitute the
|
|
next multibyte character, or it returns -1 if the next <CODE>n</CODE>
|
|
(or the remaining) bytes do not constitute a valid multibyte character.
|
|
<CODE>mblen</CODE> does not include the terminating null in the count of
|
|
bytes. The function can use a
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#conversion state">conversion state</A>
|
|
stored in an internal
|
|
static-duration object to determine how
|
|
to interpret the multibyte string.</P>
|
|
|
|
<P>If <CODE>s</CODE> is a null pointer and if multibyte characters have a
|
|
<A HREF="charset.html#state-dependent encoding" tppabs="http://ccs.ucsd.edu/c/charset.html#state-dependent encoding">state-dependent encoding</A>
|
|
in the current
|
|
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A>, the function stores the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversion state</A>
|
|
in its internal static-duration object and
|
|
returns nonzero; otherwise, it returns zero.</P>
|
|
|
|
<H2><A NAME="mbstowcs"><CODE>mbstowcs</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>mbstowcs</B>(wchar_t *wcs, const char *s, size_t n);
|
|
<CODE></P>
|
|
|
|
<P>The function stores a wide character string, in successive elements
|
|
of the array whose first element has the address <CODE>wcs</CODE>,
|
|
by converting, in turn, each of the multibyte characters
|
|
in the multibyte string <CODE>s</CODE>.
|
|
The string begins in the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversion state</A>.
|
|
The function converts each character as if by calling
|
|
<A HREF="#mbtowc"><CODE>mbtowc</CODE></A> (except that
|
|
the internal conversion state stored for that function is unaffected).
|
|
It stores at most <CODE>n</CODE> wide characters, stopping after it stores
|
|
a null wide character. It returns the number of wide characters it
|
|
stores, not counting the null wide character, if all conversions are
|
|
successful; otherwise, it returns -1.</P>
|
|
|
|
<H2><A NAME="mbtowc"><CODE>mbtowc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>mbtowc</B>(wchar_t *pwc, const char *s, size_t n);
|
|
<CODE></P>
|
|
|
|
<P>If <CODE>s</CODE> is not a null pointer,
|
|
the function determines <CODE>x</CODE>,
|
|
the number of bytes in the multibyte string <CODE>s</CODE> that constitute
|
|
the next multibyte character.
|
|
(<CODE>x</CODE> cannot be greater than
|
|
<A HREF="#MB_CUR_MAX"><CODE>MB_CUR_MAX</CODE></A>.)
|
|
If <CODE>pwc</CODE> is not a null pointer, the function converts the next
|
|
multibyte character to its corresponding wide-character value and
|
|
stores that value in <CODE>*pwc</CODE>.
|
|
It then returns <CODE>x,</CODE> or it
|
|
returns -1 if the next <CODE>n</CODE> or the remaining bytes do not
|
|
constitute a valid multibyte character. <CODE>mbtowc</CODE> does not include
|
|
the terminating null in the count of bytes. The function can use a
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#conversion state">conversion state</A>
|
|
stored in an internal static-duration object to determine
|
|
how to interpret the multibyte string.</P>
|
|
|
|
<P>If <CODE>s</CODE> is a null pointer and if multibyte characters have a
|
|
<A HREF="charset.html#state-dependent encoding" tppabs="http://ccs.ucsd.edu/c/charset.html#state-dependent encoding">state-dependent encoding</A>
|
|
in the current
|
|
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A>, the function stores the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversion state</A>
|
|
in its internal static-duration object and
|
|
returns nonzero; otherwise, it returns zero.</P>
|
|
|
|
<H2><A NAME="qsort"><CODE>qsort</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void <B>qsort</B>(void *base, size_t nelem, size_t size,
|
|
int (*cmp)(const void *e1, const void *e2));
|
|
</CODE></P>
|
|
|
|
<P>The function sorts, in place, an array consisting of <CODE>nelem</CODE>
|
|
elements, each of <CODE>size</CODE> bytes, beginning with the element whose
|
|
address is <CODE>base</CODE>. It calls the comparison function whose address
|
|
is <CODE>cmp</CODE> to compare pairs of elements. The comparison function
|
|
must return a negative value if <CODE>e1</CODE> is less than <CODE>e2</CODE>,
|
|
zero if the two are equal, or a positive value if <CODE>e1</CODE> is greater
|
|
than <CODE>e2</CODE>. Two array elements that are equal can appear in the
|
|
sorted array in either order.</P>
|
|
|
|
<H2><A NAME="rand"><CODE>rand</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>rand</B>(void);
|
|
<CODE></P>
|
|
|
|
<P>The function computes a pseudo-random number <CODE>x</CODE> based
|
|
on a seed value stored in an internal static-duration object, alters
|
|
the stored seed value, and returns <CODE>x.</CODE>
|
|
<CODE>x</CODE> is in the interval [0,
|
|
<A HREF="#RAND_MAX"><CODE>RAND_MAX</CODE></A>].</P>
|
|
|
|
<H2><A NAME="realloc"><CODE>realloc</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void *<B>realloc</B>(void *ptr, size_t size);
|
|
<CODE></P>
|
|
|
|
<P>The function allocates an object of size <CODE>size</CODE>, possibly
|
|
obtaining initial stored values from the object
|
|
whose address is <CODE>ptr</CODE>.
|
|
It returns the address of the new object if successful; otherwise,
|
|
it returns a null pointer. You can safely convert the return value
|
|
to an object pointer of any type
|
|
whose size is not greater than <CODE>size</CODE>.</P>
|
|
|
|
<P>If <CODE>ptr</CODE> is not a null pointer, it must be the address
|
|
of an existing object that you first allocate by calling
|
|
<A HREF="#calloc"><CODE>calloc</CODE></A>,
|
|
<A HREF="#malloc"><CODE>malloc</CODE></A>, or
|
|
<CODE>realloc</CODE>. If the existing object is not larger
|
|
than the newly allocated object, <CODE>realloc</CODE> copies the entire
|
|
existing object to the initial part of the allocated object. (The
|
|
values stored in the remainder of the object are indeterminate.) Otherwise,
|
|
the function copies only the initial part of the existing object that
|
|
fits in the allocated object. If <CODE>realloc</CODE> succeeds in allocating
|
|
a new object, it deallocates the existing object. Otherwise, the existing
|
|
object is left unchanged.</P>
|
|
|
|
<P>If <CODE>ptr</CODE> is a null pointer, the function does not store
|
|
initial values in the newly created object.</P>
|
|
|
|
<H2><A NAME="size_t"><CODE>size_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>ui-type</I> <B>size_t</B>;
|
|
<CODE></P>
|
|
|
|
<P>The type is the unsigned integer type <CODE><I>ui-type</I></CODE>
|
|
of an object that you declare to store the result of the
|
|
<A HREF="express.html#sizeof operator" tppabs="http://ccs.ucsd.edu/c/express.html#sizeof operator"><I>sizeof</I></A> operator.</P>
|
|
|
|
<H2><A NAME="srand"><CODE>srand</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
void <B>srand</B>(unsigned int seed);
|
|
<CODE></P>
|
|
|
|
<P>The function stores the seed value <CODE>seed</CODE>
|
|
in a static-duration object that
|
|
<A HREF="#rand"><CODE>rand</CODE></A>
|
|
uses to compute a pseudo-random number. From a given seed value,
|
|
that function always generates the same sequence of return
|
|
values. The program behaves as if the target environment calls
|
|
<CODE>srand(1)</CODE> at program startup.</P>
|
|
|
|
<H2><A NAME="strtod"><CODE>strtod</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
double <B>strtod</B>(const char *s, char **endptr);
|
|
<CODE></P>
|
|
|
|
<P>The function converts the initial characters of the string <CODE>s</CODE>
|
|
to an equivalent value <CODE>x</CODE> of type <I>double.</I>
|
|
If <CODE>endptr</CODE> is not a null pointer,
|
|
the function stores a pointer to the unconverted
|
|
remainder of the string in <CODE>*endptr</CODE>. The function then returns
|
|
<CODE>x</CODE>.</P>
|
|
|
|
<P>The initial characters of the string <CODE>s</CODE> must consist of
|
|
zero or more characters for which
|
|
<A HREF="ctype.html#isspace" tppabs="http://ccs.ucsd.edu/c/ctype.html#isspace"><CODE>isspace</CODE></A> returns nonzero,
|
|
followed by the longest sequence of one or more characters that match
|
|
the pattern:</P>
|
|
|
|
<P><IMG SRC="strtod.gif" tppabs="http://ccs.ucsd.edu/c/gif/strtod.gif"></P>
|
|
|
|
<P>Here, a <CODE><I>point</I></CODE> is the
|
|
<A HREF="locale.html#decimal_point" tppabs="http://ccs.ucsd.edu/c/locale.html#decimal_point">decimal-point</A>
|
|
character for the current
|
|
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A>.
|
|
(It is the dot (<CODE>.</CODE>) in the
|
|
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale.)
|
|
If the string <CODE>s</CODE> matches this pattern, its equivalent value
|
|
is the decimal integer represented by any digits to the left of the
|
|
<CODE><I>point</I></CODE>, plus the decimal fraction
|
|
represented by any digits to the right of the <CODE><I>point</I></CODE>,
|
|
times 10 raised to the signed decimal integer power
|
|
that follows an optional <CODE>e</CODE> or <CODE>E</CODE>. A leading
|
|
minus sign negates the value. In locales other than the
|
|
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale,
|
|
<CODE>strtod</CODE> can define additional patterns as well.</P>
|
|
|
|
<P>If the string <CODE>s</CODE> does not match a valid pattern, the value
|
|
stored in <CODE>*endptr</CODE> is <CODE>s</CODE>,
|
|
and <CODE>x</CODE> is zero. If a
|
|
<A HREF="math.html#range error" tppabs="http://ccs.ucsd.edu/c/math.html#range error">range error</A> occurs,
|
|
<CODE>strtod</CODE> behaves exactly as the functions declared in
|
|
<A HREF="math.html#<math.h>" tppabs="http://ccs.ucsd.edu/c/math.html#<math.h>"><CODE><math.h></CODE></A>.</P>
|
|
|
|
<H2><A NAME="strtol"><CODE>strtol</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
long <B>strtol</B>(const char *s, char **endptr, int base);
|
|
<CODE></P>
|
|
|
|
<P>The function converts the initial characters of the string <CODE>s</CODE>
|
|
to an equivalent value <CODE>x</CODE> of type <I>long.</I>
|
|
If <CODE>endptr</CODE> is not a null pointer,
|
|
it stores a pointer to the unconverted remainder
|
|
of the string in <CODE>*endptr</CODE>.
|
|
The function then returns <CODE>x</CODE>.</P>
|
|
|
|
<P>The initial characters of the string <CODE>s</CODE> must consist of
|
|
zero or more characters for which
|
|
<A HREF="ctype.html#isspace" tppabs="http://ccs.ucsd.edu/c/ctype.html#isspace"><CODE>isspace</CODE></A> returns nonzero,
|
|
followed by the longest sequence of one or more characters that match
|
|
the pattern:</P>
|
|
|
|
<P><IMG SRC="strtol.gif" tppabs="http://ccs.ucsd.edu/c/gif/strtol.gif"></P>
|
|
|
|
<P>The function accepts the sequences
|
|
<CODE>0x</CODE> or <CODE>0X</CODE> only
|
|
when <CODE>base</CODE> equals zero or 16.
|
|
The letters <CODE>a-z</CODE> or <CODE>A-Z</CODE>
|
|
represent digits in the range [10, 36).
|
|
If <CODE>base</CODE> is in the range
|
|
[2, 36], the function accepts only digits
|
|
with values less than <CODE>base</CODE>.
|
|
If <CODE>base</CODE> == 0, then a leading <CODE>0x</CODE> or <CODE>0X</CODE>
|
|
(after any sign) indicates a hexadecimal (base 16) integer, a leading
|
|
<CODE>0</CODE> indicates an octal (base 8) integer, and any other valid
|
|
pattern indicates a decimal (base 10) integer.</P>
|
|
|
|
<P>If the string <CODE>s</CODE> matches this pattern, its equivalent
|
|
value is the signed integer of the appropriate base represented by
|
|
the digits that match the pattern. (A leading minus sign negates the
|
|
value.) In locales other than the
|
|
<A HREF="locale.html#C locale" tppabs="http://ccs.ucsd.edu/c/locale.html#C locale"><CODE>"C"</CODE></A> locale,
|
|
<CODE>strtol</CODE> can define additional patterns as well.</P>
|
|
|
|
<P>If the string <CODE>s</CODE> does not match a valid pattern, the value
|
|
stored in <CODE>*endptr</CODE> is <CODE>s</CODE>,
|
|
and <CODE>x</CODE> is zero. If the
|
|
equivalent value is too large to represent as type <I>long,</I>
|
|
<CODE>strtol</CODE> stores the value of
|
|
<A HREF="errno.html#ERANGE" tppabs="http://ccs.ucsd.edu/c/errno.html#ERANGE"><CODE>ERANGE</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A>
|
|
and returns either
|
|
<A HREF="limits.html#LONG_MAX" tppabs="http://ccs.ucsd.edu/c/limits.html#LONG_MAX"><CODE>LONG_MAX</CODE></A>,
|
|
if <CODE>x</CODE> is positive, or
|
|
<A HREF="limits.html#LONG_MIN" tppabs="http://ccs.ucsd.edu/c/limits.html#LONG_MIN"><CODE>LONG_MIN</CODE></A>,
|
|
if <CODE>x</CODE> is negative.</P>
|
|
|
|
<H2><A NAME="strtoul"><CODE>strtoul</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
unsigned long <B>strtoul</B>(const char *s, char **endptr, int base);
|
|
<CODE></P>
|
|
|
|
<P>The function converts the initial characters of the string <CODE>s</CODE>
|
|
to an equivalent value <CODE>x</CODE> of type <I>unsigned long.</I>
|
|
If <CODE>endptr</CODE> is not a null pointer,
|
|
it stores a pointer to the unconverted remainder
|
|
of the string in <CODE>*endptr</CODE>.
|
|
The function then returns <CODE>x</CODE>.</P>
|
|
|
|
<P><CODE>strtoul</CODE> converts strings exactly as does
|
|
<A HREF="#strtol"><CODE>strtol</CODE></A>,
|
|
but reports a range error only if the equivalent value is too large
|
|
to represent as type <I>unsigned long.</I>
|
|
In this case, <CODE>strtoul</CODE> stores the value of
|
|
<A HREF="errno.html#ERANGE" tppabs="http://ccs.ucsd.edu/c/errno.html#ERANGE"><CODE>ERANGE</CODE></A> in
|
|
<A HREF="errno.html#errno" tppabs="http://ccs.ucsd.edu/c/errno.html#errno"><CODE>errno</CODE></A> and returns
|
|
<A HREF="limits.html#ULONG_MAX" tppabs="http://ccs.ucsd.edu/c/limits.html#ULONG_MAX"><CODE>ULONG_MAX</CODE></A>.</P>
|
|
|
|
<H2><A NAME="system"><CODE>system</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>system</B>(const char *s);
|
|
<CODE></P>
|
|
|
|
<P>If <CODE>s</CODE> is not a null pointer, the function passes the string
|
|
<CODE>s</CODE> to be executed by a
|
|
<B><A NAME="command processor">command processor</B>, supplied by
|
|
the target environment, and returns the status reported by the command
|
|
processor. If <CODE>s</CODE> is a null pointer, the function returns nonzero
|
|
only if the target environment supplies a command processor. Each
|
|
implementation defines what strings its command processor accepts.</P>
|
|
|
|
<H2><A NAME="wchar_t"><CODE>wchar_t</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
typedef <I>i-type</I> <B>wchar_t</B>; <B>[keyword in C++]</B>
|
|
<CODE></P>
|
|
|
|
<P>The type is the integer type <CODE><I>i-type</I></CODE> of a
|
|
<A HREF="charset.html#wide-character constant" tppabs="http://ccs.ucsd.edu/c/charset.html#wide-character constant">
|
|
wide-character constant</A>, such as <CODE>L'X'</CODE>.
|
|
You declare an object of type <CODE>wchar_t</CODE> to hold a
|
|
<A HREF="charset.html#Wide-Character Encoding" tppabs="http://ccs.ucsd.edu/c/charset.html#Wide-Character Encoding">wide character</A>.</P>
|
|
|
|
<H2><A NAME="wcstombs"><CODE>wcstombs</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
size_t <B>wcstombs</B>(char *s, const wchar_t *wcs, size_t n);
|
|
<CODE></P>
|
|
|
|
<P>The function stores a multibyte string, in successive elements
|
|
of the array whose first element has the address <CODE>s</CODE>,
|
|
by converting in turn each of the wide characters
|
|
in the string <CODE>wcs</CODE>. The multibyte string begins in the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversion state</A>.
|
|
The function converts each wide character as if by calling
|
|
<A HREF="#wctomb"><CODE>wctomb</CODE></A> (except that the
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#conversion state">conversion state</A>
|
|
stored for that function is unaffected). It stores no
|
|
more than <CODE>n</CODE> bytes, stopping after it stores a null byte. It
|
|
returns the number of bytes it stores, not counting the null byte,
|
|
if all conversions are successful; otherwise, it returns -1.</P>
|
|
|
|
<H2><A NAME="wctomb"><CODE>wctomb</CODE></A></H2>
|
|
|
|
<P><CODE>
|
|
int <B>wctomb</B>(char *s, wchar_t wchar);
|
|
<CODE></P>
|
|
|
|
<P>If <CODE>s</CODE> is not a null pointer,
|
|
the function determines <CODE>x,</CODE>
|
|
the number of bytes needed to represent
|
|
the multibyte character corresponding
|
|
to the wide character <CODE>wchar</CODE>.
|
|
<CODE>x</CODE> cannot exceed
|
|
<A HREF="#MB_CUR_MAX"><CODE>MB_CUR_MAX</CODE></A>.
|
|
The function converts <CODE>wchar</CODE> to its corresponding multibyte
|
|
character, which it stores in successive elements of the array whose
|
|
first element has the address <CODE>s</CODE>.
|
|
It then returns <CODE>x,</CODE> or it returns -1
|
|
if <CODE>wchar</CODE> does not correspond to a valid
|
|
multibyte character. <CODE>wctomb</CODE> includes the terminating
|
|
null byte in the count of bytes. The function can use a
|
|
<A HREF="charset.html#conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#conversion state">conversion state</A>
|
|
stored in a static-duration object to determine how to interpret the
|
|
multibyte character string.</P>
|
|
|
|
<P>If <CODE>s</CODE> is a null pointer and if multibyte characters have a
|
|
<A HREF="charset.html#state-dependent encoding" tppabs="http://ccs.ucsd.edu/c/charset.html#state-dependent encoding">state-dependent encoding</A>
|
|
in the current
|
|
<A HREF="locale.html#locale" tppabs="http://ccs.ucsd.edu/c/locale.html#locale">locale</A>, the function stores the
|
|
<A HREF="charset.html#initial conversion state" tppabs="http://ccs.ucsd.edu/c/charset.html#initial conversion state">initial conversion state</A>
|
|
in its static-duration object and returns
|
|
nonzero; otherwise, it returns zero.</P>
|
|
|
|
<HR>
|
|
<P>See also the
|
|
<B><A HREF="index.html#Table of Contents" tppabs="http://ccs.ucsd.edu/c/index.html#Table of Contents">Table of Contents</A></B> and the
|
|
<B><A HREF="_index.html" tppabs="http://ccs.ucsd.edu/c/_index.html">Index</A></B>.</P>
|
|
|
|
<P><I>
|
|
<A HREF="crit_pb.html" tppabs="http://ccs.ucsd.edu/c/crit_pb.html">Copyright</A> © 1989-1996
|
|
by P.J. Plauger and Jim Brodie. All rights reserved.</I></P>
|
|
|
|
</BODY></HTML>
|