<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-6FCB023F-E9E0-5C3D-A8BA-92B1B4733258" xml:lang="en"><title>C
Standard Library Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This section provides an overview of Symbian platform's implementation
of the C Standard Library (referred to as STDLIB). </p>
<p>It provides information on how it differs from other such libraries and
descriptions of some of its main features. It does not attempt to document
the library's entire API. For such documentation, refer to the following documentation:</p>
<ul>
<li><p>For documentation of the ANSI C and POSIX specifications, see the relevant
organisations' web sites (<xref href="http://www.ansi.org" scope="external">http://www.ansi.org</xref> and <xref href="http://standards.ieee.org/index.html" scope="external">http://standards.ieee.org/index.html</xref>). </p></li>
<li><p>For literature on ANSI and POSIX specifications, see POSIX Programmers
Guide— Donald Lewine O'Reilly &amp; Associates, Inc.— ISBN 0-937175-73-0  </p></li>
</ul>
<p> <b>Important:</b> C Standard Library is planned to be deprecated soon.
It is recommended that you use the much more compliant or complete <xref href="GUID-D79380CF-22B5-5865-9366-44118E8ECA2E.dita">Open
Environment Core (P.I.P.S.)</xref> libraries instead. </p>
<section><title>Purpose</title> <p>STDLIB serves the following purposes: </p> <ul>
<li id="GUID-780B9EEB-62C5-57D7-A1AE-26116D65E339"><p>Addressing the porting
requirements of C software engines to Symbian platform. </p> </li>
<li id="GUID-5A9D30BE-C387-5389-9AD2-5B8F837A0DC9"><p>Providing an ANSI C
library with associated POSIX system calls. </p> </li>
<li id="GUID-B15818AC-9E7A-5C58-B6A9-58D47C9484FD"><p>Supporting both pure
C programs and mixed C/C++ programs. </p> </li>
<li id="GUID-93F33B67-41B4-5983-90A1-C632972ED5E2"><p>Providing the standard
include file structure with the standard <codeph>#defines</codeph> and function
prototypes. </p> </li>
</ul> <p>STDLIB implementation does not serve the following purposes: </p> <ul>
<li id="GUID-304064B6-D603-56C1-9951-8FFD4CD91E4E"><p>Supporting pre-ANSI
C compilers. </p> </li>
<li id="GUID-7A765051-395B-5B7A-A71D-C44F5DC00ED4"><p>Passing ANSI or POSIX
conformance test suites. </p> </li>
<li id="GUID-01B46F4E-E6DD-5CD9-8B09-E9D169D961B4"><p>Supporting POSIX-style
tools executed from a shell. Symbian platform neither provides a shell nor
does it provide a advanced text console. </p> </li>
<li id="GUID-12B49D44-453B-5BC6-826C-23B305C43003"><p>Being the C API for
Symbian platform. For example, STDLIB does not provide any new C functions
for supporting threads or active schedulers. </p> </li>
<li id="GUID-B8292CEE-EC88-503F-8F8B-3EE2F643D524"><p>Providing new C++ interfaces.
The public API for STDLIB is the C function by itself, and almost no aspects
of the C++ implementation are exposed, even to C++ programmers. </p> </li>
</ul> </section>
<section><title>Required Background </title> <p>The understanding on the following
are required prior to implementing STDLIB: </p> <p><b>Similarities between
STDLIB and the ANSI standard </b> </p> <ul>
<li id="GUID-177C458B-84C1-5BBA-A14A-A228DF249C18"><p>Many ANSI standard functions
have been implemented, including all those in <codeph>stdio.h</codeph> and <codeph>math.h</codeph>.
The functions which have been implemented are those in the STDLIB header files
whose prototypes are preceded by the <codeph>IMPORT_C</codeph> macro. </p> </li>
<li id="GUID-D807BFE5-B6DC-59D5-9C69-EB53FC79B6CB"><p>STDLIB's maths library, <codeph>math.h</codeph>,
provides the mandatory ANSI maths functions. Most of these use the underlying
Symbian platform maths functions, encapsulated by the <codeph>Math</codeph> class. </p> </li>
<li id="GUID-7379EE4C-D9EF-5846-BA73-6BF628A404CA"><p>Many functions, including <codeph>bsearch()</codeph>, <codeph>qsort()</codeph>, <codeph>memcpy()</codeph> and <codeph>tolower()</codeph> are more than a call to a corresponding function
provided by Symbian platform. In many cases, this function may be found in
Symbian's <codeph>User</codeph> class. For example, <codeph>malloc()</codeph> and <codeph>free()</codeph> simply
call <codeph>User::Alloc()</codeph> and <codeph>User::Free()</codeph> respectively. </p> </li>
</ul> <p><b>Differences between STDLIB and ANSI and POSIX </b> </p> <ul>
<li id="GUID-09D4CAF0-4427-52E1-BE90-C1C524AB13E3"><p>The STDLIB implementation
of <codeph>printf()</codeph> does not take into account the format specifier
for floating point values. Instead, the implementation uses <codeph>TDes8::Format()</codeph> with
a Symbian platform format specifier which is derived from the style, width
and precision of the original <codeph>printf()</codeph> specifier. The result
does not obey the rules for ANSI <codeph>printf()</codeph> for some combinations
of number width and precision, and formats the numbers using the thousands
separator taken from the Symbian platform locale; see class <codeph>TLocale</codeph>. </p> </li>
<li id="GUID-45507BF5-C062-5FF4-BC51-F2B77174C072"><p>Symbian platform identifies
some errors as being fundamental programming errors and will abruptly terminate
the offending thread (referred to as a panic). POSIX never does this and will
always return error conditions instead (though some errors will result in
signals, e.g., segmentation faults). </p> </li>
<li id="GUID-5FD1D372-3514-5F31-AA92-1F6F5D023A75"><p>POSIX processes exist
in a hierarchy with children inheriting resources from their parents — the
"fork and exec" model of process creation. In Symbian platform, processes
have no association whatsoever with the thread which created them. They are
created by constructing a fresh instance of an executable image. </p> </li>
<li id="GUID-868CC232-9A8F-5764-9499-8B39D3A1DF33"><p>Symbian platform provides
limited text console support, intended for debugging of low-level components. </p> </li>
<li id="GUID-04209D36-F963-5115-8E44-870AF9E16719"><p>An open file in the
POSIX system is a process wide resource that can also be inherited by child
processes. In Symbian platform each thread within a process has separate resources
within the shared process address space, and open files are private to a given
thread. </p> </li>
<li id="GUID-157AB2F3-DE12-5A5F-8EA3-3A5E57CECAD9"><p>Open POSIX files are
inherently shareable, so multiple processes can write to the same file simultaneously.
In Symbian platform, open files are inherently non-shareable, and even the
thread which has the file open is only allowed one outstanding write operation
at a time. For more information on files, see the <codeph>RFile</codeph> class. </p> </li>
<li id="GUID-D6CE165D-1AC7-50B8-8204-35C074F51079"><p>Symbian platform does
not support global data in DLLs. To overcome this, STDLIB uses a structure, <codeph>_reent</codeph> (declared
in <codeph>reent.h</codeph>) an instance of which is allocated to each thread
to hold the <codeph>errno</codeph> value, some "static data areas" used by
functions such as <codeph>ctime()</codeph>, and the STDIO data structures. </p> </li>
<li id="GUID-84F0AAF4-BB2B-568A-883D-46656B829C62"><p>Symbian platform has
different client classes for each type of resource: files, sockets and the
console are all different and have different APIs. POSIX file descriptors
can refer to all of these different resources and have a common API (though
many functions will actually only work on socket file descriptors). </p> </li>
<li id="GUID-15A73AC5-5065-50E9-8B78-16AFD918565E"><p>Symbian platform processes
do not have a notion of a current working directory. The closest notion is
the session path, as set and retrieved by class <codeph>RFs</codeph>. </p> </li>
<li id="GUID-2BCF79DA-66B0-5407-A4E5-ACE41541BAF8"><p>Symbian platform does
not have a way of pre-empting a thread and causing it to execute a different
piece of code, so there is no true equivalent of a POSIX signal or signal
handler. </p> </li>
</ul> <p><b>Exclusions in STDLIB </b> </p> <p>Symbian has no plans to provide
the following in the C Standard Library: </p> <ul>
<li id="GUID-411B0B35-7705-5448-AE73-BAFDEDC538E2"><p>float-sized maths operations.
POSIX requires only double-sized operations. Primitive arithmetic operations
on float values can be carried out, and all of the standard <codeph>printf</codeph> format
specifiers including <codeph>%E</codeph> and <codeph>%e</codeph> are supported.
However, none of the floating point library functions declared to take float-sized
arguments are supported. For example; </p> <codeblock id="GUID-C3ADA741-8FF4-5D72-9CE3-675B48F7E513" xml:space="preserve">double sqrt( double d );    // Supported by STDLIB
float sqrtf( float f );     // Omission</codeblock> </li>
<li id="GUID-224430FB-D02F-5C39-A9C4-4D80DFD2A95E"><p>mapping the ANSI locale
functions onto the Symbian <codeph>TLocale</codeph> functionality. Instead
the locale is a fixed "C" locale. Therefore STDLIB engines may not be localised.
It is recommended that localisation be implemented at the Symbian platform
application level. </p> </li>
<li id="GUID-3A4751A8-9814-52BC-84C2-6A6963A6B233"><p> <codeph>select()</codeph>.
The POSIX <codeph>select()</codeph> function is not implemented in STDLIB
because Symbian platform does not in general support asynchronous "ready to
read" or "ready to write" notification. </p> </li>
<li id="GUID-05D7E649-FC17-5DD4-81E0-0D3A4FDD2619"><p> <codeph>signal()</codeph>.
A Symbian thread cannot be made to spontaneously execute a "signal handler",
so signals have not been implemented. </p> </li>
<li id="GUID-9D25E72B-935D-5A95-B694-03D5F0F39C0D"><p> <codeph>fork()</codeph> or <codeph>exec()</codeph> functions </p> </li>
<li id="GUID-17E9D42B-F3EA-530F-A86B-F20B36EE1160"><p>IPv6 support </p> </li>
</ul> <p><b>Error codes </b> </p> <p>Most error codes reported by STDLIB functions
correspond to the standard C error code values. Some of these are identified
within STDLIB, which produces the correct <codeph>errno</codeph> value directly;
most are reported by translating the Symbian platform error codes into equivalent <codeph>errno</codeph> values
using a translation table. Occasionally, a Symbian platform error code may
be reported untranslated. In this case, it will have a negative value. For
the Symbian platform error codes, see <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> etc. STDLIB
does not usually attempt to detect inputs which will cause a panic, (for example,
attempting to <codeph>accept()</codeph> on a stream socket which has not been
bound). Such a panic will terminate the offending thread, which may in turn
result in the termination of the whole process. </p> </section>
</conbody><related-links>
<link href="GUID-39FA0ECE-D403-5F02-AC5D-7BC8E1669E8E.dita"><linktext>C Standard
Library  Concepts</linktext></link>
<link href="GUID-F7C9824F-0598-56A1-AC2B-24904E997588.dita"><linktext>C Standard
Library Tutorials</linktext></link>
<link href="GUID-7EFA2113-3C4A-5C52-AC28-BBD512466302.dita"><linktext>C Standard
Library Examples</linktext></link>
</related-links></concept>