<?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-6590B534-D976-5305-BE95-48DD05120DFB" xml:lang="en"><title>Miscellaneous

Topics</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-6830949E-0825-5E13-9B3E-86B5014F4B77"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-624B9EC6-7C8E-5408-AAF3-F799314B6D7A">Poll using select</xref>  </p> <ul>

<li id="GUID-7E0FA15B-8AFB-59DD-B577-34905989D316"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-6B8931EB-7AB9-588C-B419-0CD4BA048397">Monitoring two pipes using select()</xref>  </p> </li>

</ul> </li>

<li id="GUID-245A31A4-4C38-54F4-9ACC-92285C12966E"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-7582B2CB-AAC8-5E41-ADE1-76C12B691E10">Socket IOCtl options</xref>  </p> </li>

<li id="GUID-1A2BDA7D-2DE4-52AE-ACD3-12D1A6311A88"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-9BF9562E-5831-5A7F-90A1-87BDE1CFBA54">Mathematical functions</xref>  </p> </li>

<li id="GUID-A6183A50-BFBA-573B-B2BC-68BE637D7DF5"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-DA65E8FA-E20B-5572-AEC9-20AB140DF33A">Error handling and cleanup</xref>  </p> <ul>

<li id="GUID-ADB0AC3E-FB59-52DC-B151-A4551467CBA0"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-D8DB43BD-9D19-5A78-8E37-6699653D047A">Mapping P.I.P.S. error codes to the Symbian platform error codes</xref>  </p> </li>

</ul> </li>

<li id="GUID-EA748131-29ED-5D32-B1C2-F948ABEA6584"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-CF52A59F-FD04-5043-A526-05545E11F0F5">System logger</xref>  </p> </li>

<li id="GUID-1C98EDF4-C7BD-5CC8-90EB-D35B759280CD"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-8C951D9F-DE32-5201-90F2-45EB442F9FFC">Pthread barriers, rwlocks and spinlocks</xref>  </p> </li>

<li id="GUID-AFB6D3DE-B1ED-51CF-B02D-BBF1958F6357"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-777FDBF9-4B80-5B58-88F3-E78DBDB89021">Command line shell</xref>  </p> </li>

<li id="GUID-2357315B-21A6-5A9D-8D8D-B72043376F41"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-98FE0A61-A9F6-5216-A01F-A213F33D3173">User interfaces</xref>  </p> </li>

<li id="GUID-EB745371-907B-595B-AD2F-0FB0B7991066"><p><xref href="GUID-6590B534-D976-5305-BE95-48DD05120DFB.dita#GUID-6590B534-D976-5305-BE95-48DD05120DFB/GUID-3CA8FF29-79B4-5D43-8A23-EDB136BF7A8F">One Definition Rule - warning</xref>  </p> </li>

</ul>

<section id="GUID-624B9EC6-7C8E-5408-AAF3-F799314B6D7A"><title>Poll using

select</title> <p>The <xref href="GUID-8B4D4123-8146-3157-B171-28F71E0C8E4A.dita"><apiname>select()</apiname></xref> function call provides functionality

to scan descriptors for a ready event. The <codeph>select()</codeph> call

requires the system to scan through a bit mask of a file descriptor set against

its list of open descriptors to check for ready events, only stopping when

it reaches a maximum descriptor value. For a system with a relatively small

number of open descriptors this is quite efficient but for a large amount

of descriptors can be overly burdensome. </p> <p>The Symbian P.I.P.S. libraries

are not expected to be dealing with a very large number of file descriptors

and so <codeph>select()</codeph> should be satisfactory for any applications

on a phone. </p> <p> <b>Note:</b> P.I.P.S. does not support the <codeph>poll()</codeph> function. </p> <p id="GUID-6B8931EB-7AB9-588C-B419-0CD4BA048397"><b>Monitoring two pipes using

select()</b> </p> <p>The following code segment shows the usage of the <codeph>select()</codeph> function: </p> <codeblock id="GUID-36B78671-0A09-529C-B167-8F3E10C2CCB5" xml:space="preserve">Int main(int argc, char **argv)

