370 lines
17 KiB
HTML
370 lines
17 KiB
HTML
<HTML><HEAD><TITLE>C Library Overview</TITLE></HEAD><BODY BGCOLOR="#FFFFFF">
|
||
|
||
<H1><A NAME="C Library Overview">C Library Overview</A></H1><HR>
|
||
|
||
<P><B><A HREF="#Using Standard C Headers">Using Standard C Headers</A>
|
||
· <A HREF="#C Library Conventions">C Library Conventions</A>
|
||
· <A HREF="#C Program Startup and Termination">
|
||
· Program Startup and Termination</A>
|
||
</B></P>
|
||
<HR>
|
||
|
||
<P>All Standard C library entities are declared or defined in one or more
|
||
<B><A NAME="standard headers">standard headers</A></B>.
|
||
To make use of a library entity in a program, write an
|
||
<A HREF="preproc.html#include directive" tppabs="http://ccs.ucsd.edu/c/preproc.html#include directive"><I>include</I> directive</A>
|
||
that names the relevant
|
||
<B><A NAME="standard header">standard header</A></B>.
|
||
The full set of 18 Standard C headers constitutes a
|
||
<B><A NAME="hosted implementation">hosted implementation</A></B>:
|
||
<CODE><A HREF="assert.html" tppabs="http://ccs.ucsd.edu/c/assert.html"><assert.h></A></CODE>,
|
||
<CODE><A HREF="ctype.html" tppabs="http://ccs.ucsd.edu/c/ctype.html"><ctype.h></A></CODE>,
|
||
<CODE><A HREF="errno.html" tppabs="http://ccs.ucsd.edu/c/errno.html"><errno.h></A></CODE>,
|
||
<CODE><A HREF="float.html" tppabs="http://ccs.ucsd.edu/c/float.html"><float.h></A></CODE>,
|
||
<CODE><A HREF="iso646.html" tppabs="http://ccs.ucsd.edu/c/iso646.html"><iso646.h></A></CODE>,
|
||
<CODE><A HREF="limits.html" tppabs="http://ccs.ucsd.edu/c/limits.html"><limits.h></A></CODE>,
|
||
<CODE><A HREF="locale.html" tppabs="http://ccs.ucsd.edu/c/locale.html"><locale.h></A></CODE>,
|
||
<CODE><A HREF="math.html" tppabs="http://ccs.ucsd.edu/c/math.html"><math.h></A></CODE>,
|
||
<CODE><A HREF="setjmp.html" tppabs="http://ccs.ucsd.edu/c/setjmp.html"><setjmp.h></A></CODE>,
|
||
<CODE><A HREF="signal.html" tppabs="http://ccs.ucsd.edu/c/signal.html"><signal.h></A></CODE>,
|
||
<CODE><A HREF="stdarg.html" tppabs="http://ccs.ucsd.edu/c/stdarg.html"><stdarg.h></A></CODE>,
|
||
<CODE><A HREF="stddef.html" tppabs="http://ccs.ucsd.edu/c/stddef.html"><stddef.h></A></CODE>,
|
||
<CODE><A HREF="stdio.html" tppabs="http://ccs.ucsd.edu/c/stdio.html"><stdio.h></A></CODE>,
|
||
<CODE><A HREF="stdlib.html" tppabs="http://ccs.ucsd.edu/c/stdlib.html"><stdlib.h></A></CODE>,
|
||
<CODE><A HREF="string.html" tppabs="http://ccs.ucsd.edu/c/string.html"><string.h></A></CODE>,
|
||
<CODE><A HREF="time.html" tppabs="http://ccs.ucsd.edu/c/time.html"><time.h></A></CODE>,
|
||
<CODE><A HREF="wchar.html" tppabs="http://ccs.ucsd.edu/c/wchar.html"><wchar.h></A></CODE>, and
|
||
<CODE><A HREF="wctype.html" tppabs="http://ccs.ucsd.edu/c/wctype.html"><wctype.h></A></CODE>.</P>
|
||
|
||
<P>(The headers
|
||
<CODE><A HREF="iso646.html" tppabs="http://ccs.ucsd.edu/c/iso646.html"><iso646.h></A></CODE>,
|
||
<CODE><A HREF="wchar.html" tppabs="http://ccs.ucsd.edu/c/wchar.html"><wchar.h></A></CODE>, and
|
||
<CODE><A HREF="wctype.html" tppabs="http://ccs.ucsd.edu/c/wctype.html"><wctype.h></A></CODE> are added with
|
||
<B><A NAME="Amendment 1">Amendment 1</A></B>, an addition
|
||
to the C Standard published in 1995.)</P>
|
||
|
||
<P>A <B><A NAME="freestanding implementation">freestanding implementation</B>
|
||
of Standard C provides only a subset of these standard headers:
|
||
<CODE><A HREF="float.html" tppabs="http://ccs.ucsd.edu/c/float.html"><float.h></A></CODE>,
|
||
<CODE><A HREF="limits.html" tppabs="http://ccs.ucsd.edu/c/limits.html"><limits.h></A></CODE>,
|
||
<CODE><A HREF="stdarg.html" tppabs="http://ccs.ucsd.edu/c/stdarg.html"><stdarg.h></A></CODE>, and
|
||
<CODE><A HREF="stddef.html" tppabs="http://ccs.ucsd.edu/c/stddef.html"><stddef.h></A></CODE>.
|
||
Each freestanding implementation defines:</P>
|
||
|
||
<UL>
|
||
<LI>how it starts the program
|
||
|
||
<LI>what happens when the program terminates
|
||
|
||
<LI>what library functions (if any) it provides
|
||
</UL>
|
||
|
||
<H2><A NAME="Using Standard C Headers">Using Standard C Headers</A></H2>
|
||
|
||
<P>You include the contents of a standard header by naming it in an
|
||
<A HREF="preproc.html#include directive" tppabs="http://ccs.ucsd.edu/c/preproc.html#include directive"><I>include</I> directive</A>,
|
||
as in:</P>
|
||
|
||
<PRE>
|
||
#include <stdio.h> /* include I/O facilities */</PRE>
|
||
|
||
<P>You can include the standard headers in any order, a standard
|
||
header more than once, or two or more standard headers that define
|
||
the same macro or the same type.
|
||
Do not include a standard header within a declaration. Do not
|
||
define macros that have the same names as keywords before you include
|
||
a standard header.</P>
|
||
|
||
<P>A standard header never includes another standard header. A
|
||
standard header declares or defines only the entities described for
|
||
it in this document.</P>
|
||
|
||
<P>Every function in the library is declared in a standard header.
|
||
The standard header can also provide a
|
||
<B><A NAME="masking macro">masking macro</A></B>, with the same name as
|
||
the function, that masks the function declaration and achieves the
|
||
same effect. The macro typically expands to an expression that executes
|
||
faster than a call to the function of the same name. The macro can,
|
||
however, cause confusion when you are tracing or debugging the program.
|
||
So you can use a standard header in two ways to declare or define
|
||
a library function. To take advantage of any macro version, include
|
||
the standard header so that each apparent call to the function can
|
||
be replaced by a macro expansion.</P>
|
||
|
||
<P>For example:</P>
|
||
|
||
<PRE>
|
||
#include <ctype.h>
|
||
char *skip_space(char *p)
|
||
{
|
||
while (isspace(*p)) <B>can be a macro</B>
|
||
++p;
|
||
return (p);
|
||
}</PRE>
|
||
|
||
<P>To ensure that the program calls the actual library function,
|
||
include the standard header and remove any macro definition with an
|
||
<A HREF="preproc.html#undef directive" tppabs="http://ccs.ucsd.edu/c/preproc.html#undef directive"><I>undef</I> directive</A>.</P>
|
||
|
||
<P>For example:</P>
|
||
|
||
<PRE>
|
||
#include <ctype.h>
|
||
#undef isspace <B>remove any macro definition</B>
|
||
int f(char *p) {
|
||
while (isspace(*p)) <B>must be a function</B>
|
||
++p;</PRE>
|
||
|
||
<P>You can use many functions in the library without including
|
||
a standard header (although this practice is not recommended). If
|
||
you do not need defined macros or types to declare and call the function,
|
||
you can simply declare the function as it appears in this chapter.
|
||
Again, you have two choices. You can declare the function explicitly.</P>
|
||
|
||
<P>For example:</P>
|
||
|
||
<PRE>
|
||
double sin(double x); <B>declared in <math.h></B>
|
||
y = rho * sin(theta);</PRE>
|
||
|
||
<P>Or you can declare the function implicitly if it is a function
|
||
returning <I>int</I> with a fixed number of arguments, as in:</P>
|
||
|
||
<PRE>
|
||
n = atoi(str); <B>declared in <stdlib.h></B></PRE>
|
||
|
||
<P>If the function has a
|
||
<A HREF="stdarg.html#varying number of arguments" tppabs="http://ccs.ucsd.edu/c/stdarg.html#varying number of arguments">varying number
|
||
of arguments</A>, such as
|
||
<A HREF="stdio.html#printf" tppabs="http://ccs.ucsd.edu/c/stdio.html#printf"><CODE>printf</CODE></A>,
|
||
you must declare it explicitly: Either include the standard header
|
||
that declares it or write an explicit declaration.</P>
|
||
|
||
<P>Note also that you cannot define a macro or type definition
|
||
without including its standard header
|
||
because each of these varies among implementations.
|
||
</P>
|
||
|
||
<H2><A NAME="C Library Conventions">C Library Conventions</A></H2>
|
||
|
||
<P>A library macro that
|
||
<A HREF="#masking macro">masks</A>
|
||
a function declaration expands to
|
||
an expression that evaluates each of its arguments once (and only
|
||
once). Arguments that have
|
||
<A HREF="function.html#side-effects context" tppabs="http://ccs.ucsd.edu/c/function.html#side-effects context">side effects</A>
|
||
evaluate the same way whether the expression executes
|
||
the macro expansion or calls the function.
|
||
Macros for the functions
|
||
<A HREF="stdio.html#getc" tppabs="http://ccs.ucsd.edu/c/stdio.html#getc"><CODE>getc</CODE></A> and
|
||
<A HREF="stdio.html#putc" tppabs="http://ccs.ucsd.edu/c/stdio.html#putc"><CODE>putc</CODE></A>
|
||
are explicit exceptions to this rule. Their <CODE>stream</CODE>
|
||
arguments can be evaluated more than once. Avoid argument expressions
|
||
that have side effects with these macros.</P>
|
||
|
||
<P>A library function that alters a value stored in memory assumes
|
||
that the function accesses no other objects that overlap the
|
||
object whose stored value it alters. You cannot depend on consistent
|
||
behavior from a library function that accesses and alters the same
|
||
storage via different arguments. The function
|
||
<A HREF="string.html#memmove" tppabs="http://ccs.ucsd.edu/c/string.html#memmove"><CODE>memmove</CODE></A>
|
||
is an explicit exception to this rule. Its arguments
|
||
can point at objects that overlap.</P>
|
||
|
||
<P>An implementation has a set of
|
||
<B><A NAME="reserved names">reserved names</A></B> that it
|
||
can use for its own purposes. All the library names described in this
|
||
document are, of course, reserved for the library. Don't define
|
||
macros with the same names. Don't try to supply your own definition
|
||
of a library function, unless this document explicitly says you can
|
||
(only in C++). An unauthorized replacement may be successful on some
|
||
implementations and not on others. Names that begin with
|
||
two underscores, such as <CODE>__STDIO</CODE>, and names that
|
||
begin with an underscore followed by an upper case letter, such as
|
||
<CODE>_Entry</CODE>, can be used as macro names, whether or not
|
||
a translation unit explicitly includes any standard headers.
|
||
Names that begin with an underscore can be defined with external
|
||
linkage. Avoid writing such names in a program
|
||
that you wish to keep maximally portable.</P>
|
||
|
||
<P>Some library functions operate on
|
||
<B><A NAME="C string">C strings</A></B>, or pointers to
|
||
<A HREF="charset.html#null-terminated string" tppabs="http://ccs.ucsd.edu/c/charset.html#null-terminated string">null-terminated strings</A>.
|
||
You designate a C string
|
||
that can be altered by an argument expression that has type
|
||
<I>pointer to char</I> (or type <I>array of char,</I> which converts to
|
||
<I>pointer to char</I> in an argument expression).
|
||
You designate a C string that cannot be altered by an argument
|
||
expression that has type <I>pointer to const char</I> (or type
|
||
<I>const array of char</I>).
|
||
In any case, the value of the expression is
|
||
the address of the first byte in an array object.
|
||
The first successive element of the array that has a
|
||
<A HREF="charset.html#null character" tppabs="http://ccs.ucsd.edu/c/charset.html#null character">null character</A>
|
||
stored in it marks the end of the C string.</P>
|
||
|
||
<UL>
|
||
<LI>A
|
||
<B><A NAME="filename">filename</A></B> is a string
|
||
whose contents meet the requirements
|
||
of the target environment for naming files.
|
||
|
||
<LI>A
|
||
<B><A NAME="multibyte string">multibyte string</A></B>
|
||
is composed of zero or more
|
||
<A HREF="charset.html#Multibyte Characters" tppabs="http://ccs.ucsd.edu/c/charset.html#Multibyte Characters">multibyte characters</A>,
|
||
followed by a
|
||
<A HREF="charset.html#null character" tppabs="http://ccs.ucsd.edu/c/charset.html#null character">null character</A>.
|
||
|
||
<LI>A
|
||
<B><A NAME="wide-character string">wide-character string</A></B>
|
||
is composed of zero or more
|
||
<A HREF="charset.html#Wide-Character Encoding" tppabs="http://ccs.ucsd.edu/c/charset.html#Wide-Character Encoding">wide characters</A>
|
||
(stored in an array of
|
||
<A HREF="stddef.html#wchar_t" tppabs="http://ccs.ucsd.edu/c/stddef.html#wchar_t"><CODE>wchar_t</CODE></A>), followed by a
|
||
<A HREF="charset.html#null wide character" tppabs="http://ccs.ucsd.edu/c/charset.html#null wide character">null wide character</A>.
|
||
</UL>
|
||
|
||
<P>If an argument to a library function has a pointer type, then
|
||
the value of the argument expression must be a valid address for an
|
||
object of its type. This is true even if the library function has
|
||
no need to access an object by using the pointer argument. An explicit
|
||
exception is when the description of the library function spells out
|
||
what happens when you use a null pointer.</P>
|
||
|
||
<P>Some examples are:</P>
|
||
|
||
<PRE>
|
||
strcpy(s1, 0) <B>is INVALID</B>
|
||
memcpy(s1, 0, 0) <B>is UNSAFE</B>
|
||
realloc(0, 50) <B>is the same as malloc(50)</B></PRE>
|
||
|
||
<H2><A NAME="C Program Startup and Termination">
|
||
Program Startup and Termination</A></H2>
|
||
|
||
<P>The target environment controls the execution of the program
|
||
(in contrast to the translator part of the implementation, which prepares
|
||
the parts of the program for execution). The target environment passes
|
||
control to the program at
|
||
<B><A NAME="program startup">program startup</A></B>
|
||
by calling the function
|
||
<B><A NAME="main"><CODE>main</CODE></A></B>
|
||
that you define as part of the program.
|
||
<B><A NAME="program arguments">Program arguments</A></B> are
|
||
<A HREF="#C string">C strings</A>
|
||
that the target environment provides, such as text from the
|
||
<B><A NAME="command line">command line</A></B>
|
||
that you type to invoke the program. If the program
|
||
does not need to access program arguments, you can define <CODE>main</CODE>
|
||
as:</P>
|
||
|
||
<PRE>
|
||
extern int main(void)
|
||
{ <I><body of main></I> }</PRE>
|
||
|
||
<P>If the program uses program arguments, you define <CODE>main</CODE>
|
||
as:</P>
|
||
|
||
<PRE>
|
||
extern int main(int argc, char **argv)
|
||
{ <I><body of main></I> }</PRE>
|
||
|
||
<P>You can omit either or both of <CODE>extern int</CODE>, since
|
||
these are the default storage class and type for a function
|
||
definition. For program arguments:</P>
|
||
|
||
<UL>
|
||
<LI><CODE>argc</CODE> is a value (always greater than zero) that specifies
|
||
the number of program arguments.
|
||
|
||
<LI><CODE>argv[0]</CODE> designates the first element of an array of
|
||
<A HREF="#C string">C strings</A>.
|
||
<CODE>argv[argc]</CODE> designates the last element of the array, whose
|
||
stored value is a null pointer.
|
||
</UL>
|
||
|
||
<P>For example, if you invoke a program by typing:</P>
|
||
|
||
<PRE>
|
||
echo hello</PRE>
|
||
|
||
<P>a target environment can call <CODE>main</CODE> with:</P>
|
||
|
||
<UL>
|
||
<LI>The value 2 for <CODE>argc</CODE>.
|
||
|
||
<LI>The address of an array object containing <CODE>"echo"</CODE> stored
|
||
in <CODE>argv[0]</CODE>.
|
||
|
||
<LI>The address of an array object containing <CODE>"hello"</CODE> stored
|
||
in <CODE>argv[1]</CODE>.
|
||
|
||
<LI>A null pointer stored in <CODE>argv[2]</CODE>.
|
||
</UL>
|
||
|
||
<P><CODE>argv[0]</CODE> is the name used to invoke the program. The target
|
||
environment can replace this name with a
|
||
<A NAME="null string">null string</A> (<CODE>""</CODE>).
|
||
The program can alter the values stored in <CODE>argc</CODE>,
|
||
in <CODE>argv</CODE>, and in the array objects
|
||
whose addresses are stored in <CODE>argv</CODE>.</P>
|
||
|
||
<P>Before the target environment calls <CODE>main</CODE>, it stores the
|
||
initial values you specify in all objects that have static duration.
|
||
It also opens three files, controlled by the text-stream objects designated
|
||
by the macros:</P>
|
||
|
||
<UL>
|
||
<LI><B><A HREF="stdio.html#stdin" tppabs="http://ccs.ucsd.edu/c/stdio.html#stdin"><CODE>stdin</CODE></A></B> --
|
||
for <B><A NAME="standard input">standard input</A></B>
|
||
|
||
<LI><B><A HREF="stdio.html#stdout" tppabs="http://ccs.ucsd.edu/c/stdio.html#stdout"><CODE>stdout</CODE></A></B> --
|
||
for <B><A NAME="standard output">standard output</A></B>
|
||
|
||
<LI><B><A HREF="stdio.html#stderr" tppabs="http://ccs.ucsd.edu/c/stdio.html#stderr"><CODE>stderr</CODE></A></B> --
|
||
for <B><A NAME="standard error">standard error</A></B> output
|
||
</UL>
|
||
|
||
<P>If <CODE>main</CODE> returns to its caller, the target environment calls
|
||
<A HREF="stdlib.html#exit" tppabs="http://ccs.ucsd.edu/c/stdlib.html#exit"><CODE>exit</CODE></A>
|
||
with the value returned from <CODE>main</CODE> as the status argument to
|
||
<A HREF="stdlib.html#exit" tppabs="http://ccs.ucsd.edu/c/stdlib.html#exit"><CODE>exit</CODE></A>. If the
|
||
<A HREF="function.html#Return Statement" tppabs="http://ccs.ucsd.edu/c/function.html#Return Statement"><I>return</I> statement</A> that
|
||
the program executes has no expression, the status argument is undefined.
|
||
This is the case if the program executes the implied
|
||
<A HREF="function.html#Return Statement" tppabs="http://ccs.ucsd.edu/c/function.html#Return Statement"><I>return</I> statement</A>
|
||
at the end of the function definition.</P>
|
||
|
||
<P>You can also call
|
||
<A HREF="stdlib.html#exit" tppabs="http://ccs.ucsd.edu/c/stdlib.html#exit"><CODE>exit</CODE></A>
|
||
directly from any expression within the program. In both cases,
|
||
<A HREF="stdlib.html#exit" tppabs="http://ccs.ucsd.edu/c/stdlib.html#exit"><CODE>exit</CODE></A>
|
||
calls all functions registered with
|
||
<A HREF="stdlib.html#atexit" tppabs="http://ccs.ucsd.edu/c/stdlib.html#atexit"><CODE>atexit</CODE></A>
|
||
in reverse order of registry and then begins
|
||
<B><A NAME="program termination">program termination</A></B>.
|
||
At program termination, the target environment closes
|
||
all open files, removes any temporary files that you created by calling
|
||
<A HREF="stdio.html#tmpfile" tppabs="http://ccs.ucsd.edu/c/stdio.html#tmpfile"><CODE>tmpfile</CODE></A>,
|
||
and then returns control to the invoker, using the
|
||
status argument value to determine the termination status to report
|
||
for the program.</P>
|
||
|
||
<P>The program can terminate abnormally by calling
|
||
<A HREF="stdlib.html#abort" tppabs="http://ccs.ucsd.edu/c/stdlib.html#abort"><CODE>abort</CODE></A>,
|
||
for example. Each implementation defines whether it closes files,
|
||
whether it removes temporary files, and what termination status it
|
||
reports when a program terminates abnormally.</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>
|
||
|