C Standard Library Overview

Purpose

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.

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