{

   FILE* ChildProcessStream1;

   FILE* ChildProcessStream2;

   int ChildProcessFD1;

   int ChildProcessFD2;

   fd_set SelectFDs;

   int MaxFD;

   struct timeval timeout;

   int Ret;

   //Create child process 1 using popen(). 

   ChildProcessStream1 = popen("/root/PortDoc/Example7_c/Symbian/Child/ChildProg", "r");

   if(ChildProcessStream1 == NULL)

   {

      printf("\n Failure to create child process 1 with popen()\n");

      return EXIT_FAILURE;

   }

   //Create child process 2 using popen(). 

   ChildProcessStream2 = popen("/root/PortDoc/Example7_c/Symbian/Child/ChildProg", "r");

   if(ChildProcessStream2 == NULL)

   {

      printf("\n Failure to create child process 2 with popen()\n");

      return EXIT_FAILURE;

   }

   //Convert streams to file descriptors

   ChildProcessFD1 = fileno(ChildProcessStream1);

   ChildProcessFD2 = fileno(ChildProcessStream2);

   //Setup the select set

   FD_ZERO(&SelectFDs);

   FD_SET(ChildProcessFD1, &SelectFDs);

   MaxFD = ChildProcessFD1;

   FD_SET(ChildProcessFD2, &SelectFDs);

   //Calculate the largest Descriptor

   if (ChildProcessFD2 > MaxFD)

      MaxFD = ChildProcessFD2;

   //Setup a time out value in case neither return in a sufficient time

   timeout.tv_sec = 3;

   timeout.tv_usec = 0;

   //Issue select request

   Ret = select(MaxFD + 1, &SelectFDs, NULL, NULL, &timeout);

   if (Ret == -1)

   {

      //Error occurred

      printf("\nCould not poll, error=%d",errno);    

      return EXIT_FAILURE;

   }

   else if (Ret == 0)

   {

      //Timed out

      printf("\nTimed Out");    

   }

   else

   {

      //Create a receive buffer, and zero contents before receiving.

      Char RxBuffer[100];

      memset(RxBuffer,0,sizeof(RxBuffer));

      if (FD_ISSET(ChildProcessFD1, &SelectFDs))

      {

         //Wait for data from child process 1. Child sends a string.

         Int nbytes = read(ChildProcessFD1,RxBuffer,sizeof(RxBuffer));

         printf("\nMessage Received from Child1 First =%s",RxBuffer);

      }

      else if (FD_ISSET(ChildProcessFD2, &SelectFDs))

      {

         //Wait for data from child process 2. Child sends a string.

         Int nbytes = read(ChildProcessFD2,RxBuffer,sizeof(RxBuffer));

         printf("\nMessage Received from Child2 First =%s",RxBuffer);

      }

   }

   //Wait for Child Process to complete

   pclose(ChildProcessStream1);

   pclose(ChildProcessStream2);

   return EXIT_SUCCESS;

}</codeblock> </section>

<section id="GUID-7582B2CB-AAC8-5E41-ADE1-76C12B691E10"><title>Socket IOCtl

options</title> <p>The underlying implementation of sockets on the Symbian

platform imposes some restrictions on the socket options available in P.I.P.S.

and has also resulted in some new non-standard options to be created. </p> <p>The

introduction of multi-homing (single link, multiple IP addresses) on Symbian

phones and the various methods of connecting to networks, such as Wi-Fi and

3G, with their varying degrees of cost to the user have made it important

to be able to choose which interface or access point is used to route socket

traffic. The Symbian <xref href="GUID-BED8A733-2ED7-31AD-A911-C1F4707C67FD.dita"><apiname>RConnection</apiname></xref> class provides this functionality,

and is exposed in P.I.P.S. using some extra IOCtl options. </p> <p>The list

of socket options available in P.I.P.S. are as follows: </p> <table id="GUID-B753C24D-597E-53AB-A633-C128C7316514">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<tbody>

<row>

<entry><p> <b>Socket Option</b>  </p> </entry>

<entry><p> <b>New</b>  </p> </entry>

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

</row>

<row>

<entry><p>SIOCADDRT </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Adds an entry to the interface routing table using the parameters

