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