This section provides an overview of the 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:
For documentation of the ANSI C and POSIX specifications, see the relevant organisations' web sites (http://www.ansi.org and http://standards.ieee.org/index.html).
For literature on ANSI and POSIX specifications, see POSIX Programmers Guide— Donald Lewine O'Reilly & Associates, Inc.— ISBN 0-937175-73-0
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.
STDLIB serves the following purposes:
Addressing the porting requirements of C software engines to the 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. The Symbian platform neither provides a shell nor does it provide a advanced text console.
Being the C API for the 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.
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 the 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.
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).
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.
The 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. 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.
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 RFile class.
The 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.
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).
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 RFs.
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.
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 the 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.