C -Standard Library Overview

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:

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.

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.

-C Standard -Library Concepts -C Standard -Library Tutorials -C Standard -Library Examples + + + + + +C +Standard Library Overview +

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.

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.

+C Standard +Library Concepts +C Standard +Library Tutorials +C Standard +Library Examples

\ No newline at end of file