<?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-BE893F87-E7F6-56E5-BD27-328B532F8332" xml:lang="en"><title>Hello World Example: Using P.I.P.S.</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This example application shows a simple EXE and DLL written using
P.I.P.S. (P.I.P.S. Is POSIX on Symbian Platform). It also shows the
dynamic lookup of symbols by name mechanism used in Unix-like operating
systems, instead of the native Symbian Platform lookup by ordinal
mechanism. P.I.P.S., from Symbian OS v9.3, provides APIs from <filepath>libdl</filepath> library to implement this lookup by name mechanism. </p>
<p>The example defines a simple DLL using the P.I.P.S. <codeph>STDDLL</codeph> target type, with an exported function. It also creates a simple
EXE, using the <codeph>STDEXE</codeph> target type, which calls the
DLL's exported function using the lookup by name mechanism. These
P.I.P.S. specific target types are required to enable the specific
options for compilers and linkers to generate P.I.P.S. executables
and to make symbol information available in the executable image. </p>
<section id="GUID-F39633E1-9E29-45BA-9F11-66E011B16687"><title>Download</title> <p>Click on the following link to
download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-42af5ea2-87c6-46ef-b872-af35876c73c7.zip" scope="external">HelloWorldExample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-42af5ea2-87c6-46ef-b872-af35876c73c7.html" scope="peer">browse</xref> to view the example code. </p> </section>
<section id="GUID-459D68E3-EC28-4F21-858A-10678A443EEE"><title>Description</title> <p>The following sections provide
more information about the example. </p> <p><b> Creating a simple
DLL using P.I.P.S. STDDLL target type</b> </p> <p>The example creates
a DLL file that declares and defines an exported function. The target
type of this DLL file is <codeph>STDDLL</codeph>. It contains a header
and a source file: </p> <ul>
<li id="GUID-A0857840-AD8C-5313-A642-801A79382855"><p> <filepath>helloworlddllexample.h</filepath>: this declares a function with external linkage. Note that for a <codeph>STDDLL</codeph> library, functions and data with external linkage
are exported by default, without any requirement for <codeph>IMPORT_C</codeph> and <codeph>EXPORT_C</codeph> declarations in header or source files. </p> </li>
<li id="GUID-973CE8AE-5B87-5234-8145-20A6632E7F9C"><p> <filepath>helloworlddllexample.cpp</filepath>: this defines the function declared in the header file, which displays
a hello world message to the console. </p> </li>
</ul> <p><b> Creating a simple EXE using P.I.P.S. STDEXE target type</b> </p> <p>The example creates an EXE file which calls the exported
function of the loaded DLL. The target type of this EXE file is <codeph>STDEXE</codeph>. It calls the following <filepath>libdl</filepath> functions to use the lookup by name mechanism: </p> <ul>
<li id="GUID-08422DA9-EE4F-502C-8D31-EB19BC86F98B"><p> <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref>: This function is used to load the DLL file which contains an exported
function. </p> </li>
</ul> <ul>
<li id="GUID-0EC17FCA-7B6A-5FBF-8693-1C4BD629F553"><p> <xref href="GUID-312604D7-59D9-3C67-9D4F-42CFA24EAA2B.dita"><apiname>dlsysm()</apiname></xref>: This function gets the address of a symbol defined within the DLL
loaded by the <codeph>dlopen()</codeph> call. </p> </li>
</ul> <ul>
<li id="GUID-EFC5BA53-F378-5D2B-A550-1055DA8CBAD7"><p> <xref href="GUID-F74DC7CB-1E3F-368E-99A7-DD4B38FF7EF0.dita"><apiname>dlclose()</apiname></xref>: This function informs the system that the DLL loaded by a previous <codeph>dlopen()</codeph> call is no longer needed by the application. </p> </li>
</ul> <ul>
<li id="GUID-B6003F4A-8919-5D15-844E-294A9020A2C2"><p> <xref href="GUID-F5B2CFAB-99F5-3A24-8F6C-ECAA61922FB0.dita"><apiname>dlerror()</apiname></xref>: This function is used to get the last error that occurred from
any of the <filepath>libdl</filepath> APIs. </p> </li>
</ul> <p>The EXE links to <filepath>libdl.lib</filepath> to use these
functions. </p> </section>
<section id="GUID-15EDF774-BC24-4BD5-A185-697DCFDCF732"><title>Build</title> <p>The <filepath>HelloWorldExample</filepath> builds two files, a DLL file <filepath>helloworlddllexample.dll</filepath>, and an EXE file <filepath>helloworldexeexample.exe</filepath>,
in the standard locations. </p> <p>To run the example, start <filepath>helloworldexeexample.exe</filepath> from the file system or from
your IDE. After launching the executable, depending on the emulator
you are using, you may need to navigate away from the application
launcher or shell screen to view the console. </p> </section>
</conbody></concept>