<!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>