412 lines
19 KiB
HTML
412 lines
19 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Using Signal APIs</title>
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
||
|
|
<!--File Edited December 2001 -->
|
||
|
|
<!--End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Using Signal APIs</h2>
|
||
|
|
|
||
|
|
<h3><a name="sigconcepts">Signal Concepts</a></h3>
|
||
|
|
|
||
|
|
<p>An X/Open specification defines a "signal" as a mechanism by which a process
|
||
|
|
may be notified of, or affected by, an event occurring in the system. The term
|
||
|
|
signal is also used to refer to the event itself.</p>
|
||
|
|
|
||
|
|
<p>A signal is said to be <strong>generated</strong> when the event that causes
|
||
|
|
the signal first occurs. Examples of such events include the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>System-detected errors<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Timer expiration<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Terminal (work station) activity<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Calling an API such as the X/Open <strong>kill()</strong> function, the
|
||
|
|
American National Standard C <strong>raise()</strong> function, or the ILE
|
||
|
|
<strong>CEESGL</strong> (signal a condition) function.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>A <strong>synchronous signal</strong> is a signal that is generated by some
|
||
|
|
action attributable to a program running within the thread, such as a
|
||
|
|
system-detected error, <strong>raise()</strong>, or <strong>CEESGL</strong>. An
|
||
|
|
<strong>asynchronous signal</strong> is a signal that is generated for the
|
||
|
|
process by using the <strong>kill()</strong> function or by an asynchronous
|
||
|
|
event such as terminal activity or an expired timer.</p>
|
||
|
|
|
||
|
|
<p>The <strong>signal action vector</strong> is a list of signal-handling
|
||
|
|
actions for each defined signal. The signal action vector is maintained
|
||
|
|
separately for each process and is inherited from the parent process. The
|
||
|
|
signal action vector specifies the signal-handling actions for both
|
||
|
|
synchronously and asynchronously generated signals.</p>
|
||
|
|
|
||
|
|
<p>A signal is said to be <strong>delivered</strong> to a process when the
|
||
|
|
specified signal-handling action for the signal is taken. A signal is said to
|
||
|
|
be <strong>accepted</strong> by a process when a signal is selected and
|
||
|
|
returned by one of the <em>sigwait</em> functions.</p>
|
||
|
|
|
||
|
|
<p>Signals generated for a process are delivered to or accepted by one thread
|
||
|
|
in the process.</p>
|
||
|
|
|
||
|
|
<p>A signal is said to be <strong>pending</strong> during the interval between
|
||
|
|
the time the signal is generated and the time it is delivered or accepted.
|
||
|
|
Ordinarily, this interval cannot be detected by an application. However, a
|
||
|
|
signal can be <strong>blocked</strong> from being delivered to a thread. When a
|
||
|
|
signal is blocked, the signal-handling action associated with the signal is not
|
||
|
|
taken. If there are no threads in a call to a <em>sigwait</em> function
|
||
|
|
selecting the signal and if all threads block delivery of the signal, the
|
||
|
|
signal remains pending on the process. The signal remains pending until either
|
||
|
|
a thread calls a <em>sigwait</em> function selecting the signal, a thread
|
||
|
|
unblocks delivery of the signal, or the signal action associated with the
|
||
|
|
signal is set to ignore the signal. The <strong>signal blocking mask</strong>
|
||
|
|
defines the set of signals that are blocked from delivery to the thread. The
|
||
|
|
signal blocking mask is maintained separately for each thread in the process
|
||
|
|
and is inherited from the thread that created it.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="sigmanagement">i5/OS Signal Management</a></h3>
|
||
|
|
|
||
|
|
<p>The set of defined signals is determined by the system. The system specifies
|
||
|
|
the attributes for each defined signal. These attributes consist of a signal
|
||
|
|
number, the initial signal action, and the signal default action. The system
|
||
|
|
also specifies an initial signal blocking mask. The set of defined signals, the
|
||
|
|
signal attributes, and signal blocking mask are referred to as <strong>signal
|
||
|
|
controls</strong>.</p>
|
||
|
|
|
||
|
|
<p>A signal can be generated or delivered only to a process that has expressed
|
||
|
|
an interest in signals. An error condition results under the following
|
||
|
|
conditions:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>An attempt is made to generate a signal when the system signal controls
|
||
|
|
have not been initialized.</li>
|
||
|
|
|
||
|
|
<li>An attempt is made to generate a signal for a process that has not been
|
||
|
|
enabled for signals.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>A process can express an interest in signals by calling the <strong>
|
||
|
|
Qp0sEnableSignals()</strong> API. In addition, calling particular signal APIs
|
||
|
|
implicitly enables the process for signals.</p>
|
||
|
|
|
||
|
|
<p>If the process has not been enabled for signals, the process signal controls
|
||
|
|
are set from signal controls established by the system during IPL (the system
|
||
|
|
signal controls). An error condition results if an attempt is made to enable
|
||
|
|
signals for the process before the system signal controls have been
|
||
|
|
initialized.</p>
|
||
|
|
|
||
|
|
<p>Once the process signal controls have been initialized, the user is
|
||
|
|
permitted to change the signal controls for the process. For example, the
|
||
|
|
signal blocking mask and the signal action for a signal are commonly changed.
|
||
|
|
Some signal controls, such as the number of defined signals and the signal
|
||
|
|
default action for a signal, cannot be changed at the process level.</p>
|
||
|
|
|
||
|
|
<p>The attributes for each defined signal are stored in an object called a
|
||
|
|
<strong>signal monitor</strong>. The system supports a maximum of 63 signal
|
||
|
|
monitors for each process. The process signal action vector is a list of signal
|
||
|
|
monitors, one for each defined signal. The signal monitor contains, but is not
|
||
|
|
limited to, the following information:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Signal action</li>
|
||
|
|
|
||
|
|
<li>Signal default action</li>
|
||
|
|
|
||
|
|
<li>Signal options</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The <strong>signal action</strong> defines the action to be taken by the
|
||
|
|
system when a process receives an unblocked signal. The user can change the
|
||
|
|
signal action for a process signal monitor. The possible signal actions
|
||
|
|
are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Handle using signal default action (SIG_DFL)
|
||
|
|
|
||
|
|
<p>The <em>handle using signal default action</em> signal action indicates that
|
||
|
|
the system is to take the action specified by the signal default action field
|
||
|
|
when the signal is eligible to be delivered.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Ignore the signal (SIG_IGN)
|
||
|
|
|
||
|
|
<p>The <em>ignore the signal</em> signal action indicates that the user is not
|
||
|
|
interested in handling the signal. When an ignored signal is generated for the
|
||
|
|
process, the system automatically discards the signal, regardless of the
|
||
|
|
blocked or unblocked state of the signal monitor.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Handle the signal by running signal-catching function
|
||
|
|
|
||
|
|
<p>The <em>handle the signal by running signal-catching function</em> signal
|
||
|
|
action causes the system to call the signal-catching function when a signal is
|
||
|
|
received for the signal monitor. The signal-catching function is set to point
|
||
|
|
to a procedure within an active activation group.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The signal default action field defines the action to be taken by the system
|
||
|
|
when the signal action is set to <em>handle using signal default action</em>.
|
||
|
|
The signal default action for a signal monitor is set in the system signal
|
||
|
|
controls and cannot be changed for a process signal monitor. The possible
|
||
|
|
signal default actions are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Terminate the process
|
||
|
|
|
||
|
|
<p>The <em>terminate the process</em> action puts the process in a phase that
|
||
|
|
ends the process, allowing cancel handlers to be called. If the process is
|
||
|
|
already in the end phase, the <em>terminate the process</em> action is
|
||
|
|
ignored.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>End the request
|
||
|
|
|
||
|
|
<p>The <em>end the request</em> action results in the cancelation of all calls
|
||
|
|
up to the nearest call that has a call status of request processor. If a call
|
||
|
|
with a status of request processor is not present or the job is capable of
|
||
|
|
having multiple threads, the <em>terminate the process</em> action is
|
||
|
|
taken.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Ignore the signal
|
||
|
|
|
||
|
|
<p>The <em>ignore the signal</em> action causes the system to discard the
|
||
|
|
signal. A signal is discarded for a signal monitor in the blocked state when
|
||
|
|
the signal action is <em>handle using signal default action</em> and the
|
||
|
|
default signal action is <em>ignore the signal</em>.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Stop the process
|
||
|
|
|
||
|
|
<p>The <em>stop the process</em> action causes the system to place the process
|
||
|
|
in the stopped state. When a process is in the <strong>stopped</strong> state,
|
||
|
|
it is temporarily suspended until a signal is generated for the process that
|
||
|
|
has <em>continue the process if stopped</em> as its signal default action. When
|
||
|
|
a process is in the stopped state, the normal process control functions remain
|
||
|
|
in effect (the process can be suspended, resumed, or ended). When a signal is
|
||
|
|
generated for a signal monitor that has <em>stop the process</em> as its signal
|
||
|
|
default action, the system removes any pending signals for signal monitors that
|
||
|
|
have <em>continue the process if stopped</em> as their default action.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Continue the process if stopped
|
||
|
|
|
||
|
|
<p>The <em>continue the process if stopped</em> action causes the system to
|
||
|
|
resume running the process that is in the stopped state, even if the signal
|
||
|
|
monitor with the signal default action of <em>continue the process if
|
||
|
|
stopped</em> is in the blocked state or has a signal action of <em>ignore the
|
||
|
|
signal</em>. When a signal is generated for a signal monitor that has <em>
|
||
|
|
continue the process if stopped</em> as its signal default action, the system
|
||
|
|
removes any pending signals for signal monitors that have <em>stop the
|
||
|
|
process</em> as their signal default action.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Signal exception
|
||
|
|
|
||
|
|
<p>The <em>signal exception</em> action causes the system to send the MCH7603
|
||
|
|
escape message to the process.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The <strong>signal options</strong> specify an additional set of attributes
|
||
|
|
for the signal monitor. The primary use of these options is to specify an
|
||
|
|
additional set of actions to be taken by the system when a signal-catching
|
||
|
|
function is called.</p>
|
||
|
|
|
||
|
|
<p>A signal is generated by sending a request to a signal monitor. Scheduling
|
||
|
|
of the signal-handling action is controlled separately for each signal monitor
|
||
|
|
through the <strong>signal blocking mask</strong>. The signal blocking mask is
|
||
|
|
a bit mask that defines the set of signals to be blocked from delivery to the
|
||
|
|
thread. The blocked or unblocked option specified for the <em>nth</em> bit
|
||
|
|
position in the signal blocking mask is applied to the <em>nth</em> signal
|
||
|
|
monitor defined for the process. When <samp>signal is unblocked</samp> is
|
||
|
|
specified, the signal-handling action is eligible to be scheduled. When <samp>
|
||
|
|
signal is blocked</samp> is specified, the signal-handling action is blocked
|
||
|
|
from delivery.</p>
|
||
|
|
|
||
|
|
<p>The process to receive the signal is identified by a <strong>process
|
||
|
|
ID</strong>. The process ID is used to indicate whether the signal should be
|
||
|
|
sent to an individual process or to a group of processes (known as a process
|
||
|
|
group). The process ID is a 4-byte binary number that is used to locate an
|
||
|
|
entry in the system-managed process table. A process table entry contains the
|
||
|
|
following information relating to the process:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Parent process ID</li>
|
||
|
|
|
||
|
|
<li>Process group ID</li>
|
||
|
|
|
||
|
|
<li>Status information</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The <strong>parent process</strong> is the logical creator of the process. A
|
||
|
|
<strong>process group</strong> represents a collection of processes that are
|
||
|
|
bound together for some common purpose. An error condition results if the
|
||
|
|
process ID specified when a signal is sent does not represent a valid process
|
||
|
|
or process group.</p>
|
||
|
|
|
||
|
|
<p>The process sending a signal must have the appropriate authority to the
|
||
|
|
receiving process. The parent process is allowed to send a signal to a child
|
||
|
|
process (the parent process ID of the receiving process is equal to the process
|
||
|
|
ID of the process sending the signal). A child process is allowed to send a
|
||
|
|
signal to its parent process (the process ID of the receiving process is equal
|
||
|
|
to the parent process ID of the process sending the signal). A process can send
|
||
|
|
a signal to another process if the sending process has *JOBCTL authority
|
||
|
|
defined for the current process user profile or in an adopted user profile.
|
||
|
|
Otherwise, the real or effective user ID of the sending process must match the
|
||
|
|
real or effective user ID of the receiving process. An error condition results
|
||
|
|
if the process does not have authority to send the signal to a receiving
|
||
|
|
process.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="sigdifferences">Differences from Signals on UNIX Systems</a></h3>
|
||
|
|
|
||
|
|
<p>The i5/OS<SUP>(TM)</SUP> support for signals does differ from the usual behavior of
|
||
|
|
signals on UNIX<SUP>(R)</SUP> systems:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Integration of American National Standard C signal model and X/Open signal
|
||
|
|
model
|
||
|
|
|
||
|
|
<p>On UNIX systems, the standard C signal functions (as defined by American
|
||
|
|
National Standards Institute (ANSI)) and the UNIX signal functions interact.
|
||
|
|
That is, the standard C <strong>signal()</strong> function operates on the
|
||
|
|
process signal action vector. Likewise, when a signal is generated for a
|
||
|
|
process using the standard C <strong>raise()</strong> function, the process
|
||
|
|
signal blocking mask and the signal action vector are used to determine the
|
||
|
|
action to be taken.</p>
|
||
|
|
|
||
|
|
<p>On i5/OS, the behavior of the standard C signal functions depends on a
|
||
|
|
compiler option. When the compiler option <strong>
|
||
|
|
SYSIFCOPT(*ASYNCSIGNAL)</strong> is specified, the standard C <strong>
|
||
|
|
signal()</strong> and <strong>raise()</strong> functions operate like the UNIX
|
||
|
|
signal functions by operating on the process signal action vector and the
|
||
|
|
process signal blocking mask. However, if the <strong>
|
||
|
|
SYSIFCOPT(*ASYNCSIGNAL)</strong> is not specified the standard C signal
|
||
|
|
functions do not operate like the UNIX signal functions. Although the default C
|
||
|
|
signal model does not interact with the UNIX signal functions, the UNIX signal
|
||
|
|
functions <strong>sigaction()</strong> and <strong>kill()</strong> provide the
|
||
|
|
same type of capability as the standard C <strong>signal()</strong> and
|
||
|
|
<strong>raise()</strong> functions. For more information, see <a href=
|
||
|
|
"sigactn.htm">sigaction()--Examine and Change Signal Action</a> and <a href=
|
||
|
|
"sigkill.htm">kill()--Send Signal to Process or Group of Processes</a>.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Scope of signal action vector, signal-blocking mask, and pending signals
|
||
|
|
|
||
|
|
<p>On most UNIX systems, a process consists of a single thread of control. When
|
||
|
|
the program in control needs to perform a task that is contained in another
|
||
|
|
program, the program uses the <strong>fork()</strong> and <strong>
|
||
|
|
exec()</strong> functions to start a child process that runs the other program.
|
||
|
|
The signal controls for the child process are inherited from the parent
|
||
|
|
process. Changes to the signal controls in either the parent or the child
|
||
|
|
process are isolated to the process in which the change is made.</p>
|
||
|
|
|
||
|
|
<p>On i5/OS, when a program needs to perform a task that is contained in
|
||
|
|
another program, the program calls that program directly. The target program is
|
||
|
|
run using the same process structure. As a result of this call and return
|
||
|
|
mechanism, if a called program changes the process signal controls and does not
|
||
|
|
restore the original signal controls when returning to its caller, the changed
|
||
|
|
process signal controls remain in effect. The called program inherits the
|
||
|
|
signal controls of its caller. However, there are some differences from what
|
||
|
|
would be expected if <strong>fork()</strong> and <strong>exec()</strong> were
|
||
|
|
used in a UNIX process:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The set of pending signals is not cleared.</li>
|
||
|
|
|
||
|
|
<li>Alarms are not reset.</li>
|
||
|
|
|
||
|
|
<li>Signals set to be caught are not reset to the default action.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Programs that use signals and change the signal controls of the process
|
||
|
|
should restore the old actions or signal blocking mask (or both) when they
|
||
|
|
return to their callers. Programs using signals should explicitly enable the
|
||
|
|
process for signals when the program begins. If the process was not enabled for
|
||
|
|
signals when the program was called, the program should also disable signals
|
||
|
|
when it returns to the process. For more information, see <a href=
|
||
|
|
"sigesig.htm">Qp0sEnableSignals()--Enable Process for Signals</a> and <a href=
|
||
|
|
"sigdsig.htm">Qp0sDisableSignals()--Disable Process for Signals</a>.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Mapping system-detected errors to signals
|
||
|
|
|
||
|
|
<p>On UNIX systems, system-detected errors are mapped to signal numbers. For
|
||
|
|
example, a floating point error results in the SIGFPE signal being generated
|
||
|
|
for the process. On i5/OS, the default C signal model presents system-detected
|
||
|
|
errors to the user as escape messages which can be handled with C signal
|
||
|
|
handlers established with the C <strong>signal()</strong> function or with ILE
|
||
|
|
C exception-handling functions, but not with signal handlers established with
|
||
|
|
the UNIX <strong>sigaction()</strong> function. When the compiler option
|
||
|
|
<strong>SYSIFCOPT(*ASYNCSIGNAL)</strong> is specified, system-detected errors
|
||
|
|
are mapped to signal numbers and can be handled with signal handlers
|
||
|
|
established either with the C <strong>signal()</strong> function or the UNIX
|
||
|
|
<strong>sigaction()</strong> function, but not with ILE C exception-handling
|
||
|
|
functions.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Unexpected error handling in the signal-catching function
|
||
|
|
|
||
|
|
<p>On UNIX systems, an unhandled error condition in a signal-catching function
|
||
|
|
results in ending the process. On i5/OS, unhandled error conditions in the
|
||
|
|
signal-catching function are implicitly handled. The signal-catching function
|
||
|
|
is ended and the receiving program resumes running at the point at which it was
|
||
|
|
interrupted. The error condition may be logged in the job log. Aside from the
|
||
|
|
job log entry for the error, no further error notification takes place.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Termination action
|
||
|
|
|
||
|
|
<p>i5/OS offers two types of termination actions. The termination action
|
||
|
|
applied to most signals is to end the most recent request. This usually results
|
||
|
|
in ending the current program, which is the expectation of most UNIX
|
||
|
|
programmers. The second termination action is to end the process, which is more
|
||
|
|
severe. The only signal with this action is SIGKILL.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Default actions
|
||
|
|
|
||
|
|
<p>On i5/OS, some default actions for signals are different than on typical
|
||
|
|
UNIX systems. For example, the i5/OS default action for the SIGPIPE signal is
|
||
|
|
to ignore the signal.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|