C +Standard Library Overview

This section provides an overview of Symbian platform's implementation +of the C Standard Library (referred to as STDLIB).

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:

Important: C Standard Library is planned to be deprecated soon. +It is recommended that you use the much more compliant or complete Open +Environment Core (P.I.P.S.) libraries instead.

Purpose

STDLIB serves the following purposes:

Addressing the porting +requirements of C software engines to Symbian platform.
Providing an ANSI C +library with associated POSIX system calls.
Supporting both pure +C programs and mixed C/C++ programs.
Providing the standard +include file structure with the standard #defines and function +prototypes.

STDLIB implementation does not serve the following purposes:

Supporting pre-ANSI +C compilers.
Passing ANSI or POSIX +conformance test suites.
Supporting POSIX-style +tools executed from a shell. Symbian platform neither provides a shell nor +does it provide a advanced text console.
Being the C API for +Symbian platform. For example, STDLIB does not provide any new C functions +for supporting threads or active schedulers.
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.

Required Background

The understanding on the following +are required prior to implementing STDLIB:

Similarities between +STDLIB and the ANSI standard

Many ANSI standard functions +have been implemented, including all those in stdio.h and math.h. +The functions which have been implemented are those in the STDLIB header files +whose prototypes are preceded by the IMPORT_C macro.
STDLIB's maths library, math.h, +provides the mandatory ANSI maths functions. Most of these use the underlying +Symbian platform maths functions, encapsulated by the Math class.
Many functions, including bsearch(), qsort(), memcpy() and tolower() are more than a call to a corresponding function +provided by Symbian platform. In many cases, this function may be found in +Symbian's User class. For example, malloc() and free() simply +call User::Alloc() and User::Free() respectively.

Differences between STDLIB and ANSI and POSIX

The STDLIB implementation +of printf() does not take into account the format specifier +for floating point values. Instead, the implementation uses TDes8::Format() with +a Symbian platform format specifier which is derived from the style, width +and precision of the original printf() specifier. The result +does not obey the rules for ANSI printf() for some combinations +of number width and precision, and formats the numbers using the thousands +separator taken from the Symbian platform locale; see class TLocale.
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).
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.
Symbian platform provides +limited text console support, intended for debugging of low-level components.
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.
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 RFile class.
Symbian platform does +not support global data in DLLs. To overcome this, STDLIB uses a structure, _reent (declared +in reent.h) an instance of which is allocated to each thread +to hold the errno value, some "static data areas" used by +functions such as ctime(), and the STDIO data structures.
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).
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 RFs.
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.

Exclusions in STDLIB

Symbian has no plans to provide +the following in the C Standard Library:

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 printf format +specifiers including %E and %e are supported. +However, none of the floating point library functions declared to take float-sized +arguments are supported. For example;
double sqrt( double d ); // Supported by STDLIB +float sqrtf( float f ); // Omission
mapping the ANSI locale +functions onto the Symbian TLocale 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.
select(). +The POSIX select() function is not implemented in STDLIB +because Symbian platform does not in general support asynchronous "ready to +read" or "ready to write" notification.
signal(). +A Symbian thread cannot be made to spontaneously execute a "signal handler", +so signals have not been implemented.
fork() or exec() functions
IPv6 support

Error codes

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 errno value directly; +most are reported by translating the Symbian platform error codes into equivalent errno 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 KErrNone etc. STDLIB +does not usually attempt to detect inputs which will cause a panic, (for example, +attempting to accept() 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.