<!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>kill()--Send Signal to Process or Group of Processes</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 ========================================== -->
<!-- UNIX5 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Edited by Kersten Feb 02 -->
<!-- This file has undergone error condition cleanup on 04/30/02 by JET -->
<!--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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>kill()--Send Signal to Process or Group of Processes</h2>
<div class="box" style="width: 60%;">
<br>
Syntax<br>
<pre>
#include <sys/types.h>
#include <signal.h>
int kill( pid_t <em>pid</em>, int <em>sig</em> );
</pre>
<br>
Service Program Name: QPOSSRV1<br>
<!-- iddvc RMBR -->
<br>
Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>kill()</strong> function sends a signal to a process or process
group specified by <em>pid</em>. The signal to be sent is specified by <em>
sig</em> and is either 0 or one of the signals from the list in the
<<strong>sys/signal.h</strong>> header file.</p>
<p>The process sending the signal must have appropriate authority to the
receiving process or processes. The <strong>kill()</strong> function is
successful if the process has permission to send the signal <em>sig</em> to any
of the processes specified by <em>pid</em>. If <strong>kill()</strong> is not
successful, no signal is sent.</p>
<p>A process can use <strong>kill()</strong> to send a signal to itself. If the
signal is not blocked in the sending thread, and if no other thread has the
<em>sig</em> unblocked or is waiting in a <em>sigwait</em> function for <em>
sig</em>, either <em>sig</em> or at least one pending unblocked signal is
delivered to the sender before <strong>kill()</strong> returns.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong><em>pid</em></strong></dt>
<dd>(Input) The process ID or process group ID to receive the signal.<br>
<br>
</dd>
<dt><strong><em>sig</em></strong></dt>
<dd>(Input) The signal to be sent.</dd>
</dl>
<p><em>pid</em> and <em>sig</em> can be used as follows:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top" nowrap><em><samp>pid_t</samp></em> pid;</td>
<td align="left" valign="top">Specifies the processes that the caller wants to
send the signal to:
<ul>
<li>If <em>pid</em> is greater than zero, <strong>kill()</strong> sends the
signal <em>sig</em> to the process whose ID is equal to <em>pid</em>.<br>
<br>
</li>
<li>If <em>pid</em> is equal to zero, <strong>kill()</strong> sends the signal
<em>sig</em> to all processes whose process group ID is equal to that of the
sender, except for those to which the sender does not have the appropriate
authority to send a signal.<br>
<br>
</li>
<li>If <em>pid</em> is equal to -<samp>1</samp>, <strong>kill()</strong>
returns -<samp>1</samp> and <em>errno</em> is set to [ESRCH].<br>
<br>
</li>
<li>If <em>pid</em> is less than -<samp>1</samp>, <strong>kill()</strong> sends
the signal <em>sig</em> to all processes whose process group ID is equal to the
absolute value of <em>pid</em>, except for those to which the sender does not
have appropriate authority to send a signal.</li>
</ul>
</td>
</tr>
<tr>
<td align="left" valign="top"><em><samp>int</samp></em> sig;</td>
<td align="left" valign="top">The signal that should be sent to the processes
specified by <em>pid</em>. This must be zero, or one of the signals defined in
the <<strong>sys/signal.h</strong>> header file. If <em>sig</em> is zero,
<strong>kill()</strong> performs error checking, but does not send a signal.
You can use a <em>sig</em> value of zero to check whether the <em>pid</em>
argument is valid.</td>
</tr>
</table>
<br>
<br>
<h3>Authorities</h3>
<p>The thread sending the signal must have the appropriate authority to the
receiving process. A thread is allowed to send a signal to a process if at
least one of the following conditions is true:</p>
<ul>
<li>The thread is sending a signal to its own process.<br>
<br>
</li>
<li>The thread has *JOBCTL special authority defined in the currently running
user profile or in a current adopted user profile.<br>
<br>
</li>
<li>The thread belongs to a process that is the parent of the receiving
process. (The process being signaled has a <em>parent process ID</em> equal to
the <em>process ID</em> of the thread sending the signal.)<br>
<br>
</li>
<li>If the receiving process is multi-threaded,<br>
<br>
<ul>
<li>The real or effective user ID of the thread matches the <em>job user
identity</em> of the process receiving process (the process being
signaled).</li>
</ul>
<br>
</li>
<li>Otherwise,<br>
<br>
<ul>
<li>The real or effective user ID of the thread matches the real or effective
user ID of the process being signaled. If _POSIX_SAVED_IDS is defined in the
<<strong>unistd.h</strong>> include file, the saved set user ID of the
intended recipient is checked instead of its effective user ID.</li>
</ul>
</li>
</ul>
<p>The <em>job user identity</em> is the name of the user profile by which a
job is known to other jobs. It is described in more detail in the <a href=
"../rzaks/rzaks1.htm">Work Management</a> topic.</p>
<p>When sending a signal affects entries for multiple processes, the signal is
generated for each process to which the process sending the signal is
authorized. If the process does not have permission to send the signal to any
receiving process, the [EPERM] error is returned.</p>
<p>Regardless of user ID, a process can always send a SIGCONT signal to a
process that is a member of the same process group (same <em>process group
ID</em>) as the sender.</p>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top"><strong>kill()</strong> was successful. It had
permission to send <em>sig</em> to one or more of the processes specified by
<em>pid</em>.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top"><strong>kill()</strong> was not successful. It
failed to send a signal. The <em>errno</em> variable is set to indicate the
error.</td>
</tr>
</table>
<br>
<br>
<h3>Error Conditions</h3>
<p>If <strong>kill()</strong> is not successful, <em>errno</em> usually
indicates one of the following errors. Under some conditions, <em>errno</em>
could indicate an error other than those listed here.</p>
<dl>
<dt><em>[EINVAL]</em></dt>
<dd>
<p>The value specified for the argument is not correct.</p>
<p>A function was passed incorrect argument values, or an operation was
attempted on an object and the operation specified is not supported for that
type of object.</p>
<p>An argument value is not valid, out of range, or NULL.</p>
<p>The value of <em>sig</em> is not within the range of signal numbers or is a
signal that is not supported.</p>
</dd>
<dt><em>[ENOTSIGINIT]</em></dt>
<dd>
<p>Process not enabled for signals.</p>
<p>An attempt was made to call a signal function under one of the following
conditions:</p>
<ul>
<li>The signal function is being called for a process that is not enabled for
asynchronous signals.<br>
<br>
</li>
<li>The signal function is being called when the system signal controls have
not been initialized.</li>
</ul>
<br>
</dd>
<dt><em>[ENOSYSRSC]</em></dt>
<dd>
<p>System resources not available to complete request.</p>
</dd>
<dt><em>[EPERM]</em></dt>
<dd>Operation not permitted.
<p>You must have appropriate privileges or be the owner of the object or other
resource to do the requested operation.</p>
</dd>
<dt><em>[ESRCH]</em></dt>
<dd>No item could be found that matches the specified value.
<p>The process or process group specified in <em>pid</em> cannot be found.</p>
</dd>
</dl>
<br>
<h3>Usage Notes</h3>
<ol>
<li>If the value of <em>pid</em> is 0 (so that <strong>kill()</strong> is used
to send a signal to all processes whose process group ID is equal to that of
the sender), <strong>kill()</strong> enables the process for signals if the
process is not already enabled for signals. For details, see <a href=
"sigesig.htm">Qp0sEnableSignals()--Enable Process for Signals</a>.<br>
<br>
</li>
<li>A process can use <strong>kill()</strong> to simulate the American National
Standard C <strong>raise()</strong> function by using the following:
<pre>
sigset_t sigmask;
/*
* Allow all signals to be delivered by unblocking all signals
*/
sigemtyset( &sigmask );
sigprocmask( SIG_SETMASK, &sigmask, NULL );
...
kill( getpid(), SIGUSR1 );
</pre>
<p>The example above ensures that no signals are blocked from delivery. When
the <strong>kill()</strong> function is called, the behavior is the same as
calling the <strong>raise()</strong> function.</p>
</li>
</ol>
<br>
<h3>Related Information</h3>
<ul>
<li>The <<strong>signal.h</strong>> file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
<br>
</li>
<li>The <<strong>sys/types.h</strong>> file (see <a href="unix13.htm">
Header Files for UNIX-Type Functions</a>)<br>
<br>
</li>
<li><a href="sigdsig.htm">Qp0sDisableSignals()</a>--Disable Process for
Signals<br>
<br>
</li>
<li><a href="sigesig.htm">Qp0sEnableSignals()</a>--Enable Process for
Signals<br>
<br>
</li>
<li><a href="sigactn.htm">sigaction()</a>--Examine and Change Signal Action<br>
<br>
</li>
<li><a href="sigtwait.htm">sigtimedwait()</a>--Synchronously Accept a Signal
for Interval of Time<br>
<br>
</li>
<li><a href="sigwait.htm">sigwait()</a>--Synchronously Accept a Signal<br>
<br>
</li>
<li><a href="sigwaiti.htm">sigwaitinfo()</a>--Synchronously Accept a Signal and
Signal Data</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<p>The following example uses the <strong>kill()</strong> function:</p>
<pre>
#include <signal.h>
#include <unistd.h>
#include <errno.h>
#include <stdio.h>
#include <time.h>
int sendsig( int );
volatile int sigcount=0;
void catcher( int sig ) {
sigcount++;
}
int main( int argc, char *argv[] ) {
struct sigaction sigact;
int result;
/* set up a signal catching function to handle the signals */
/* that will be sent from the sendsig() function */
sigemptyset( &sigact.sa_mask );
sigact.sa_flags = 0;
sigact.sa_handler = catcher;
sigaction( SIGUSR1, &sigact, NULL );
/* Call the sendsig() function that will call the kill() */
/* function for SIGUSR1 n times based on the input value */
result = sendsig( 21 );
printf( "Back in main\n" );
printf( "The kill() function was called %d times\n", result );
printf( "The signal catching function was called %d times\n", \
sigcount );
return( 0 );
}
int sendsig( int count ) {
int i;
int j=0;
for( i=0; i < count; i++ ) {
if( i == ((i/10)*10) ) {
j++;
kill( getpid(), SIGUSR1 );
}
}
return( j );
}
</pre>
<br>
<h3>Output:</h3>
<pre>
Back in main
The kill() function was called 3 times
The signal catching function was called 3 times
</pre>
<br>
<hr>
API introduced: V3R6
<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>