<?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. </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_d0e194016_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_d0e194075_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 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>