<?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 the 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 id="GUID-5818FD85-85E3-4DD3-ABC3-3A9B0531E457"><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 the 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. The 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
the 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 id="GUID-EE492687-97FC-4B0E-9E33-64B39DE93F49"><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 the 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>The 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. On the 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>The 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. On the 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.
On the 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>The 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>The 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>The 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>The 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 the 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>