<?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>