<?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>