<?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> <p><xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use
bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How
to use abld</xref> describe how to use the SBSv1 build tools. </p> </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\<udeb or urel>\</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>