<?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 reference
  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="GUID-301037F1-1983-565A-88F9-633BBF0EBB91" xml:lang="en"><title>posixsignals: POSIX Signal Example, Using P.I.P.S.</title><shortdesc>This example demonstrates various signal use cases as supported
in P.I.P.S. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>
<section id="GUID-CB373350-FF46-4535-BF8E-69F1CB3BA96E"><title>Purpose</title> <p>The example demonstrates the following use cases: </p> <ol>
<li id="GUID-2449E06E-4B58-567F-977E-B949483EB5C2"><p>Sending and
handling a signal using the default handler </p> </li>
<li id="GUID-7E468336-5849-5900-BE63-5AAE64061463"><p>Sending and
handling a signal using a customized signal handler </p> </li>
<li id="GUID-0BE58B0C-9D2A-5CAE-BF98-CF5169532B41"><p>Ignoring an
incoming signal </p> </li>
<li id="GUID-585B9B29-DFA4-5530-8E4F-F2DC865C9D2C"><p>Blocking and
releasing a signal </p> </li>
<li id="GUID-A486A7E3-31AB-5AAF-B24F-F908CE687121"><p>Waiting for
a signal </p> </li>
<li id="GUID-E4F52B24-EDA0-57A7-AA1C-7B93EF91F3C1"><p>Generating and
handling a <codeph>SIGPIPE</codeph> signal </p> </li>
<li id="GUID-3D92B198-4827-5817-B28C-C1AC0B28CD6F"><p>Using a signal
to gracefully terminate a process </p> </li>
<li id="GUID-D7F62326-7148-528E-9189-D9180123724E"><p>Using a signal
to handle an asynchronous event </p> </li>
</ol><p> </p><p>The example delivers 3 sub projects: </p> <ul>
<li id="GUID-F8B3EA5D-58D5-535D-BF5A-5E4639EE78FB"><p> <b>basicSignals:</b> This project demonstrates basic signal use cases. It shows the first
six use cases mentioned in the list above. The use cases are demonstrated
through <filepath>basicsignals.exe</filepath>. </p> </li>
<li id="GUID-145641DC-753A-53C4-8AFA-4F38D754A293"><p> <b>sigtermSignal:</b> This project demonstrates the graceful termination of a process
using the <codeph>SIGTERM</codeph> signal. The use case is demonstrated
through <filepath>sigtermsignal.exe</filepath> and <filepath>raisesignal.exe</filepath>. </p> </li>
<li id="GUID-899D801E-B669-560F-87AE-3C3AE095FB07"><p> <b>asyncSignal:</b> This project demonstrates asynchronous signal handling using the <codeph>SIGUSR1</codeph> signal and the <codeph>SIGUSR2</codeph> signal.
The use case is demonstrated using <filepath>sigusr1.exe</filepath> and <filepath>sigusr2.exe</filepath>. </p> </li>
</ul> </section>
<section id="GUID-703F9106-A12C-4F0B-872B-F4A06FCEC1FC"><title>Description</title> <p>The use cases demonstrated in this example are described below.</p><p>Note: For clarity in the documentation for this example, signal
names have been given in capitals whilst process names have been given
in lower case.</p><p><b>1. Sending and handling a signal using the
default handler </b> </p> <p>The default implementation of the signals
supported in P.I.P.S. will either terminate a process or ignore a
process. Signals are generated using the <codeph>Kill()</codeph> method
and they are handled as per the implementation in the default handler. </p> <p>To demonstrate this use case we use <codeph>SIGCHLD</codeph> and <codeph>SIGALRM</codeph> signals. <codeph>SIGCHLD</codeph> by default gets
ignored whenever it is raised, whereas <codeph>SIGALRM</codeph> causes
a process termination when raised. As a result the example terminates
whenever <codeph>SIGALRM</codeph> is raised, whereas an info message
is printed when <codeph>SIGCHLD</codeph> is raised. </p> <p><b>2.
Sending and handling a signal using a customized signal handler </b> </p> <p>To override the default implementation of a signal a customized
handler can be defined. This customized handler can be set either
by using <codeph>sigaction()</codeph> or <codeph>signal()</codeph>. The <codeph>sigaction()</codeph> method takes <codeph>struct sigaction</codeph> as one of its parameters (the <codeph>sa_handler</codeph> member
of this structure is filled with the custom handler). Now whenever
a signal is generated the custom handler is executed. </p> <p>For
the demonstration of this particular use case, <codeph>SIGCHLD</codeph> and <codeph>SIGALRM</codeph> signals are used. These signals are
assigned custom handler functions. The handlers for these signals
contains a simple user message. Thus, whenever the signals are raised,
the customized signal handlers get invoked instead of the default
handlers. </p> <p><b>3. Ignoring an incoming signal </b> </p> <p>A
signal can be ignored by setting <codeph>SIG_IGN</codeph> in the <codeph>sa_handler</codeph> member of <codeph>struct sigaction</codeph>.
The demonstration of this use case also uses <codeph>SIGCHLD</codeph> and <codeph>SIGALRM</codeph> signals, and as a result of setting <codeph>SIG_IGN</codeph> in <codeph>sa_handler</codeph> the signals are ignored
when raised. </p> <p><b>4. Blocking and releasing a signal </b> </p> <p>A signal can be blocked by first adding it to the blocking set
(a list of signals we want to block, when a signal is executing) by
using the <codeph>sigaddset()</codeph> method and then calling the<codeph> sigprocmask()</codeph> function. Once a signal is blocked it will
always be ignored upon generation. The <codeph>sigrelse()</codeph> method is used to unblock a signal. </p> <p>Demonstration of this
use case involves the <codeph>SIGUSR1</codeph> and <codeph>SIGUSR2</codeph> signals. Both <codeph>SIGUSR1 </codeph>and <codeph>SIGUSR2</codeph> are user-defined signals. We first block the <codeph>SIGUSR1</codeph> signal by adding it to the blocking set and making a call to the <codeph>sigprocmask()</codeph> function. Now whenever <codeph>SIGUSR1</codeph> is raised it will get ignored as it is blocked. <codeph>SIGUSR1</codeph> will keep waiting in the pending queue until it is released. The
release of <codeph>SIGUSR1</codeph> happens in the <codeph>SIGUSR2</codeph> signal handler. Once <codeph>SIGUSR1</codeph> is released, it is
removed from the pending queue and its handler function is called
to handle it. </p> <p><b>5. Waiting for a signal </b> </p> <p>Before
a process can wait on a particular signal, it has to add the signal
to the mask set (which is a list of signals we want to block) and
then call the <codeph>sigprocmask()</codeph> method. The process then
sets the timeout value using <codeph>struct timespec</codeph>. Once
this is done the process waits on a signal for a specified time period
using the<codeph>sigtimedwait()</codeph> method. If the signal is
not received within the specified time period, an error message is
generated. </p> <p>For the demonstration of this use case we are setting
a timeout of 5 seconds. The <codeph>SIGALRM</codeph> signal is raised
by a call to <codeph>alarm()</codeph> as and when the timer expires.
There are two instances in the example where <codeph>SIGALRM</codeph> signal is raised, one after a duration of 4 seconds and one after
6 seconds. When <codeph>SIGALRM</codeph> is raised after 4 seconds,
it is well within the timeout limit (of 5 seconds) and hence the signal
gets received but not handled. But when the alarm is raised after
6 seconds, timeout happens and an error is generated. Now as the <codeph>SIGALRM</codeph> signal was added to the mask set it never gets handled
even though it is received. To handle the signal we need to move it
from block state to unblock state, which we do using the <codeph>sigprocmask()</codeph> method. Once the signal gets unblocked its custom handler gets called. </p> <p><b>6. Generating and handling a <codeph>SIGPIPE</codeph> signal </b> </p> <p>The  <codeph>SIGPIPE</codeph> signal is generated when writing
to a broken pipe. To achieve this broken pipe condition the read end
of the pipe (obtained using the <codeph>pipe() </codeph> function
call) is closed and then write to the pipe is done. The associated
handler function is executed in response to the raised <codeph>SIGPIPE</codeph> signal . </p> <p><b>7. Using a signal to gracefully terminate a
process </b> </p> <p>Graceful termination of process can be achieved
by using the <codeph>SIGTERM </codeph>signal. In the handler function
of the signal all the opened file descriptors need to be closed before
exiting. </p> <p>This use case is demonstrated using the <filepath>sigtermSignal</filepath> project. The project consists of two processes:
the <filepath>sigtermsignal</filepath> process and the <filepath>raisesignal </filepath> process. </p> <ul>
<li id="GUID-A2CC3DF9-0334-5638-A5E7-7828F319F5D0"> <p>The <filepath>sigtermsignal</filepath> process first defines a custom handler for
the <codeph>SIGTERM</codeph> signal that carries out the closing of
all the open file descriptors when the signal is raised. This is done
in order to achieve the graceful termination of the process. The <filepath>sigtermsignal</filepath> process then opens a file and obtains names
from user to be written in to it. It then simultaneously spawns a <filepath>raisesignal</filepath> process and starts reading from the file.
When the <filepath>raisesignal</filepath> process sends a <codeph>SIGTERM</codeph> signal to the <filepath>sigtermsignal</filepath> process, the <filepath>sigtermsignal</filepath> process closes all
the open file descriptors and prepares to exit. </p> </li>
<li id="GUID-05715C75-A100-563B-82D5-CAA4EFD44634"> <p>The <filepath>raisesignal</filepath> process sends the <codeph>SIGTERM</codeph> signal to the <filepath>sigtermsignal</filepath> process. The custom
handler of the <codeph>SIGTERM</codeph> signal takes care of properly
closing all opened file descriptors and then terminating the process.
If the custom handler is not implemented, the default handler will
get called, which will result in process termination without closing
any opened file descriptors. </p> </li>
</ul> <p><b>8. Using a signal to handle an asynchronous event </b> </p> <p> <codeph>The SIGUSR1</codeph> and <codeph>SIGUSR2</codeph> signals are used to demonstrate the handling of an asynchronous
event. These signals are sent from one process to another. On reception
of these signals, respective custom handlers are called and any necessary
action is taken. The action taken is purely implementation dependent
. </p> <p>This use case demonstration is performed using the <filepath>asyncSignal</filepath> project. The project consists of two processes:
the <filepath>sigusr1</filepath> process and the <filepath>sigusr2</filepath> process, where the <filepath>sigusr1</filepath> process handles
the <codeph>SIGUSR1</codeph> signal and sends the <codeph>SIGUSR2</codeph> signal to the <filepath>sigusr2</filepath> process. Whereas the<filepath> sigusr2</filepath> process handles the <codeph>SIGUSR2</codeph> signal
and sends the <codeph>SIGUSR1</codeph> signal to the <filepath>sigusr1</filepath> process. </p> <ul>
<li id="GUID-57116DD9-EB8E-57F0-9FFD-AA54F984F698"><p>The <filepath>sigusr1 </filepath> process assigns a custom handler for the <codeph>SIGUSR1</codeph> signal. It then opens a file in read and write mode
and write some content into the open file. Once write operation is
done the <filepath>sigusr1</filepath> process spawns <filepath>sigusr2</filepath> process and waits for <codeph>SIGUSR1 </codeph> signal from <filepath>sigusr2</filepath> process. On receiving <codeph>SIGUSR1</codeph> signal <filepath>sigusr1 </filepath> process starts reading from
the file. Once reading from the file is done and its contents are
displayed on the console, <filepath>sigusr1</filepath> process sends <codeph>SIGUSR2</codeph> signal to <filepath>sigusr2</filepath> process.
It then closes all its open file descriptor and prepares to exit. </p> </li>
<li id="GUID-9F878182-23B1-570C-986C-3B4E7B26F444"> <p>The<filepath> sigusr2</filepath> process is spawned from <filepath>sigusr1</filepath> process and it assigns a custom handler for <codeph>SIGUSR2</codeph> signal. It sends <codeph>SIGUSR1</codeph> signal to <filepath>sigusr1</filepath> process in order to start file read and then waits for <codeph>SIGUSR2 </codeph> signal from <filepath>sigusr1</filepath> process. When <filepath>sigusr2</filepath> process receives <codeph>SIGUSR2</codeph> signal
it prepares to exit. </p> </li>
</ul> <p>Hence, the communication between the two processes happens
through the <codeph>SIGUSR1</codeph> and <codeph>SIGUSR2</codeph> signals
and asynchronous signal handling happens. </p> </section>
<section id="GUID-E1661179-0268-4E49-A574-C7CC41D7A56B"><title>Download</title> <p>Click on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-5a633d12-547a-4439-9eca-104a655109ab.zip" scope="external">BasicSignals.zip</xref></p><p>Click on the following
link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-54523fba-51b5-436a-9403-99874fdc94c7 .zip" scope="external">SigtermSignal.zip</xref></p><p>Click on the following
link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-7714a392-161f-4dc7-b8e6-311e42e1deb8 .zip" scope="external">AsyncSignal.zip</xref></p><p/><p>To view the BasicSignal
example source click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-5a633d12-547a-4439-9eca-104a655109ab.html" scope="peer">browseBasicSignals</xref></p><p>To view the SigtermSignal
example source click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-54523fba-51b5-436a-9403-99874fdc94c7.html" scope="peer">browseSigtermSignal</xref></p><p>To view the AsyncSignal
example source click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-7714a392-161f-4dc7-b8e6-311e42e1deb8.html" scope="peer">browseAsyncSignal</xref></p> </section>
<section id="GUID-38492A50-BF1B-4A33-8125-397D646ED8A7"><title>Building
and configuring</title> <p>You can build the example from your IDE
or the command line: </p> <ul>
<li id="GUID-0D86ECCB-1501-52D9-A52E-A016AB6710A2"><p> </p><p>If you
use an IDE, import the <filepath>bld.inf</filepath> file of the example
into your IDE, and use the build command of the IDE. </p></li>
<li> <p>If you use the command line, open a command prompt, and set
the current directory to the source code directory of the example.
You can then build the example with the SBSv1 build tools using the
following commands: </p><ul>
<li><p><cmdname>bldmake bldfiles</cmdname></p></li>
<li><p><cmdname>abld build</cmdname></p></li>
</ul> </li>
</ul> <p> </p><p>The example builds the following executables :<ul>
<li><p><filepath>basicsignals.exe</filepath> : for basic signal use
cases demonstration. </p></li>
<li><p><filepath>sigtermsignal.exe</filepath> : for demonstrating
graceful termination of process .</p></li>
<li><p><filepath>raisesignal.exe</filepath> : for sending <codeph>SIGTERM</codeph> signal.</p></li>
<li><p><filepath>sigusr1.exe</filepath> : for demonstrating asynchronous
event handling , sending <codeph>SIGUSR2</codeph> signal and receiving <codeph>SIGUSR1</codeph> signal. </p></li>
<li><p><filepath>sigusr2.exe</filepath> : for sending <codeph><codeph>SIGUSR1</codeph></codeph> signal and receiving <codeph>SIGUSR2</codeph> signal.</p></li>
</ul></p><p> in the <filepath>epoc32\release\winscw\&lt;udeb or urel&gt;\</filepath> folder. </p><p> </p></section>
<section id="GUID-1CB8164D-030D-41CD-B146-3E4D14CB1A9B"><title>Running
the example</title> <p><b>NOTE : </b> </p> <p> <filepath>basicsignals.exe</filepath> should be executed first for running the first six uses cases mentioned
above. </p> <p> <filepath>sigtermsignal.exe</filepath> should be executed
for running the seventh use case. </p> <p> <filepath>sigusr1.exe</filepath> should be executed for running the last use case. </p> <p>The <filepath>sigtermsignal</filepath> process internally spawns the<filepath> raisesignal</filepath> process for taking an input from the user and sending the <codeph>SIGTERM</codeph> signal. You should not run the <filepath>raisesignal</filepath> process explicitly. You should only run <filepath>sigtermsignal.exe</filepath> as the <filepath>sigtermsignal</filepath> process takes proper care
of launching the <filepath>raisesignal</filepath> process. </p> <p>The <filepath>sigusr1</filepath> process also internally spawns the <filepath>sigusr2</filepath> process. </p> <p>The <filepath>sigusr1</filepath> process sends the <codeph>SIGUSR2</codeph> signal to the <filepath>sigusr2</filepath> process and receives the <codeph>SIGUSR1</codeph> signal from it. </p> <p>The <filepath>sigusr2</filepath> process
sends the <codeph>SIGUSR1</codeph> signal to the <filepath>sigusr1</filepath> process and receives the <codeph>SIGUSR2</codeph> signal from it. </p> <p>As the <filepath>sigusr1 </filepath>process spawns the <filepath>sigusr2</filepath> process, hence you should run <filepath>sigusr1.exe</filepath> only. </p> <p>In order to toggle between the processes use <cmdname>Alt+ctrl+shift+T</cmdname> and observe the behavior. </p> </section>
</refbody></reference>