1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-66C1493D-5B85-558A-9A39-454E6EBA307B" xml:lang="en"><title>Signal

    13 Emulation on Symbian Platform</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>The <codeph>libc</codeph> library of P.I.P.S. provides support for POSIX

    15 signals, thereby facilitating the porting of applications that use signals

    16 for exception handling and as control IPC. </p>

    17 <p>P.I.P.S. supports POSIX signals by emulating them in user-side code. This

    18 is different from the UNIX architecture, where the kernel manages the generation

    19 and delivery of signals, and has important implications. </p>

    20 <ul>

    21 <li id="GUID-22658912-1F1E-5C77-9DE1-5210B898CFF0"><p>Signals are always handled

    22 in the context of a signal-handler thread created by the P.I.P.S. backend.

    23 For this reason, signals cannot be directed to a particular thread. </p> </li>

    24 <li id="GUID-4EFC9E19-4031-553B-AF88-546665FA37DB"><p>Before the handler function

    25 of a signal is invoked in the signal-handler thread, all other threads are

    26 suspended. When the handler function returns, the other threads resume. This

    27 is done to mirror the UNIX behaviour of process execution being suspended

    28 when a signal is being handled. </p> </li>

    29 <li id="GUID-177E6544-106B-5E8B-94C6-B0AAD6437C4C"><p>There might be a considerable

    30 amount of latency when you send or receive signals. </p> </li>

    31 </ul>

    32 <section><title>Sending signals</title> <p>Signals can be sent between P.I.P.S.

    33 processes using <xref href="GUID-16DC4A9D-44BC-36E2-AB97-5E9E7521937D.dita"><apiname>kill()</apiname></xref>, <xref href="GUID-EB7F74AE-091B-32C3-9D73-18B82F8D3D73.dita"><apiname>raise()</apiname></xref> or <xref href="GUID-3C70BF0B-CD6E-3A30-A9E6-4CCF11D47EEC.dita"><apiname>sigqueue()</apiname></xref>. </p> <p>You

    34 can use these functions to send any of the supported signals (refer to the

    35 following table). </p> <p>The P.I.P.S. runtime sends the following signals

    36 to P.I.P.S. processes: </p> <ul>

    37 <li id="GUID-6F1D5A0A-4562-55B4-8E70-BAFF45F3EFA9"><p> <b>SIGPIPE:</b> This

    38 signal is sent to a process which attempts to write to a broken <xref href="GUID-EC7F85FF-FD4E-324C-8D01-EF6F7E7A79FE.dita"><apiname>pipe()</apiname></xref>. </p> </li>

    39 <li id="GUID-99788FD7-4E26-5979-8E39-BA12F24D1DA9"><p> <b>SIGCHLD:</b> This

    40 signal is sent to a parent process when a child process exits. </p> </li>

    41 <li id="GUID-D41E5F22-0893-5F61-A4F6-E72239205928"><p> <b> SIGALRM:</b> This

    42 signal is sent to a process when an alarm registered by the process times

    43 out. </p> </li>

    44 </ul> <p> <b>Note:</b> Always ensure that you handle <codeph>SIGPIPE</codeph>, <codeph>SIGCHLD</codeph> or <codeph>SIGALRM</codeph> using

    45 a signal handler to avoid the termination of the process receiving these signals.

    46 For more information about handling signals, see the following section. </p> </section>

    47 <section><title>Handling signals</title> <p>A signal can be received by a

    48 process at any time and is handled immediately, unless it is currently blocked.

    49 You can handle a signal in the following ways: </p> <ol id="GUID-F03B299F-A527-5365-81D3-DDDC607A4094">

    50 <li id="GUID-DF0E70C8-74C2-5ACC-B556-8D216275C554"><p> <b>Use default handling:</b> The

    51 default action for each signal supported on Symbian platform is listed in

    52 the following table. </p> <p> <b>Note:</b> The default action for all of the

    53 signals sent by the P.I.P.S. runtime (<codeph>SIGPIPE</codeph>, <codeph>SIGCHLD</codeph> or <codeph>SIGALRM</codeph>)

    54 is process termination. You must provide a custom handler for each of these

    55 signals. </p> <table id="GUID-7101041B-CC50-5367-A3A2-6D15FB15C3DD">

    56 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

    57 <thead>

    58 <row>

    59 <entry>Signal </entry>

    60 <entry>Default Action</entry>

    61 </row>

    62 </thead>

    63 <tbody>

    64 <row>

    65 <entry><p> <codeph>SIGHUP</codeph>  </p> </entry>

    66 <entry><p>Ignore </p> </entry>

    67 </row>

    68 <row>

    69 <entry><p> <codeph> SIGINT</codeph>  </p> </entry>

    70 <entry><p>Ignore </p> </entry>

    71 </row>

    72 <row>

    73 <entry><p> <codeph>SIGQUIT</codeph>  </p> </entry>

    74 <entry><p>Ignore </p> </entry>

    75 </row>

    76 <row>

    77 <entry><p> <codeph> SIGILL</codeph>  </p> </entry>

    78 <entry><p>Ignore </p> </entry>

    79 </row>

    80 <row>

    81 <entry><p> <codeph> SIGTRAP</codeph>  </p> </entry>

    82 <entry><p>Ignore </p> </entry>

    83 </row>

    84 <row>

    85 <entry><p> <codeph> SIGABRT</codeph>  </p> </entry>

    86 <entry><p>Ignore </p> </entry>

    87 </row>

    88 <row>

    89 <entry><p> <codeph> SIGIOT</codeph>  </p> </entry>

    90 <entry><p>Ignore </p> </entry>

    91 </row>

    92 <row>

    93 <entry><p> <codeph> SIGEMT</codeph>  </p> </entry>

    94 <entry><p>Ignore </p> </entry>

    95 </row>

    96 <row>

    97 <entry><p> <codeph> SIGFPE</codeph>  </p> </entry>

    98 <entry><p>Ignore </p> </entry>

    99 </row>

   100 <row>

   101 <entry><p> <codeph> SIGKILL</codeph>  </p> </entry>

   102 <entry><p>Process termination </p> </entry>

   103 </row>

   104 <row>

   105 <entry><p> <codeph> SIGBUS</codeph>  </p> </entry>

   106 <entry><p>Ignore </p> </entry>

   107 </row>

   108 <row>

   109 <entry><p> <codeph> SIGSEGV</codeph>  </p> </entry>

   110 <entry><p>Ignore </p> </entry>

   111 </row>

   112 <row>

   113 <entry><p> <codeph> SIGSYS</codeph>  </p> </entry>

   114 <entry><p>Ignore </p> </entry>

   115 </row>

   116 <row>

   117 <entry><p> <codeph> SIGPIPE</codeph>  </p> </entry>

   118 <entry><p>Process termination </p> </entry>

   119 </row>

   120 <row>

   121 <entry><p> <codeph> SIGALRM</codeph>  </p> </entry>

   122 <entry><p>Process termination </p> </entry>

   123 </row>

   124 <row>

   125 <entry><p> <codeph> SIGTERM</codeph>  </p> </entry>

   126 <entry><p>Process termination </p> </entry>

   127 </row>

   128 <row>

   129 <entry><p> <codeph> SIGURG</codeph>  </p> </entry>

   130 <entry><p>Ignore </p> </entry>

   131 </row>

   132 <row>

   133 <entry><p> <codeph> SIGSTOP</codeph>  </p> </entry>

   134 <entry><p>Ignore </p> </entry>

   135 </row>

   136 <row>

   137 <entry><p> <codeph> SIGTSTP</codeph>  </p> </entry>

   138 <entry><p>Ignore </p> </entry>

   139 </row>

   140 <row>

   141 <entry><p> <codeph> SIGCONT</codeph>  </p> </entry>

   142 <entry><p>Ignore </p> </entry>

   143 </row>

   144 <row>

   145 <entry><p> <codeph> SIGCHLD</codeph>  </p> </entry>

   146 <entry><p>Ignore </p> </entry>

   147 </row>

   148 <row>

   149 <entry><p> <codeph> SIGTTIN</codeph>  </p> </entry>

   150 <entry><p>Ignore </p> </entry>

   151 </row>

   152 <row>

   153 <entry><p> <codeph> SIGTTOU </codeph>  </p> </entry>

   154 <entry><p>Ignore </p> </entry>

   155 </row>

   156 <row>

   157 <entry><p> <codeph>SIGIO</codeph>  </p> </entry>

   158 <entry><p>Ignore </p> </entry>

   159 </row>

   160 <row>

   161 <entry><p> <codeph> SIGXCPU</codeph>  </p> </entry>

   162 <entry><p>Ignore </p> </entry>

   163 </row>

   164 <row>

   165 <entry><p> <codeph> SIGXFSZ</codeph>  </p> </entry>

   166 <entry><p>Ignore </p> </entry>

   167 </row>

   168 <row>

   169 <entry><p> <codeph> SIGVTALRM</codeph>  </p> </entry>

   170 <entry><p>Ignore </p> </entry>

   171 </row>

   172 <row>

   173 <entry><p> <codeph> SIGPROF</codeph>  </p> </entry>

   174 <entry><p>Ignore </p> </entry>

   175 </row>

   176 <row>

   177 <entry><p> <codeph> SIGWINCH</codeph>  </p> </entry>

   178 <entry><p>Ignore </p> </entry>

   179 </row>

   180 <row>

   181 <entry><p> <codeph> SIGINFO</codeph>  </p> </entry>

   182 <entry><p>Ignore </p> </entry>

   183 </row>

   184 <row>

   185 <entry><p> <codeph> SIGUSR1</codeph>  </p> </entry>

   186 <entry><p>Ignore </p> </entry>

   187 </row>

   188 <row>

   189 <entry><p> <codeph> SIGUSR2</codeph>  </p> </entry>

   190 <entry><p>Ignore </p> </entry>

   191 </row>

   192 <row>

   193 <entry><p> <codeph> SIGTHR</codeph>  </p> </entry>

   194 <entry><p>Ignore </p> </entry>

   195 </row>

   196 <row>

   197 <entry><p> <codeph> SIGRTMIN</codeph>  </p> </entry>

   198 <entry><p>Ignore </p> </entry>

   199 </row>

   200 <row>

   201 <entry><p> <codeph> SIGRTMAX</codeph>  </p> </entry>

   202 <entry><p>Ignore </p> </entry>

   203 </row>

   204 </tbody>

   205 </tgroup>

   206 </table> </li>

   207 <li id="GUID-5FEF9FD7-22C1-5722-AB35-56C6EC27713D"><p> <b> Ignore the signal:</b> You

   208 can choose to ignore a signal when it is delivered. </p> </li>

   209 <li id="GUID-83529703-4593-51B6-ACFD-78AF3634B3E5"><p> <b> Use a custom signal

   210 handler function:</b> You can set a custom signal handler function to be invoked

   211 when the signal arrives. </p> <p>The following example code demonstrates how

   212 you can handle a <codeph>SIGCHLD</codeph> signal by setting a custom signal

   213 handler function: </p> <codeblock id="GUID-4C7E5A1C-A0D6-5F7D-B444-8465B48122D4" xml:space="preserve">#include &lt;signal.h&gt;

   214 #include <stdio.h>

   215 #include <stdlib.h>

   216 void sighandler(int signum)

   217     {

   218     if(signum == SIGCHLD)

   219         {

   220         // Program logic for custom signal handling

   221         }

   222     else

   223         printf(“Error: Unknown signal”);

   224     }

   225 int main()

   226     {

   227     // When SIGCHLD arrives, invoke sighandler()

   228     signal(SIGCHLD,sighandler);

   229     // program logic

   230     return 0;

   231     }</codeblock> </li>

   232 </ol> </section>

   233 <section><title>Blocking signals</title> <p>A P.I.P.S. process can choose

   234 to block (and subsequently unblock) signals to itself using <xref href="GUID-02901E24-3615-3018-AF20-F5D5D63FD708.dita"><apiname>sighold()</apiname></xref>, <xref href="GUID-AE4CC3C8-C6D4-3F5C-A28F-C4AAB63E8992.dita"><apiname>sigset()</apiname></xref>, <xref href="GUID-68BD2914-FB73-3D91-9D81-425BF2436473.dita"><apiname>sigrelse()</apiname></xref> and <xref href="GUID-C7279C75-CB98-3F24-ABAA-76CF0009A8ED.dita"><apiname>sigprocmask()</apiname></xref>. Signals that are blocked on a P.I.P.S.

   235 process are not be delivered for handling. Instead, they are queued to be

   236 handled when they are unblocked. </p> <p>Non-realtime signals are queued only

   237 once, even when they are delivered multiple times. However, real-time signals

   238 are queued every time they are delivered. </p> <p> <b> Note:</b> You can force

   239 non-realtime signals to be queued multiple times by sending the signal using <xref href="GUID-3C70BF0B-CD6E-3A30-A9E6-4CCF11D47EEC.dita"><apiname>sigqueue()</apiname></xref>. </p> <p><b>Examples</b> </p> <p>The

   240 following example code demonstrates how real-time signals are queued when

   241 they are blocked: </p> <codeblock id="GUID-D3E99770-0E31-5B31-8AD4-DB5991AC4E03" xml:space="preserve">#include &lt;stdio.h&gt;

   242 #include <signal.h>

   243 void func(int sig)

   244     {

   245     printf("Signal was received");

   246     }

   247 int main(void)

   248     {

   249     signal(SIGRTMIN+3,func);

   250     sighold(SIGRTMIN+3);

   251     raise(SIGRTMIN+3);

   252     raise(SIGRTMIN+3);

   253     raise(SIGRTMIN+3);

   254     //This will cause func() to be called thrice

   255     sigrelse(SIGRTMIN+3);

   256     return 0;

   257     }</codeblock> <p>The output displayed is: </p> <codeblock id="GUID-BB3F1695-8BD4-5AAA-8CF4-BECA435327D4" xml:space="preserve">Signal was received

   258 Signal was received

   259 Signal was received</codeblock> <p>The following example code demonstrates

   260 how non-realtime signals are queued when they are blocked: </p> <codeblock id="GUID-0F984C01-54F9-50DB-8112-CF5F79E344D6" xml:space="preserve">#include &lt;stdio.h&gt;

   261 #include <signal.h>

   262 void func(int sig)

   263     {

   264     printf("Signal was received");

   265     }

   266 int main(void)

   267     {

   268     signal(SIGINT,func);

   269     sighold(SIGINT);

   270     raise(SIGINT);

   271     raise(SIGINT);

   272     raise(SIGINT);

   273     // This will cause func() to be called only ONCE, since SIGINT is a non-realtime signal.

   274     sigrelse(SIGINT);

   275     return 0;

   276     }</codeblock> <p>The output displayed is: </p> <codeblock id="GUID-3AAF3CF0-4B9D-5F75-9461-31A1EB628291" xml:space="preserve">Signal was received</codeblock> <p>The

   277 following example code demonstrates how you can force a non-realtime signal

   278 to be queued multiple times by sending the signal using <xref href="GUID-3C70BF0B-CD6E-3A30-A9E6-4CCF11D47EEC.dita"><apiname>sigqueue()</apiname></xref>: </p> <codeblock id="GUID-C3EFB6FC-3592-5F69-9AAE-F796EB483DEA" xml:space="preserve">#include &lt;stdio.h&gt;

   279 #include <signal.h>

   280 #include <unistd.h>

   281 void func(int sig)

   282     {

   283     printf("Signal was received");

   284     }

   285 int main(void)

   286     {

   287     union sigval val;

   288     val.sigval_int = 0;

   289     signal(SIGINT,func);

   290     sighold(SIGINT);

   291     sigqueue(getpid(), SIGINT,val);

   292     sigqueue(getpid(), SIGINT,val);

   293     sigqueue(getpid(), SIGINT,val);

   294     // This will cause func() to be called thrice

   295     sigrelse(SIGINT);

   296     return 0;

   297     }</codeblock> <p>The output displayed is: </p> <codeblock id="GUID-6F2BA135-2134-5176-9A80-80EB15286D7F" xml:space="preserve">Signal was received

   298 Signal was received

   299 Signal was received</codeblock> </section>

   300 </conbody><related-links>

   301 <link href="GUID-E65D91AE-482F-5592-B83C-0F29126C2EFA.dita"><linktext>Using Signals

   302 to Handle Exceptions</linktext></link>

   303 <link href="GUID-186B9876-2A08-5F23-BB49-49EC34C51507.dita"><linktext>Using Signals

   304 to Terminate Processes</linktext></link>

   305 <link href="GUID-6CF8A41B-C2DD-5D57-A71D-6405CE08A06B.dita"><linktext>Using Signals

   306 to Handle Asynchronous Events</linktext></link>

   307 </related-links></concept>