in the <codeph>rtentry</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCATMARK </p> </entry>

<entry><p>No </p> </entry>

<entry><p>Determines whether the read pointer is currently pointing to the

logical mark in the data stream, testing whether the next read will be Out-of-Band

data or not. </p> </entry>

</row>

<row>

<entry><p>SIOCDELRT </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Deletes an entry from the interface routing table using the parameters

in the <codeph>rtentry</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCGIFACTIVECONF </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Gets a list of interfaces/access points started by P.I.P.S. in an <codeph>ifconf</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCGIFADDR </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Gets the interface address. This is valid only for sockets with

address family AF_INET. </p> </entry>

</row>

<row>

<entry><p>SIOCGIFCONF </p> </entry>

<entry><p>No </p> </entry>

<entry><p>Gets a list of available interfaces/access points in an <codeph>ifconf</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCGIFHWADDR </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Gets the interface hardware address in an <codeph>ifreq</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCGIFINDEX </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Sets the index of an interface/access point from a name in an <codeph>ifreq</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCGIFNUM </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Return the total number of IP interfaces configured in the system. </p> </entry>

</row>

<row>

<entry><p>SIOCIFACTIVESTART </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Attempts to start a sub-connection on an available interface/access

point using the parameters in an <codeph>ifreq</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCIFSTART </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Attempts to start an interface/access point using the parameters

in an <codeph>ifreq</codeph> structure. </p> </entry>

</row>

<row>

<entry><p>SIOCIFSTOP </p> </entry>

<entry><p>Yes </p> </entry>

<entry><p>Stops a previously started interface or sub-connection. </p> </entry>

</row>

<row>

<entry><p>SIOCSIFNAME </p> </entry>

<entry><p>No </p> </entry>

<entry><p>Sets the desired interface/access point name to start in an <codeph>ifreq</codeph> structure. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The follow code for a function shows how to start an interface

called "3G Access Point" and return the created socket. </p> <codeblock id="GUID-94D8CA06-366E-5697-A72B-891C07F21F8E" xml:space="preserve">int opensocket()

{

  int Sock;

  struct ifreq Ifr;

  char AccessPoint[]="3G Access Point";

  //Open the socket

  Sock = socket(AF_INET, SOCK_STREAM, 0);

  if (Sock < 0) 

  {

    printf("\nCannot open socket, error=%d",errno);

    return -1;

  }

  //Set up the interface request structure

  bzero(&Ifr, sizeof(Ifr));

  strcpy(Ifr.ifr_name, AccessPoint);

  //Set the requested interface name

  if (ioctl(Sock, SIOCSIFNAME, &Ifr))

  {

    printf("\nCannot set the interface name, error=%d",errno);

    close(Sock);

    return -1;

  }

  //Start the interface

  if (ioctl(Sock, SIOCIFSTART, &Ifr))

  {

    printf("\nCannot start the interface, error=%d",errno);

    close(Sock);

    return -1;

  }

  //Return the opened socket

  return Sock;

}</codeblock> </section>

<section id="GUID-9BF9562E-5831-5A7F-90A1-87BDE1CFBA54"><title>Mathematical

functions</title> <p>The Symbian platform does not have any support for long

doubles so any P.I.P.S. programs which call long double versions of APIs will

actually invoke the double version of the API. </p> <p>The Symbian platform

supports the use of a hardware floating point co-processor, however not all

phones incorporate an FPU (Floating Point Unit) and rely on software emulation

of floating point operations. Phones and computers equipped with an FPU provide

faster and more accurate floating point operations. </p> <p>The Symbian platform

does not support complex numbers so the P.I.P.S. libraries are not able to

offer the POSIX complex number APIs. </p> <p> <b>Note:</b> The mathematical

functions are included in the <filepath>libm.dll</filepath> file. </p> </section>

<section id="GUID-DA65E8FA-E20B-5572-AEC9-20AB140DF33A"><title> Error handling

and cleanup</title> <p>It is important that the Symbian platform error codes

do not reach any ported application code. P.I.P.S. logically maps the native

