<?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-9D278187-8B5E-581D-9869-EE8861048F93" xml:lang="en"><title>Dynamic

Link Libraries</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-5B4A95B4-FE2E-4541-B185-1B4590DE5974"><title>Introduction</title> <p>A

Dynamic Link Library (DLL) contains an executable code that can be shared

by many processes in a system at any one time. A program can link against

a DLL at compile time, meaning that the linker will match the DLL's symbols

(such as function names and variables) with references from the program and

ascertain the address within the DLL of the functions or variables. </p> <p>Alternatively

a program can dynamically load a DLL into memory during execution, locate

the address of a symbol, use it and then unload the DLL. Traditionally and

for greater memory efficiency, the Symbian platform links by

ordinal, whereas Unix-like operating systems link by name. The following sections

provide example code to illustrate how the DLL loader works with each operating

system. </p><p>The Symbian platform v9.3 kernel supports all functionalities

of P.I.P.S. libraries - referred to as "P.I.P.S.- ready". Pre v9.3 the kernel

only supports the Symbian platform- standard ordinal lookup in DLLs; it does

not support symbolic lookup. Thus the function <codeph>dlsym()</codeph> cannot

be used with a symbolic name. To overcome this restriction, pass the function's

ordinal number as symbol parameter refer the library's list of exports (the

DEF file) for the function's ordinal number. For example, instead of: <codeph>dlsym(&amp;handle,

"foo")</codeph> use <codeph>dlsym (&amp;handle, "3")</codeph> where the function <codeph>foo()</codeph> has

ordinal 3.</p> </section>

<section id="GUID-CCE3F3DC-307A-41F2-BAB4-523834C12E93"><title>Using shared

libraries in a Unix-like environment</title><p>The following code shows how

a shared library is dynamically loaded and used in a Unix-like environment

using the <codeph>dl</codeph> interface.</p><codeblock xml:space="preserve">int main(int argc, char *argv[])

{

  //Handle

  void* dll_handle;

  //Function prototype

  void (*printSum)(int a, int b);

  //Error message

  const char* errorMsg;

  //Filename of dll to load 

  char dllFileName[] = "/root/PortDoc/Example6/dll/shareddll";

  //Load the dll

  dll_handle = dlopen(dllFileName, RTLD_LAZY);

  if (!dll_handle)

  {

     fprintf(stderr, "Error during load of library: %s\n", dlerror()); 

     return EXIT_FAILURE;

  }

  //Find the symbol

  printSum = dlsym(dll_handle, "printSum");   

  //Get the error message 

  errorMsg = dlerror();

  if (errorMsg)

  {

     fprintf(stderr, "Error during symbol lookup: %s\n", errorMsg);

     return EXIT_FAILURE;

  } 

  //Now call the function

  printSum(4, 6);

  //Dispose of the DLL

  dlclose(dll_handle);

  return EXIT_SUCCESS;

}

</codeblock><p>As an example, the <codeph>shareddll</codeph> might have a

function such as:</p><codeblock xml:space="preserve">void printSum(int a, int b)

    {

    printf("Result is : %d\n", a + b);

    }</codeblock></section>

<section id="GUID-7C649A95-3F73-454B-AAD4-80889D6B34E3"><title>DLLs on the

Symbian platform(prior to v9.3)</title><p>Symbian platform programs uses the

function or variable's ordinal position within a DLL to link with DLLs. For

example, implementing a shared DLL on the Symbian platform could look like

this:</p><codeblock xml:space="preserve">EXPORT_C void printSum(int a, int b)

    {

    printf("Result is : %d\n", a + b);

    }</codeblock><p>Compiling this will generate a <filepath>.def</filepath> file,

which contains the ordinals of each symbol in the DLL. For instance:</p><codeblock xml:space="preserve">EXPORTS

    printSum @ 1 NONAME</codeblock><p>Here, the <filepath>.def</filepath> shows

that the ordinal for the <codeph>printSum()</codeph> function is 1. </p><p>The

following code shows how the <codeph>main()</codeph> function is changed in

P.I.P.S.. </p><codeblock xml:space="preserve">int main(int argc, char *argv[])

