--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-301037F1-1983-565A-88F9-633BBF0EBB91.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,213 @@
+<?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>
\ No newline at end of file