kill()--Send Signal to Process or Group of Processes

Syntax

 #include <sys/types.h>
 #include <signal.h>

 int kill( pid_t pid, int sig );

  Service Program Name: QPOSSRV1

  Default Public Authority: *USE

  Threadsafe: Yes

The kill() function sends a signal to a process or process group specified by pid. The signal to be sent is specified by sig and is either 0 or one of the signals from the list in the <sys/signal.h> header file.

The process sending the signal must have appropriate authority to the receiving process or processes. The kill() function is successful if the process has permission to send the signal sig to any of the processes specified by pid. If kill() is not successful, no signal is sent.

A process can use kill() to send a signal to itself. If the signal is not blocked in the sending thread, and if no other thread has the sig unblocked or is waiting in a sigwait function for sig, either sig or at least one pending unblocked signal is delivered to the sender before kill() returns.

Parameters

pid: (Input) The process ID or process group ID to receive the signal.
sig: (Input) The signal to be sent.

pid and sig can be used as follows:

pid_t pid;

Specifies the processes that the caller wants to send the signal to:

If pid is greater than zero, kill() sends the signal sig to the process whose ID is equal to pid.
If pid is equal to zero, kill() sends the signal sig 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.
If pid is equal to -1, kill() returns -1 and errno is set to [ESRCH].
If pid is less than -1, kill() sends the signal sig to all processes whose process group ID is equal to the absolute value of pid, except for those to which the sender does not have appropriate authority to send a signal.

int sig;

The signal that should be sent to the processes specified by pid. This must be zero, or one of the signals defined in the <sys/signal.h> header file. If sig is zero, kill() performs error checking, but does not send a signal. You can use a sig value of zero to check whether the pid argument is valid.

Authorities

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:

The thread is sending a signal to its own process.
The thread has *JOBCTL special authority defined in the currently running user profile or in a current adopted user profile.
The thread belongs to a process that is the parent of the receiving process. (The process being signaled has a parent process ID equal to the process ID of the thread sending the signal.)
If the receiving process is multi-threaded,
- The real or effective user ID of the thread matches the job user identity of the process receiving process (the process being signaled).
Otherwise,
- 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 <unistd.h> include file, the saved set user ID of the intended recipient is checked instead of its effective user ID.

The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work Management topic.

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.

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 process group ID) as the sender.

Return Value

0	kill() was successful. It had permission to send sig to one or more of the processes specified by pid.
-1	kill() was not successful. It failed to send a signal. The errno variable is set to indicate the error.

Error Conditions

If kill() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

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.

An argument value is not valid, out of range, or NULL.

The value of sig is not within the range of signal numbers or is a signal that is not supported.

[ENOTSIGINIT]

Process not enabled for signals.

An attempt was made to call a signal function under one of the following conditions:

The signal function is being called for a process that is not enabled for asynchronous signals.
The signal function is being called when the system signal controls have not been initialized.

[ENOSYSRSC]

System resources not available to complete request.

[EPERM]

Operation not permitted.

You must have appropriate privileges or be the owner of the object or other resource to do the requested operation.

[ESRCH]

No item could be found that matches the specified value.

The process or process group specified in pid cannot be found.

Usage Notes

If the value of pid is 0 (so that kill() is used to send a signal to all processes whose process group ID is equal to that of the sender), kill() enables the process for signals if the process is not already enabled for signals. For details, see Qp0sEnableSignals()--Enable Process for Signals.
A process can use kill() to simulate the American National Standard C raise() function by using the following:
```
   sigset_t  sigmask;

   /*
    * Allow all signals to be delivered by unblocking all signals
   */

   sigemtyset( &sigmask );
   sigprocmask( SIG_SETMASK, &sigmask, NULL );

   ...

   kill( getpid(), SIGUSR1 );
```
The example above ensures that no signals are blocked from delivery. When the kill() function is called, the behavior is the same as calling the raise() function.

Related Information

The <signal.h> file (see Header Files for UNIX-Type Functions)
The <sys/types.h> file (see Header Files for UNIX-Type Functions)
Qp0sDisableSignals()--Disable Process for Signals
Qp0sEnableSignals()--Enable Process for Signals
sigaction()--Examine and Change Signal Action
sigtimedwait()--Synchronously Accept a Signal for Interval of Time
sigwait()--Synchronously Accept a Signal
sigwaitinfo()--Synchronously Accept a Signal and Signal Data

Example

See Code disclaimer information for information pertaining to code examples.

The following example uses the kill() function:

#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 );
}

Output:

    Back in main
    The kill() function was called 3 times
    The signal catching function was called 3 times

API introduced: V3R6

Top | UNIX-Type APIs | APIs by category