OS error codes with the corresponding POSIX <codeph>errno</codeph> values

as per the standard. So, ported programs will not usually have to alter their

error checking/handling. </p> <p id="GUID-D8DB43BD-9D19-5A78-8E37-6699653D047A"><b>Mapping

P.I.P.S. error codes to the Symbian platform error codes</b> </p> <p>Porting

your application to the Symbian platform requires 'translating' the Symbian

platform error codes to POSIX error codes. <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-B00F7659-9C31-36CD-896A-40887DECEA4B"><apiname>User::Leaves()</apiname></xref> from

native Symbian APIs are trapped in P.I.P.S.. Calls to P.I.P.S. APIs from user

code need not be wrapped in <xref href="GUID-3AD20E0C-F364-533F-9FBC-227478CA9982.dita">TRAP</xref> s. </p> <p>Occasionally

errors may be generated by the underlying Symbian platform that cannot be

translated to POSIX error codes, in which case the error variable <codeph>errno</codeph> will

be out of the usual range of values, above the maximum value of <codeph>__EMAXERRNO</codeph> or <codeph>124</codeph>. </p> <p>The

Symbian platform error code can be calculated using the following formula: </p> <codeblock id="GUID-A2F7B744-4B73-56AB-BA06-7C83333ADC5D" xml:space="preserve">Symbian Error Code = -(errno - __EMAXERRNO)</codeblock> <p>Error

codes are defined in the <filepath>errno.h</filepath> file. </p> </section>

<section id="GUID-CF52A59F-FD04-5043-A526-05545E11F0F5"><title>System logger</title> <p>P.I.P.S.

does not supply a system logger for use with <xref href="GUID-0138AF2F-50A6-3FAD-8AE9-FDBFD66E5EF5.dita"><apiname>openlog()</apiname></xref>, <xref href="GUID-CCBCF015-F7CF-3A55-A723-0BC4B4DC758C.dita"><apiname>syslog()</apiname></xref> and <xref href="GUID-57C7FF8B-7EB3-35BE-BC9B-5FD6ABEE6225.dita"><apiname>closelog()</apiname></xref>.

Instead, a rudimentary selection of functions which log to a file can be written

as demonstrated by the following example. </p> <codeblock id="GUID-EE476405-2657-5827-81F4-DD5A29BF9F35" xml:space="preserve">//define maximum length of identifier

#define SysLogMax 80

//logging file and identifier

FILE* fSysLog = NULL;

char fSysLogIdent[SysLogMax];

//close the log file

void my_closelog()

{

   //close the log file if it is open

   if (fSysLog)

   {

      fclose(fSysLog);

      fSysLog = NULL;

   }

   fSysLogIdent[0] = '\0';

}

//open a new log file

int my_openlog(const char *ident)

{

   //close the log file if it is open

   if (fSysLog)

      my_closelog();    

   //make the logging directory

   mkdir("/syslog/", S_IWUSR | S_IRUSR | S_IXUSR);

   //open a new log file

   fSysLog = fopen("/syslog/syslog.log", "a");

   //return if the log file did not open

   if (!fSysLog)

      return -1;

   //set the identifier

   if (!ident)

      fSysLogIdent[0] = '\0';

   else    

      strncpy(fSysLogIdent, ident, SysLogMax);

   return 0;

}

//output a string to the log file with a variable argument list

void my_vsyslog(const char *format, va_list formatlist)

{

   //open a log file if one does not exist

   if (!fSysLog)

   {

      my_openlog(NULL);    

   }

   //check if there is a log file 

   if (fSysLog)

   {

      //print out the logging identifier if one exists

      if (strlen(fSysLogIdent))

      {

         fprintf(fSysLog, "%s ", fSysLogIdent);

      }

      //print out the logging string

      vfprintf(fSysLog, format, formatlist);    

      fprintf(fSysLog, "\r\n");    

   }

}

//output a string to the log file

void my_syslog(const char *format, ...)

{

   //create the variable argument list

   va_list formatlist;

   va_start(formatlist, format);

   my_vsyslog(format, formatlist);

   va_end(formatlist);

}

int main(int argc, char **argv)

