--- a/Symbian3/SDK/Source/GUID-301037F1-1983-565A-88F9-633BBF0EBB91.dita Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-301037F1-1983-565A-88F9-633BBF0EBB91.dita Tue Jul 20 12:00:49 2010 +0100
@@ -1,213 +1,165 @@
-<?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>
+<?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\<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>
\ No newline at end of file