<?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_d0e193406_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_d0e193465_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>