{

   //open the log file

   my_openlog("test");

   //log a line

   my_syslog("testing logging of the error number : %d", errno);

   //close the log

   my_closelog();

   return EXIT_SUCCESS;

}</codeblock> </section>

<section id="GUID-8C951D9F-DE32-5201-90F2-45EB442F9FFC"><title>Pthread barriers,

rwlocks and spinlocks</title> <p>At present P.I.P.S. does not provide Pthread

barriers, rwlocks or spinlocks, but there are techniques which can be used

to implement the functionality using semaphores, mutexes and conditional variables. </p> <p>The

following code sample (originally taken from <xref href="http://heather.cs.ucdavis.edu/matloff/public_html/158/PLN/ParProcIntro.pdf" scope="external">http://heather.cs.ucdavis.edu/matloff/public_html/158/PLN/ParProcIntro.pdf</xref>)

demonstrates an implementation of a simple Pthread barrier. </p> <codeblock id="GUID-A156CD2D-F212-57EA-A23A-C7B7478B431E" xml:space="preserve">struct barrier_t

{

   //number of nodes to synchronise

   int nodes;

   //two counts to avoid race conditions

   int count[2];

   //which count to use

   int whichcount;

   //mutex to lock

   pthread_mutex_t lock;

   //condition to lock

   pthread_cond_t cv;

};

//initialize a barrier 

void InitBarrier(struct barrier_t* PB, int nodes)

{

   PB->nodes = nodes;

   PB->count[0] = 0;

   PB->count[1] = 0;

   PB->whichcount = 0;

   pthread_mutex_init(&PB->lock, NULL);

   pthread_cond_init(&PB->cv, NULL);

}

//destroy a barrier

void DestroyBarrier(struct barrier_t* PB)

{

   pthread_mutex_destroy(&PB->lock);

   pthread_cond_destroy(&PB->cv);

}

//wait for a barrier

void WaitBarrier(struct barrier_t* PB)

{

   int WhichCount, Count;

   //which counter variable to use

   WhichCount = PB->whichcount;

   //lock the mutex

   pthread_mutex_lock(&PB->lock);

   //get the count of nodes

   Count = ++PB->count[WhichCount];

   //test whether it should block

   if (Count < PB->nodes)

      pthread_cond_wait(&PB->cv, &PB->lock);

   else

   { 

      //reset the counter

      PB->count[WhichCount] = 0;

      PB->whichcount = 1 - WhichCount;

      //release the wait

      pthread_cond_broadcast(&PB->cv);

   }

   //unlock the threads

   pthread_mutex_unlock(&PB->lock);

}</codeblock> <p>The following code was posted by Michael M. Lampkin as an

open source implementation of Pthread spin threads. </p> <codeblock id="GUID-85F81360-113F-54DC-958E-7C76BC8BA98D" xml:space="preserve">/**********************************************************************

BETA User Space spinlocks for POSIX systems lacking this functionality.

Copyright ©) 2003-2006 Michael M. Lampkin 

Contact at michael.lampkin<at>ieee.org

This program is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License version 2 as

published by the Free Software Foundation.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

version 2 along with this program; if not, write to the Free Software

Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301

**********************************************************************/

#define _POSIX_C_SOURCE 200112L

#define _XOPEN_SOURCE 600

#define SPINLOCK_SPIN_MAX 50

/**

 Need this "unique" value that we can use to take any spinlock

 that has been initialized and identify attempts to call init

 multiple times without corresponding calls to destroy.  A hard

 coded value should be fine though still a 1 in 4 billion chance

 of collision with random data in un-inited spinlock.

**/

static long int spin_magic = 0x2FCD51F9L;

/**

  The spinlock structure which should NEVER be manipulated

  by user code.

  owner:

    a pthread_t var indicating the current owner of the

    spinlock or filled with 0's if not owned

  mutex:

    the primary mutex that any incoming threads will spin on

    and attempt to obtain.

  magic:

    a field to hold a sentinel value indicating if the spinlock

    is initialized.

**/

typedef struct

{

  pthread_t       owner;

  pthread_mutex_t mutex;

  long int        magic;

}