--- a/Symbian3/SDK/Source/GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,212 +1,212 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
-<!-- This component and the accompanying materials are made available under the terms of the License
-"Eclipse Public License v1.0" which accompanies this distribution,
-and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
-<!-- Initial Contributors:
- Nokia Corporation - initial contribution.
-Contributors:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D" xml:lang="en"><title>P.I.P.S.
-Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>P.I.P.S. supplies a new framework of POSIX 'C' APIs to be used by Symbian
-developers with RTOS, Linux or Microsoft Windows® knowledge. The new APIs
-are packaged into industry standard libraries - <codeph>libc</codeph>, <codeph>libm</codeph>, <codeph>libpthread</codeph> and <codeph>libdl</codeph> - and will help reduce development costs. </p>
-<section id="GUID-08EF9B92-E9A6-4C4F-8A08-597F2EF32135"><title>Purpose</title> <p>The
-Symbian platform already provides a library called '<codeph>ESTLIB</codeph>',
-which includes a subset of Standard C APIs. This was created to allow the
-Java virtual machine to run on the Symbian platform rather than to allow applications
-written in C to be ported to the Symbian platform. Furthermore, the functionality
-provided by <codeph>ESTLIB</codeph> is not fully compliant with the Standard
-C and POSIX standards. Symbian intends to deprecate <codeph>ESTLIB</codeph> once
-P.I.P.S. is mature. </p> <p>The P.I.P.S. libraries are included in ROM on
-certain smartphones based on Symbian OS v9.3 onwards. For smartphones based
-on earlier versions of Symbian platform, a freely downloadable SIS file is
-available from the Symbian Developer Network (specifically <xref href="http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start" scope="external">http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start</xref>)
-and can be installed on any Symbian OS v9.x smartphones. </p> </section>
-<section id="GUID-6E46D602-BED1-4E20-AE6B-5137615E2440"><title>Required background</title> <p><b>The
-differences between the Symbian platform and other operating systems</b> </p> <p>The
-Symbian platform is an operating system designed for mobile devices and comes
-in the form of many libraries that contain hundreds of classes and thousands
-of member functions. </p> <p>The Symbian platform has been specifically designed
-to provide efficient memory and power management. </p> <p>P.I.P.S. has been
-introduced to the Symbian platform to make it more attractive to third party
-Symbian developers with C/C++ experience and to allow them to port their applications
-to the Symbian platform with greater ease. </p> <p>The P.I.P.S. initiative
-aims to reduce the development cost of porting software to run on the Symbian
-platform. It achieves this by providing a POSIX-like API layer above the Symbian
-platform. Given the structure of the Symbian platform, however, it is not
-possible to provide a fully compliant API and some functionality, such as, <xref href="GUID-432C9AA0-A698-3A62-95D8-CB010965F92C.dita"><apiname>fork()</apiname></xref> and <xref href="GUID-1F3AB7F6-B354-36DB-AA0C-D8F2DC89A6DD.dita"><apiname>exec()</apiname></xref> are
-not supported. This guide details such non-compliance and recommended alternatives. </p> <p>Specific
-differences between the Symbian platform and Unix-like systems are described
-in the relevant sections of this guide. </p> <p><b>What P.I.P.S. is not</b> </p> <p>The
-P.I.P.S. environment is <b>not</b> a UNIX® application environment. You will
-not be able to run a UNIX application on the Symbian platform 'as is'. At
-a minimum, you will need to create a <filepath>.mmp</filepath> file and a <filepath>bld.inf</filepath> file
-for the application and rebuild the application's source code for the Symbian
-platform. For further information, see <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The
-Symbian build process</xref> section. </p> <p>If the application does not
-work at the first attempt, you may have to modify the application code to
-replace missing APIs or port the required APIs to extend the P.I.P.S. environment.
-To find out more about porting C libraries to the Symbian platform, see the <xref href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita">P.I.P.S. Porting Tutorials</xref> sections. </p> <p>The
-P.I.P.S. environment is not 100% POSIX compliant and it is not officially
-certified as POSIX compatible. However, the implementation is as compliant
-as the underlying Symbian platform allows it to be. For example, P.I.P.S.
-does not provide the APIs <codeph>fork()</codeph> and <codeph>exec()</codeph>,
-but it does provide <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref>, <xref href="GUID-F4749DAA-1B29-3D1D-A3AA-0D52B851E501.dita"><apiname>mkfifo()</apiname></xref> and
-so on, which can be used to implement well known alternative patterns. For
-further information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process
-Creation</xref> section. </p> </section>
-<section id="GUID-22E7E427-C9D1-4C26-BCA8-E4A48CE0E45F"><title>Architecture</title> <p>P.I.P.S.
-provides an API layer above the native Symbian platform APIs that is more
-closely aligned with industry standard APIs. </p> <p>The core P.I.P.S. libraries
-are: </p> <ul>
-<li id="GUID-213D2779-C303-5A11-A339-8E464D4B4A68"><p> <codeph>libc</codeph>:
-Standard C and POSIX APIs - includes support for files, sockets, pipes, message
-queues, shared memory APIs and environment variables </p> </li>
-<li id="GUID-1209CBDA-DFEB-5ECA-AD4F-A1452762C2CC"><p> <codeph>libm</codeph>:
-Standard C maths support APIs </p> </li>
-<li id="GUID-138D2894-8362-5C13-B5BB-24A9A22DF415"><p> <codeph>libpthread</codeph>:
-Standard POSIX threading APIs </p> </li>
-<li id="GUID-E00112DA-D5BB-55C0-A6A4-A443B67858C0"><p> <codeph>libdl</codeph>:
-Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is
-supported on pre-Symbian OS v9.3 releases). </p> </li>
-</ul> <p>The first three libraries listed above are seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>. </p> <p>The diagram below shows the high
-level architecture of the P.I.P.S. environment. </p> <fig id="GUID-103BEA25-EE1B-50D0-8C0C-950C1A43656D">
-<title> P.I.P.S. environment architecture </title>
-<image href="GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e155039_href.png" placement="inline"/>
-</fig> <p>This diagram shows how P.I.P.S. fits in with the Symbian platform,
-and also how C/C++ applications, additional C shared libraries and hybrid
-applications developed by third party Symbian developers using P.I.P.S. fit
-in. </p> <p>P.I.P.S. environment is based on industry-standard APIs. These
-standards include </p> <ul>
-<li id="GUID-09A5848E-7934-5202-BB09-BE6390FC2F12"><p>Standard C (<codeph>stdC</codeph>)
-and </p> </li>
-<li id="GUID-0478A6C5-238C-5CFF-8625-791293800E9B"><p>POSIX. </p> </li>
-</ul> <p>The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward. </p> <p>For
-devices already in the market, a SIS file is freely downloadable from the
-Forum Nokia site (specifically <xref href="http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/" scope="external">http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/</xref>)
-and can be installed on any v9.x phone. </p> <p><b>Components</b> </p> <p>P.I.P.S.
-is based on an industry-standard API and system behaviour. The relevant
-industry standards are Open Group standards and include Standard C (<codeph>stdC</codeph>),
-POSIX, GNU C library (<codeph>glibc</codeph>) and Standard C++ (<codeph>stdC++</codeph>). </p> <p>The
-diagram below shows how the Standard C libraries and exported applications
-fit into the native platform. </p> <fig id="GUID-02F370A6-0713-5E7F-A851-339E03603A0A">
-<title> The subsystem components </title>
-<image href="GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e155098_href.png" placement="inline"/>
-</fig> <p>The System Call Adaptation Layer (SCAL) is not directly accessed
-by the developer wishing to export to the Symbian platform, but through calls
-in the P.I.P.S. libraries. </p> <p>Traditionally, in Unix-like systems, system
-calls are implemented in the kernel, separate from the C libraries. On the
-Symbian platform, the 'System Call Adaptation Layer' runs in the context of
-the user side but is considered 'kernel-like' code. APIs that belong to this
-layer are tagged as <codeph>@internalComponent</codeph> and may only be extended
-by Symbian. </p> <p>Note that P.I.P.S. is not a Linux application environment
-- you cannot simply run an application that you've compiled for your Linux
-desktop. At a minimum, you will have to rebuild your application from source. </p> <p>For
-more information, see the <xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita">Build
-Process</xref> section. </p> <p id="GUID-49C7F951-8317-5F41-B1B9-9F7B8803E655"><b>Glue
-code (CRT0)</b> </p> <p>Executables built for the Symbian platform enter via <codeph>E32Main()</codeph>,
-whereas Standard C applications expect to be started from <codeph>main()</codeph>.
-It is therefore necessary to have 'glue code' (formerly known as CRT0) between
-these two functions. The glue code is also responsible for allocating any
-system resources, obtaining system and environment data, and initialising
-the SCAL infrastructure prior to calling the <codeph>main()</codeph> function
-of the application. There are two versions of the glue code library - <filepath>libcrt0.lib</filepath> (for
-use by applications that enter via char <codeph>main()</codeph>) and <filepath>libwcrt0.lib</filepath> (for
-use by applications that enter via wide char <codeph>main()</codeph>). </p> <p>To
-include the glue code library you should explicity link to <filepath>libcrt0.lib</filepath> and <filepath>libwcrt0.lib</filepath> statically,
-however, if you are using the <codeph>STDEXE</codeph> or <codeph>STDDLL</codeph> target
-types, glue code will be added automatically. </p> <p id="GUID-1DDC11E7-D9D6-5251-89CE-981C4869D109"><b>P.I.P.S.
-Core libraries</b> </p> <p>Currently, the C libraries include the <codeph>libc</codeph>, <codeph>libm</codeph>,
-and <codeph>libpthread</codeph> (seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) and <codeph>libdl</codeph> libraries. The
-APIs provided by these libraries are defined to be compliant, via compatibility
-features, with the POSIX standard. They are not officially certified as POSIX
-compatible but they conform to it mostly. </p> <p>The P.I.P.S. libraries include
-the following APIs: </p> <ul>
-<li id="GUID-95E53F0A-B919-5EEE-9A6F-427E87547088"><p> <codeph>stdio</codeph>,
-including <xref href="GUID-E69DB3CD-E6DA-3B1D-A499-AE68EC432CAC.dita"><apiname>print()</apiname></xref>, <xref href="GUID-58616261-FB60-37C5-9289-239144CD8FB8.dita"><apiname>scanf()</apiname></xref>, and so on </p> </li>
-<li id="GUID-5359692C-17C8-5486-9DCB-0A5B9AD1C90A"><p> <codeph>stdlib</codeph>,
-including environment variable support, and so on </p> </li>
-<li id="GUID-F0E19C9C-5581-5E47-A775-A6B57C22EE92"><p>string manipulation
-and character APIs </p> </li>
-<li id="GUID-B0F2B006-6D62-5DD6-9CDC-7ADFB693E77E"><p>locale and system services </p> </li>
-<li id="GUID-C5440DE9-24A2-5A34-A2A7-47E836E1545D"><p>searching, sort and
-pattern matching </p> </li>
-<li id="GUID-33D03F27-4B97-56CA-B4ED-67901701A1E2"><p>IPC mechanisms, including
-shared memory, pipes, FIFOs and message queues </p> </li>
-<li id="GUID-15AE7775-5FC8-59A4-924E-3987F9314F58"><p>process creation, including <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref>, <xref href="GUID-E7C4DE71-BC5B-34AE-ACB3-C34A0DB1FC16.dita"><apiname>posix_spawn()</apiname></xref> and <xref href="GUID-3D9040E5-F6FB-3DEA-9800-A55F0CEE7B08.dita"><apiname>system()</apiname></xref> </p> </li>
-<li id="GUID-2AEE41E3-A696-588C-9E5B-8E362E96D4B5"><p>networking and socket
-APIs </p> </li>
-<li id="GUID-ACF6B3A6-0F83-50D3-B0FB-FA765BDA408D"><p>mathematical and arithmetic
-APIs </p> </li>
-<li id="GUID-595D4C61-0FC9-5A05-BEDD-7412CEA585BA"><p>dynamic loading and
-symbol lookup </p> </li>
-<li id="GUID-DC3DB027-B384-52D1-8284-BF868A5CD543"><p>thread creation and
-synchronisation mechanisms. </p> </li>
-</ul> <p>Due to fundamental differences between Linux and the Symbian platform
-kernel architecture, there is no support for <xref href="GUID-432C9AA0-A698-3A62-95D8-CB010965F92C.dita"><apiname>fork()</apiname></xref> and <xref href="GUID-1F3AB7F6-B354-36DB-AA0C-D8F2DC89A6DD.dita"><apiname>exec()</apiname></xref>.
-For more information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process
-Creation</xref> section. </p> <p>The original seed directory structure (<xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) is preserved
-as fully as possible to allow for future catch-ups to be performed more easily.
-The table below shows the original seed directory structure in FreeBSD. </p> <table id="GUID-A1D61A32-6F99-5B0A-B348-135373DC3AEA">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<tbody>
-<row>
-<entry><p> <b>Module</b> </p> </entry>
-<entry><p> <b>Description</b> </p> </entry>
-</row>
-<row>
-<entry><p> <filepath>core\libc</filepath> </p> </entry>
-<entry><p>Contains Standard C and POSIX APIs as defined by the Standard C
-and POSIX standards </p> </entry>
-</row>
-<row>
-<entry><p> <filepath>core\libm</filepath> </p> </entry>
-<entry><p>Contains the Standard C <codeph>Math</codeph> API as defined by
-Standard C </p> </entry>
-</row>
-<row>
-<entry><p> <filepath>core\libpthread</filepath> </p> </entry>
-<entry><p>Contains POSIX threading APIs as defined the POSIX standards </p> </entry>
-</row>
-<row>
-<entry><p> <filepath>core\libdl</filepath> </p> </entry>
-<entry><p>Contains APIs for dynamic loading and symbol lookup by name. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p>Although P.I.P.S. provides a wide range of APIs, some of the functionality
-required in order to complete a porting task might be missing - this could
-be some APIs from an existing library or an entire library. </p> <p>Several
-options are available to the user: </p> <ul>
-<li id="GUID-99935DCF-2678-5D76-98E9-8E94269E7CAC"><p>Port the missing APIs
-using the P.I.P.S. libraries </p> </li>
-<li id="GUID-FFA95C02-268F-5281-B0D3-5A4A64BC5A27"><p>Implement the missing
-APIs on top of the Symbian platform native C++ APIs </p> </li>
-<li id="GUID-D70619B7-E889-5D11-81C7-FD99420F3D1D"><p>Use a workaround - for
-example, use <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref> instead of <codeph>fork()</codeph>. </p> </li>
-</ul> <p> <b>Note:</b> The following are the limitations associated with porting
-a UNIX® application: </p> <ul>
-<li id="GUID-4057ED21-65DD-5C20-A65B-B9228BE920BD"><p> <b>Limited stack-space:</b> The
-default stack size per thread on Unix-like operating systems ranges from 64
-kB to 1 MB. The Symbian platform, however, defines a default stack size of
-8 kB per thread. P.I.P.S. Pthreads use this by default. You can use the <codeph>pthread_attr_setstacksize()</codeph> function
-to modify this before calling <codeph>pthread_create()</codeph>. </p> </li>
-<li id="GUID-8329F811-34A6-5812-B033-2BE49C038D3E"><p> <b>Limited threads
-per process:</b> Assuming that all threads use the default stack size (8 kB),
-Symbian specifies a limit of 128 threads per process. The limit changes depending
-on the stack size you use for individual threads. For example, if you create
-your threads with a stack size of 16 kB, the OS only supports 64 threads per
-process. </p> </li>
-</ul> </section>
-</conbody><related-links>
-<link href="GUID-2016EF4B-F001-5EB2-8095-6048582511D6.dita"><linktext>P.I.P.S.
-Concepts</linktext></link>
-<link href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita"><linktext>P.I.P.S.
-Porting Tutorials</linktext></link>
-<link href="GUID-3EB1C34E-584E-595D-A339-DE170A96AEBC.dita"><linktext>P.I.P.S.
-Examples</linktext></link>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
+<!-- This component and the accompanying materials are made available under the terms of the License
+"Eclipse Public License v1.0" which accompanies this distribution,
+and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
+<!-- Initial Contributors:
+ Nokia Corporation - initial contribution.
+Contributors:
+-->
+<!DOCTYPE concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-6CDDDD1E-BDB9-5C61-8EFD-8B3369F5A12D" xml:lang="en"><title>P.I.P.S.
+Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>P.I.P.S. supplies a new framework of POSIX 'C' APIs to be used by Symbian
+developers with RTOS, Linux or Microsoft Windows® knowledge. The new APIs
+are packaged into industry standard libraries - <codeph>libc</codeph>, <codeph>libm</codeph>, <codeph>libpthread</codeph> and <codeph>libdl</codeph> - and will help reduce development costs. </p>
+<section id="GUID-08EF9B92-E9A6-4C4F-8A08-597F2EF32135"><title>Purpose</title> <p>The
+Symbian platform already provides a library called '<codeph>ESTLIB</codeph>',
+which includes a subset of Standard C APIs. This was created to allow the
+Java virtual machine to run on the Symbian platform rather than to allow applications
+written in C to be ported to the Symbian platform. Furthermore, the functionality
+provided by <codeph>ESTLIB</codeph> is not fully compliant with the Standard
+C and POSIX standards. Symbian intends to deprecate <codeph>ESTLIB</codeph> once
+P.I.P.S. is mature. </p> <p>The P.I.P.S. libraries are included in ROM on
+certain smartphones based on Symbian OS v9.3 onwards. For smartphones based
+on earlier versions of Symbian platform, a freely downloadable SIS file is
+available from the Symbian Developer Network (specifically <xref href="http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start" scope="external">http://developer.symbian.org/wiki/index.php/Open_C_and_Open_C%2B%2B_Quick_Start</xref>)
+and can be installed on any Symbian OS v9.x smartphones. </p> </section>
+<section id="GUID-6E46D602-BED1-4E20-AE6B-5137615E2440"><title>Required background</title> <p><b>The
+differences between the Symbian platform and other operating systems</b> </p> <p>The
+Symbian platform is an operating system designed for mobile devices and comes
+in the form of many libraries that contain hundreds of classes and thousands
+of member functions. </p> <p>The Symbian platform has been specifically designed
+to provide efficient memory and power management. </p> <p>P.I.P.S. has been
+introduced to the Symbian platform to make it more attractive to third party
+Symbian developers with C/C++ experience and to allow them to port their applications
+to the Symbian platform with greater ease. </p> <p>The P.I.P.S. initiative
+aims to reduce the development cost of porting software to run on the Symbian
+platform. It achieves this by providing a POSIX-like API layer above the Symbian
+platform. Given the structure of the Symbian platform, however, it is not
+possible to provide a fully compliant API and some functionality, such as, <xref href="GUID-432C9AA0-A698-3A62-95D8-CB010965F92C.dita"><apiname>fork()</apiname></xref> and <xref href="GUID-1F3AB7F6-B354-36DB-AA0C-D8F2DC89A6DD.dita"><apiname>exec()</apiname></xref> are
+not supported. This guide details such non-compliance and recommended alternatives. </p> <p>Specific
+differences between the Symbian platform and Unix-like systems are described
+in the relevant sections of this guide. </p> <p><b>What P.I.P.S. is not</b> </p> <p>The
+P.I.P.S. environment is <b>not</b> a UNIX® application environment. You will
+not be able to run a UNIX application on the Symbian platform 'as is'. At
+a minimum, you will need to create a <filepath>.mmp</filepath> file and a <filepath>bld.inf</filepath> file
+for the application and rebuild the application's source code for the Symbian
+platform. For further information, see <xref href="GUID-3100800B-B2F7-50EF-BD4C-3C345ECCB2A5.dita">The
+Symbian build process</xref> section. </p> <p>If the application does not
+work at the first attempt, you may have to modify the application code to
+replace missing APIs or port the required APIs to extend the P.I.P.S. environment.
+To find out more about porting C libraries to the Symbian platform, see the <xref href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita">P.I.P.S. Porting Tutorials</xref> sections. </p> <p>The
+P.I.P.S. environment is not 100% POSIX compliant and it is not officially
+certified as POSIX compatible. However, the implementation is as compliant
+as the underlying Symbian platform allows it to be. For example, P.I.P.S.
+does not provide the APIs <codeph>fork()</codeph> and <codeph>exec()</codeph>,
+but it does provide <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref>, <xref href="GUID-F4749DAA-1B29-3D1D-A3AA-0D52B851E501.dita"><apiname>mkfifo()</apiname></xref> and
+so on, which can be used to implement well known alternative patterns. For
+further information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process
+Creation</xref> section. </p> </section>
+<section id="GUID-22E7E427-C9D1-4C26-BCA8-E4A48CE0E45F"><title>Architecture</title> <p>P.I.P.S.
+provides an API layer above the native Symbian platform APIs that is more
+closely aligned with industry standard APIs. </p> <p>The core P.I.P.S. libraries
+are: </p> <ul>
+<li id="GUID-213D2779-C303-5A11-A339-8E464D4B4A68"><p> <codeph>libc</codeph>:
+Standard C and POSIX APIs - includes support for files, sockets, pipes, message
+queues, shared memory APIs and environment variables </p> </li>
+<li id="GUID-1209CBDA-DFEB-5ECA-AD4F-A1452762C2CC"><p> <codeph>libm</codeph>:
+Standard C maths support APIs </p> </li>
+<li id="GUID-138D2894-8362-5C13-B5BB-24A9A22DF415"><p> <codeph>libpthread</codeph>:
+Standard POSIX threading APIs </p> </li>
+<li id="GUID-E00112DA-D5BB-55C0-A6A4-A443B67858C0"><p> <codeph>libdl</codeph>:
+Standard C dynamic loading and symbol lookup APIs (only ordinal lookup is
+supported on pre-Symbian OS v9.3 releases). </p> </li>
+</ul> <p>The first three libraries listed above are seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>. </p> <p>The diagram below shows the high
+level architecture of the P.I.P.S. environment. </p> <fig id="GUID-103BEA25-EE1B-50D0-8C0C-950C1A43656D">
+<title> P.I.P.S. environment architecture </title>
+<image href="GUID-ACA2AFE8-4872-42FA-A871-34EB80197495_d0e148518_href.png" placement="inline"/>
+</fig> <p>This diagram shows how P.I.P.S. fits in with the Symbian platform,
+and also how C/C++ applications, additional C shared libraries and hybrid
+applications developed by third party Symbian developers using P.I.P.S. fit
+in. </p> <p>P.I.P.S. environment is based on industry-standard APIs. These
+standards include </p> <ul>
+<li id="GUID-09A5848E-7934-5202-BB09-BE6390FC2F12"><p>Standard C (<codeph>stdC</codeph>)
+and </p> </li>
+<li id="GUID-0478A6C5-238C-5CFF-8625-791293800E9B"><p>POSIX. </p> </li>
+</ul> <p>The P.I.P.S. environment is a mandatory part of Symbian OS v9.5 onward. </p> <p>For
+devices already in the market, a SIS file is freely downloadable from the
+Forum Nokia site (specifically <xref href="http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/" scope="external">http://www.forum.nokia.com/Technology_Topics/Development_Platforms/Open_C_and_C++/</xref>)
+and can be installed on any v9.x phone. </p> <p><b>Components</b> </p> <p>P.I.P.S.
+is based on an industry-standard API and system behaviour. The relevant
+industry standards are Open Group standards and include Standard C (<codeph>stdC</codeph>),
+POSIX, GNU C library (<codeph>glibc</codeph>) and Standard C++ (<codeph>stdC++</codeph>). </p> <p>The
+diagram below shows how the Standard C libraries and exported applications
+fit into the native platform. </p> <fig id="GUID-02F370A6-0713-5E7F-A851-339E03603A0A">
+<title> The subsystem components </title>
+<image href="GUID-5746BC4A-E8D2-51DE-B101-4BA68F0E1769_d0e148577_href.png" placement="inline"/>
+</fig> <p>The System Call Adaptation Layer (SCAL) is not directly accessed
+by the developer wishing to export to the Symbian platform, but through calls
+in the P.I.P.S. libraries. </p> <p>Traditionally, in Unix-like systems, system
+calls are implemented in the kernel, separate from the C libraries. On the
+Symbian platform, the 'System Call Adaptation Layer' runs in the context of
+the user side but is considered 'kernel-like' code. APIs that belong to this
+layer are tagged as <codeph>@internalComponent</codeph> and may only be extended
+by Symbian. </p> <p>Note that P.I.P.S. is not a Linux application environment
+- you cannot simply run an application that you've compiled for your Linux
+desktop. At a minimum, you will have to rebuild your application from source. </p> <p>For
+more information, see the <xref href="GUID-79100974-CAE1-5451-9ED7-E06C9B27131B.dita">Build
+Process</xref> section. </p> <p id="GUID-49C7F951-8317-5F41-B1B9-9F7B8803E655"><b>Glue
+code (CRT0)</b> </p> <p>Executables built for the Symbian platform enter via <codeph>E32Main()</codeph>,
+whereas Standard C applications expect to be started from <codeph>main()</codeph>.
+It is therefore necessary to have 'glue code' (formerly known as CRT0) between
+these two functions. The glue code is also responsible for allocating any
+system resources, obtaining system and environment data, and initialising
+the SCAL infrastructure prior to calling the <codeph>main()</codeph> function
+of the application. There are two versions of the glue code library - <filepath>libcrt0.lib</filepath> (for
+use by applications that enter via char <codeph>main()</codeph>) and <filepath>libwcrt0.lib</filepath> (for
+use by applications that enter via wide char <codeph>main()</codeph>). </p> <p>To
+include the glue code library you should explicity link to <filepath>libcrt0.lib</filepath> and <filepath>libwcrt0.lib</filepath> statically,
+however, if you are using the <codeph>STDEXE</codeph> or <codeph>STDDLL</codeph> target
+types, glue code will be added automatically. </p> <p id="GUID-1DDC11E7-D9D6-5251-89CE-981C4869D109"><b>P.I.P.S.
+Core libraries</b> </p> <p>Currently, the C libraries include the <codeph>libc</codeph>, <codeph>libm</codeph>,
+and <codeph>libpthread</codeph> (seeded from <xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) and <codeph>libdl</codeph> libraries. The
+APIs provided by these libraries are defined to be compliant, via compatibility
+features, with the POSIX standard. They are not officially certified as POSIX
+compatible but they conform to it mostly. </p> <p>The P.I.P.S. libraries include
+the following APIs: </p> <ul>
+<li id="GUID-95E53F0A-B919-5EEE-9A6F-427E87547088"><p> <codeph>stdio</codeph>,
+including <xref href="GUID-E69DB3CD-E6DA-3B1D-A499-AE68EC432CAC.dita"><apiname>print()</apiname></xref>, <xref href="GUID-58616261-FB60-37C5-9289-239144CD8FB8.dita"><apiname>scanf()</apiname></xref>, and so on </p> </li>
+<li id="GUID-5359692C-17C8-5486-9DCB-0A5B9AD1C90A"><p> <codeph>stdlib</codeph>,
+including environment variable support, and so on </p> </li>
+<li id="GUID-F0E19C9C-5581-5E47-A775-A6B57C22EE92"><p>string manipulation
+and character APIs </p> </li>
+<li id="GUID-B0F2B006-6D62-5DD6-9CDC-7ADFB693E77E"><p>locale and system services </p> </li>
+<li id="GUID-C5440DE9-24A2-5A34-A2A7-47E836E1545D"><p>searching, sort and
+pattern matching </p> </li>
+<li id="GUID-33D03F27-4B97-56CA-B4ED-67901701A1E2"><p>IPC mechanisms, including
+shared memory, pipes, FIFOs and message queues </p> </li>
+<li id="GUID-15AE7775-5FC8-59A4-924E-3987F9314F58"><p>process creation, including <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref>, <xref href="GUID-E7C4DE71-BC5B-34AE-ACB3-C34A0DB1FC16.dita"><apiname>posix_spawn()</apiname></xref> and <xref href="GUID-3D9040E5-F6FB-3DEA-9800-A55F0CEE7B08.dita"><apiname>system()</apiname></xref> </p> </li>
+<li id="GUID-2AEE41E3-A696-588C-9E5B-8E362E96D4B5"><p>networking and socket
+APIs </p> </li>
+<li id="GUID-ACF6B3A6-0F83-50D3-B0FB-FA765BDA408D"><p>mathematical and arithmetic
+APIs </p> </li>
+<li id="GUID-595D4C61-0FC9-5A05-BEDD-7412CEA585BA"><p>dynamic loading and
+symbol lookup </p> </li>
+<li id="GUID-DC3DB027-B384-52D1-8284-BF868A5CD543"><p>thread creation and
+synchronisation mechanisms. </p> </li>
+</ul> <p>Due to fundamental differences between Linux and the Symbian platform
+kernel architecture, there is no support for <xref href="GUID-432C9AA0-A698-3A62-95D8-CB010965F92C.dita"><apiname>fork()</apiname></xref> and <xref href="GUID-1F3AB7F6-B354-36DB-AA0C-D8F2DC89A6DD.dita"><apiname>exec()</apiname></xref>.
+For more information, see the <xref href="GUID-AF07AD54-86F1-5DB7-80FF-633A559DA4BD.dita">Process
+Creation</xref> section. </p> <p>The original seed directory structure (<xref href="http://www.freebsd.org/" scope="external">FreeBSD</xref>) is preserved
+as fully as possible to allow for future catch-ups to be performed more easily.
+The table below shows the original seed directory structure in FreeBSD. </p> <table id="GUID-A1D61A32-6F99-5B0A-B348-135373DC3AEA">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p> <b>Module</b> </p> </entry>
+<entry><p> <b>Description</b> </p> </entry>
+</row>
+<row>
+<entry><p> <filepath>core\libc</filepath> </p> </entry>
+<entry><p>Contains Standard C and POSIX APIs as defined by the Standard C
+and POSIX standards </p> </entry>
+</row>
+<row>
+<entry><p> <filepath>core\libm</filepath> </p> </entry>
+<entry><p>Contains the Standard C <codeph>Math</codeph> API as defined by
+Standard C </p> </entry>
+</row>
+<row>
+<entry><p> <filepath>core\libpthread</filepath> </p> </entry>
+<entry><p>Contains POSIX threading APIs as defined the POSIX standards </p> </entry>
+</row>
+<row>
+<entry><p> <filepath>core\libdl</filepath> </p> </entry>
+<entry><p>Contains APIs for dynamic loading and symbol lookup by name. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p>Although P.I.P.S. provides a wide range of APIs, some of the functionality
+required in order to complete a porting task might be missing - this could
+be some APIs from an existing library or an entire library. </p> <p>Several
+options are available to the user: </p> <ul>
+<li id="GUID-99935DCF-2678-5D76-98E9-8E94269E7CAC"><p>Port the missing APIs
+using the P.I.P.S. libraries </p> </li>
+<li id="GUID-FFA95C02-268F-5281-B0D3-5A4A64BC5A27"><p>Implement the missing
+APIs on top of the Symbian platform native C++ APIs </p> </li>
+<li id="GUID-D70619B7-E889-5D11-81C7-FD99420F3D1D"><p>Use a workaround - for
+example, use <xref href="GUID-A9DB6E7C-B8D6-377A-BBE6-39E0A7A09E5D.dita"><apiname>popen()</apiname></xref> instead of <codeph>fork()</codeph>. </p> </li>
+</ul> <p> <b>Note:</b> The following are the limitations associated with porting
+a UNIX® application: </p> <ul>
+<li id="GUID-4057ED21-65DD-5C20-A65B-B9228BE920BD"><p> <b>Limited stack-space:</b> The
+default stack size per thread on Unix-like operating systems ranges from 64
+kB to 1 MB. The Symbian platform, however, defines a default stack size of
+8 kB per thread. P.I.P.S. Pthreads use this by default. You can use the <codeph>pthread_attr_setstacksize()</codeph> function
+to modify this before calling <codeph>pthread_create()</codeph>. </p> </li>
+<li id="GUID-8329F811-34A6-5812-B033-2BE49C038D3E"><p> <b>Limited threads
+per process:</b> Assuming that all threads use the default stack size (8 kB),
+Symbian specifies a limit of 128 threads per process. The limit changes depending
+on the stack size you use for individual threads. For example, if you create
+your threads with a stack size of 16 kB, the OS only supports 64 threads per
+process. </p> </li>
+</ul> </section>
+</conbody><related-links>
+<link href="GUID-2016EF4B-F001-5EB2-8095-6048582511D6.dita"><linktext>P.I.P.S.
+Concepts</linktext></link>
+<link href="GUID-C4C85189-BA6F-5F11-ABB3-727D8C1F5984.dita"><linktext>P.I.P.S.
+Porting Tutorials</linktext></link>
+<link href="GUID-3EB1C34E-584E-595D-A339-DE170A96AEBC.dita"><linktext>P.I.P.S.
+Examples</linktext></link>
</related-links></concept>
\ No newline at end of file