--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-6FCB023F-E9E0-5C3D-A8BA-92B1B4733258.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,157 @@
+<?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>
\ No newline at end of file