libc.sgml

eCos操作系统源码

<!-- {{{ Banner                         -->

<!-- =============================================================== -->
<!--                                                                 -->
<!--     libc.sgml                                                   -->
<!--                                                                 -->
<!--     eCos C Library                                              -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- ####COPYRIGHTBEGIN####                                          -->
<!--                                                                 -->
<!-- =============================================================== -->
<!-- Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.  -->
<!-- This material may be distributed only subject to the terms      -->
<!-- and conditions set forth in the Open Publication License, v1.0  -->
<!-- or later (the latest version is presently available at          -->
<!-- http://www.opencontent.org/openpub/)                            -->
<!-- Distribution of the work or derivative of the work in any       -->
<!-- standard (paper) book form is prohibited unless prior           -->
<!-- permission obtained from the copyright holder                   -->
<!-- =============================================================== -->
<!--                                                                 -->      
<!-- ####COPYRIGHTEND####                                            -->
<!-- =============================================================== -->
<!-- #####DESCRIPTIONBEGIN####                                       -->
<!--                                                                 -->
<!-- ####DESCRIPTIONEND####                                          -->
<!-- =============================================================== -->

<!-- }}} -->

<PART id="libc">
<TITLE>The ISO Standard C and Math Libraries</TITLE>
<CHAPTER id="c-and-math-library-overview">
<TITLE><!-- <xref> -->C and math library overview</TITLE>
<anchor id="iso-c-and-math-libraries">
<PARA><EMPHASIS>eCos</EMPHASIS> provides compatibility with the
	ISO 9899:1990 specification for the standard C library, which
	is essentially the same as the better-known ANSI C3.159-1989
	specification (C-89).</PARA>
<PARA>There are three aspects of this compatibility supplied by <EMPHASIS>eCos</EMPHASIS>.
First there is a <!-- <index></index> --><firstterm>C library</firstterm> which
implements the functions defined by the ISO standard, except for the
mathematical functions. This is provided by the eCos C library
packages. </PARA>
<PARA>Then <EMPHASIS>eCos</EMPHASIS> provides a <!-- <index></index> -->math
library, which implements the mathematical functions from the ISO
C library. This distinction between C and math libraries is frequently
drawn &mdash; most standard C library implementations provide
separate linkable files for the two, and the math library contains
all the functions from the <filename>math.h</filename> header
file.</PARA>
<PARA>There is a third element to the ISO C library, which is the
environment in which applications run when they use the standard
C library. This environment is set up by the C library startup procedure
(<xref linkend="c-library-startup">)
and it provides (among other things) a <FUNCTION>main()</FUNCTION> entry
point function, an <FUNCTION>exit()</FUNCTION> function that
does the cleanup required by the standard (including handlers registered
using the <FUNCTION>atexit()</FUNCTION> function), and an environment
that can be read with <FUNCTION>getenv()</FUNCTION>. </PARA>
<PARA>The description in this manual focuses on the <EMPHASIS>eCos</EMPHASIS>-specific
aspects of the C library (mostly related to <EMPHASIS>eCos</EMPHASIS>'s
configurability) as well as mentioning the omissions from the standard
in this release. We do not attempt to define the semantics of each
function, since that information can be found in the ISO, ANSI,
POSIX and IEEE standards, and the many good books that have been
written about the standard C library, that cover usage of these
functions in a more general and useful way.</PARA>
<SECT1 id="include-non-iso-functions">
<TITLE>Included non-ISO functions</TITLE>
<PARA>The following functions from the <!-- <index></index> -->POSIX specification
are included for convenience: </PARA>
<PARA>	<literal>extern char **</literal><EMPHASIS>environ</EMPHASIS> variable
(for setting up the environment for use with <FUNCTION>getenv()</FUNCTION>)</PARA>
<PARA>	<FUNCTION>_exit()</FUNCTION> </PARA>
<PARA>	<FUNCTION>strtok_r()</FUNCTION> </PARA>
<PARA>	<FUNCTION>rand_r()</FUNCTION> </PARA>
<PARA>	<FUNCTION>asctime_r()</FUNCTION> </PARA>
<PARA>	<FUNCTION>ctime_r()</FUNCTION> </PARA>
<PARA>	<FUNCTION>localtime_r()</FUNCTION> </PARA>
<PARA>	<FUNCTION>gmtime_r()</FUNCTION> </PARA>
<PARA><EMPHASIS>eCos</EMPHASIS> provides the following additional
implementation-specific functions within the standard C library
to adjust the date and time settings:</PARA>
<PROGRAMLISTING>void <FUNCTION>cyg_libc_time_setdst</FUNCTION>( 
  cyg_libc_time_dst state
);</PROGRAMLISTING>
<PARA>This function sets the state of Daylight Savings Time. The
values for state are:</PARA>
<PROGRAMLISTING>CYG_LIBC_TIME_DSTNA   unknown
CYG_LIBC_TIME_DSTOFF  off
CYG_LIBC_TIME_DSTON   on</PROGRAMLISTING>

<PROGRAMLISTING>void <FUNCTION>cyg_libc_time_setzoneoffsets</FUNCTION>( 
  time_t stdoffset, time_t dstoffset
);</PROGRAMLISTING>
<PARA>This function sets the offsets from UTC used when Daylight
Savings Time is enabled or disabled. The offsets are in time_t&rsquo;s,
which are seconds in the current inplementation.</PARA>
<PROGRAMLISTING><FUNCTION>Cyg_libc_time_dst cyg_libc_time_getzoneoffsets</FUNCTION>( 
  time_t *stdoffset, time_t *dstoffset
);</PROGRAMLISTING>
<PARA>This function retrieves the current setting for Daylight Savings
Time along with the offsets used for both STD and DST. The offsets
are both in time_t&rsquo;s, which are seconds in the
current implementation.</PARA>
<PROGRAMLISTING><FUNCTION>cyg_bool cyg_libc_time_settime</FUNCTION>( 
  time_t utctime
);</PROGRAMLISTING>
<PARA>This function sets the current time for the system The time
is specified as a <type>time_t</type> in UTC.
It returns non-zero on error.</PARA>
</SECT1>
<SECT1 id="math-library-compatibility-modes">
<TITLE>Math library compatibility modes</TITLE>
<PARA>This math library is capable of being operated in several
different compatibility modes. These options deal solely with how
errors are handled. </PARA>
<PARA>There are 4 compatibility modes: ANSI/POSIX 1003.1;
IEEE-754; X/Open Portability Guide issue 3 (XPG3); and
System V Interface Definition Edition 3. </PARA>
<PARA>In <!-- <index></index> -->IEEE mode, the <function>matherr()</function> function
(see below) is never called, no warning messages are printed on
the stderr output stream, and errno is never set. </PARA>
<PARA>In <!-- <index></index> -->ANSI/POSIX mode, errno is set correctly,
but <function>matherr()</function> is never called and no warning messages
are printed on the stderr output stream. </PARA>
<PARA>In <!-- <index></index> -->X/Open mode, errno is set correctly,
<function>matherr()</function> is called, but no warning messages are printed
on the stderr output stream. </PARA>
<PARA>In <!-- <index></index> -->SVID mode, functions which overflow return
a value HUGE (defined in <filename>math.h</filename>), which is the maximum
single precision floating point value (as opposed to
HUGE_VAL which is meant to stand for infinity). errno is
set correctly and <function>matherr()</function> is called. If
<function>matherr()</function> returns 0, warning messages are printed on
the stderr output stream for some errors. </PARA>
<PARA>The mode can be compiled-in as IEEE-only, or any one of the
above methods settable at run-time. </PARA>
<NOTE>
<PARA>This math library assumes that the hardware (or software floating
point emulation) supports IEEE-754 style arithmetic, 32-bit 2's
complement integer arithmetic, doubles are in 64-bit IEEE-754 format.</PARA>
</NOTE>
<SECT2>
<TITLE><!-- <index></index> -->	    matherr()</TITLE>
<PARA>As mentioned above, in X/Open or SVID modes, the user
	    can supply a function <FUNCTION>matherr()</FUNCTION> of
	    the form:</PARA>
<PROGRAMLISTING>int <FUNCTION>matherr</FUNCTION>( struct exception *e )
</PROGRAMLISTING>
<PARA>where struct exception is defined as:</PARA>
<PROGRAMLISTING>struct exception {
 int type;
 char *name;
 double arg1, arg2, retval;
}; </PROGRAMLISTING>
<PARA>type is the exception type and is one of:</PARA>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>DOMAIN 	</TERM>
<LISTITEM>

<PARA>argument domain exception</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>SING 	</TERM>
<LISTITEM>

<PARA>argument singularity</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>OVERFLOW 	</TERM>
<LISTITEM>

<PARA>overflow range exception</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>UNDERFLOW 	</TERM>
<LISTITEM>

<PARA>underflow range exception</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>TLOSS 	</TERM>
<LISTITEM>

<PARA>total loss of significance</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>PLOSS 	</TERM>
<LISTITEM>

<PARA>partial loss of significance</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
<PARA><parameter>name</parameter> is a string containing the name of the
function</PARA>
<PARA><parameter>arg1</parameter> and <parameter>arg2</parameter> are the
arguments passed to the function</PARA>
<PARA><parameter>retval</parameter> is the default value that will be returned
by the function, and can be changed by <FUNCTION>matherr()</FUNCTION></PARA>
<NOTE>
<PARA>matherr must have &ldquo;C&rdquo; linkage, not &ldquo;C&plus;&plus;&rdquo; linkage.</PARA>
</NOTE>
<PARA>If matherr returns zero, or the user doesn't supply
their own matherr, then the following <EMPHASIS>usually</EMPHASIS> happens
in SVID mode:</PARA><!-- FIXME: must convert this table -->
	  <table>
<title>Behavior of math exception handling</title>
<tgroup cols="2">
<thead>
<row>
  <entry>Type</entry>
  <entry>Behavior</entry
</row>
</thead>
<tbody>
<row>
<entry>DOMAIN</entry><entry>0.0 returned,
errno=EDOM, and a message printed on stderr</entry></row>
<row>
<entry>SING</entry><entry>HUGE of appropriate
sign is returned, errno=EDOM, and a message is printed
on stderr</entry></row>
<row>
<entry>OVERFLOW</entry><entry>HUGE of
appropriate sign is returned, and errno=ERANGE</entry></row>
<row>
<entry>UNDERFLOW</entry><entry>0.0 is
returned and errno=ERANGE</entry></row>
<row>
<entry>TLOSS</entry><entry>0.0 is returned,
errno=ERANGE, and a message is printed on stderr</entry></row>
<row>
<entry>PLOSS</entry><entry>The current
implementation doesn't return this type</entry></row>
</tbody>
</tgroup>
</table>
<!-- -->
<PARA>X/Open mode is similar except that the message is
not printed on stderr and HUGE_VAL is used in place of
HUGE</PARA>
</SECT2>
<SECT2>
<TITLE>Thread-safety and re-entrancy</TITLE>
<PARA>With the appropriate configuration options set below, the
math library is fully thread-safe if:</PARA>
<ITEMIZEDLIST>
<LISTITEM>
<PARA>Depending on the compatibility mode, the
		setting of the errno variable from the C library is
		thread-safe</PARA>
</LISTITEM>
<LISTITEM>
<PARA>Depending on the compatibility mode, sending error messages
to the stderr output stream using the C library 
<FUNCTION>fputs()</FUNCTION>
 function is thread-safe </PARA>
</LISTITEM>
<LISTITEM>
<PARA>Depending on the compatibility mode, the user-supplied 
<FUNCTION>matherr()</FUNCTION>
 function and anything it depends on are thread-safe </PARA>
</LISTITEM>
</ITEMIZEDLIST>
<PARA>In addition, with the exception of the <FUNCTION>gamma*()</FUNCTION> and <FUNCTION>lgamma*()</FUNCTION> functions,
the math library is reentrant (and thus safe to use from interrupt handlers)
if the Math library is always in IEEE mode.</PARA>
</SECT2>
</SECT1>
<SECT1 id="libc-implementation-details">
<TITLE>Some implementation details</TITLE>