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