{

  //Handle

  void* dll_handle;

  //Function prototype

  void (*printSum)(int a, int b);

  //Error message

  const char* errorMsg;

  //Filename of dll to load 

  char dllFileName[] = "/root/PortDoc/Example6/dll/shareddll";

  //Load the dll

  dll_handle = dlopen(dllFileName, RTLD_LAZY);

  if (!dll_handle)

  {

     fprintf(stderr, "Error during load of library: %s\n", dlerror()); 

     return EXIT_FAILURE;

  }

  //Find the symbol, using the ordinal

  printSum = dlsym(dll_handle, "1");   

  //Get the error message 

  errorMsg = dlerror();

  if (errorMsg)

  {

     fprintf(stderr, "Error during symbol lookup: %s\n", errorMsg);

     return EXIT_FAILURE;

  } 

  //Now call the function

  printSum(4, 6);

  //Dispose of the DLL

  dlclose(dll_handle);

  return EXIT_SUCCESS;

}

</codeblock><p>Note that for the Symbian library loader, the mode parameter

for the <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref> function is irrelevant and the library

will be loaded immediately. So although <codeph>RTLD_LAZY</codeph> is the

mode parameter in the example, it will behave just as <codeph>RTLD_NOW</codeph>.

Also note that there is no facility to call any library constructor and destructor

functions using <codeph>__attribute((constructor))</codeph> or <codeph>__attribute((destructor))</codeph>. </p></section>

<section id="GUID-DEF804DF-CECC-4739-9ACD-24F46A945F6E"><title>DLLs on the

Symbian platform (v9.3 onwards)</title><p>P.I.P.S. provides APIs from libdl

to support dynamic lookup by name, which is used in Unix-like platforms, instead

of the native Symbian platform lookup by ordinal mechanism. Lookup by name

is possible thanks to the new libdl, which in turn uses the existing <ph>RLibrary</ph> functions

to load and unload DLLs. </p><p>A symbol name lookup version of the dlsym()

function is provided, similar to UNIX®, which does not need any special treatment

(the example shown in the <b>Using Shared libraries in a Unix-like environment</b> section

will suffice). However, it is still necessary to generate the <filepath>.def</filepath> file

for the DLL. The following sections provides a brief summary of the functionality

provided by <codeph>libdl</codeph>. </p><p>The <codeph>libdl</codeph> APIs,

which support dynamic lookup by name, are described in the following table:</p><table id="GUID-71331BB8-6E91-4239-9183-F4B51A383F06">

<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

<tbody>

<row>

<entry><p><b>libdl API</b></p></entry>

<entry><p><b>Description</b></p></entry>

</row>

<row>

<entry><codeph>void *dlopen (const char *path, int mode) </codeph></entry>

<entry><p>Call <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref> to gain access to symbols of any

shared library or DLL. If <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref> fails for any reason,

it will return a NULL. The default search path for the library can be provided

in the environment variable <codeph>LD_LIBRARY_PATH</codeph>. </p></entry>

</row>

<row>

<entry><codeph>void *dlsym(void *handle, const char *symbol)</codeph></entry>

<entry><p>The <xref href="GUID-6B94A42A-888B-3761-84DA-4FADC6D3B126.dita"><apiname>dlsym()</apiname></xref> function returns the address binding

of the symbol described in the null-terminated character string 'symbol',

as it occurs in the shared object identified by 'handle'. </p></entry>

</row>

<row>

<entry><codeph>int dlclose(void *handle)</codeph></entry>

<entry><p>Call <xref href="GUID-F74DC7CB-1E3F-368E-99A7-DD4B38FF7EF0.dita"><apiname>dlclose()</apiname></xref> with a valid dlopen-ed handle

to remove it from the cache list maintained by <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref>.

If it fails, dlclose() will return -1; otherwise, it will return 0. </p></entry>

</row>

<row>

<entry><codeph>char *dlerror(void)</codeph></entry>

<entry><p>Call <xref href="GUID-F5B2CFAB-99F5-3A24-8F6C-ECAA61922FB0.dita"><apiname>dlerror()</apiname></xref> to obtain the most recent error

that occurred due to any of the dl routines, that is, <xref href="GUID-51FB35C0-CFC2-357A-8ACA-FE7480C53AD3.dita"><apiname>dlopen()</apiname></xref>, <xref href="GUID-6B94A42A-888B-3761-84DA-4FADC6D3B126.dita"><apiname>dlsym()</apiname></xref>,

or <xref href="GUID-F74DC7CB-1E3F-368E-99A7-DD4B38FF7EF0.dita"><apiname>dlclose()</apiname></xref>. </p></entry>

</row>

</tbody>

</tgroup>

</table><p/></section>

</conbody><related-links>

<link href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-3CA8FF29-79B4-5D43-8A23-EDB136BF7A8F">

<linktext>One Definition Rule - warning</linktext></link>

</related-links></concept>