man2/kill.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified by Michael Haardt <michael@moria.de>
   6 .\" Modified by Thomas Koenig <ig25@rz.uni-karlsruhe.de>
   7 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified 1993-07-25 by Rik Faith <faith@cs.unc.edu>
   9 .\" Modified 1995-11-01 by Michael Haardt
  10 .\"  <michael@cantor.informatik.rwth-aachen.de>
  11 .\" Modified 1996-04-14 by Andries Brouwer <aeb@cwi.nl>
  12 .\"  [added some polishing contributed by Mike Battersby <mib@deakin.edu.au>]
  13 .\" Modified 1996-07-21 by Andries Brouwer <aeb@cwi.nl>
  14 .\" Modified 1997-01-17 by Andries Brouwer <aeb@cwi.nl>
  15 .\" Modified 2001-12-18 by Andries Brouwer <aeb@cwi.nl>
  16 .\" Modified 2002-07-24 by Michael Kerrisk <mtk.manpages@gmail.com>
  17 .\"     Added note on historical rules enforced when an unprivileged process
  18 .\"     sends a signal.
  19 .\" Modified 2004-06-16 by Michael Kerrisk <mtk.manpages@gmail.com>
  20 .\"     Added note on CAP_KILL
  21 .\" Modified 2004-06-24 by aeb
  22 .\" Modified, 2004-11-30, after idea from emmanuel.colbus@ensimag.imag.fr
  23 .\"
  24 .TH kill 2 (date) "Linux man-pages (unreleased)"
  25 .SH NAME
  26 kill \- send signal to a process
  27 .SH LIBRARY
  28 Standard C library
  29 .RI ( libc ", " \-lc )
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <signal.h>
  33 .PP
  34 .BI "int kill(pid_t " pid ", int " sig );
  35 .fi
  36 .PP
  37 .RS -4
  38 Feature Test Macro Requirements for glibc (see
  39 .BR feature_test_macros (7)):
  40 .RE
  41 .PP
  42 .BR kill ():
  43 .nf
  44     _POSIX_C_SOURCE
  45 .fi
  46 .SH DESCRIPTION
  47 The
  48 .BR kill ()
  49 system call
  50 can be used to send any signal to any process group or process.
  51 .PP
  52 If \fIpid\fP is positive, then signal \fIsig\fP is sent to the
  53 process with the ID specified by \fIpid\fP.
  54 .PP
  55 If \fIpid\fP equals 0, then \fIsig\fP is sent to every process in the
  56 process group of the calling process.
  57 .PP
  58 If \fIpid\fP equals \-1, then \fIsig\fP is sent to every process
  59 for which the calling process has permission to send signals,
  60 except for process 1 (\fIinit\fP), but see below.
  61 .PP
  62 If \fIpid\fP is less than \-1, then \fIsig\fP is sent to every process
  63 in the process group whose ID is \fI\-pid\fP.
  64 .PP
  65 If \fIsig\fP is 0, then no signal is sent,
  66 but existence and permission checks are still performed;
  67 this can be used to check for the existence of a process ID or
  68 process group ID that the caller is permitted to signal.
  69 .PP
  70 For a process to have permission to send a signal,
  71 it must either be privileged (under Linux: have the
  72 .B CAP_KILL
  73 capability in the user namespace of the target process),
  74 or the real or effective user ID of the sending process must equal
  75 the real or saved set-user-ID of the target process.
  76 In the case of
  77 .BR SIGCONT ,
  78 it suffices when the sending and receiving
  79 processes belong to the same session.
  80 (Historically, the rules were different; see NOTES.)
  81 .SH RETURN VALUE
  82 On success (at least one signal was sent), zero is returned.
  83 On error, \-1 is returned, and
  84 .I errno
  85 is set to indicate the error.
  86 .SH ERRORS
  87 .TP
  88 .B EINVAL
  89 An invalid signal was specified.
  90 .TP
  91 .B EPERM
  92 The calling process does not have permission to send the signal
  93 to any of the target processes.
  94 .TP
  95 .B ESRCH
  96 The target process or process group does not exist.
  97 Note that an existing process might be a zombie,
  98 a process that has terminated execution, but
  99 has not yet been
 100 .BR wait (2)ed
 101 for.
 102 .SH STANDARDS
 103 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 104 .SH NOTES
 105 The only signals that can be sent to process ID 1, the
 106 .I init
 107 process, are those for which
 108 .I init
 109 has explicitly installed signal handlers.
 110 This is done to assure the
 111 system is not brought down accidentally.
 112 .PP
 113 POSIX.1 requires that \fIkill(\-1,sig)\fP send \fIsig\fP
 114 to all processes that the calling process may send signals to,
 115 except possibly for some implementation-defined system processes.
 116 Linux allows a process to signal itself, but on Linux the call
 117 \fIkill(\-1,sig)\fP does not signal the calling process.
 118 .PP
 119 POSIX.1 requires that if a process sends a signal to itself,
 120 and the sending thread does not have the signal blocked,
 121 and no other thread
 122 has it unblocked or is waiting for it in
 123 .BR sigwait (3),
 124 at least one
 125 unblocked signal must be delivered to the sending thread before the
 126 .BR kill ()
 127 returns.
 128 .SS Linux notes
 129 Across different kernel versions, Linux has enforced different rules
 130 for the permissions required for an unprivileged process
 131 to send a signal to another process.
 132 .\" In the 0.* kernels things chopped and changed quite
 133 .\" a bit - MTK, 24 Jul 02
 134 In kernels 1.0 to 1.2.2, a signal could be sent if the
 135 effective user ID of the sender matched effective user ID of the target,
 136 or the real user ID of the sender matched the real user ID of the target.
 137 From kernel 1.2.3 until 1.3.77, a signal could be sent if the
 138 effective user ID of the sender matched either the real or effective
 139 user ID of the target.
 140 The current rules, which conform to POSIX.1, were adopted
 141 in kernel 1.3.78.
 142 .SH BUGS
 143 In 2.6 kernels up to and including 2.6.7,
 144 there was a bug that meant that when sending signals to a process group,
 145 .BR kill ()
 146 failed with the error
 147 .B EPERM
 148 if the caller did not have permission to send the signal to \fIany\fP (rather
 149 than \fIall\fP) of the members of the process group.
 150 Notwithstanding this error return, the signal was still delivered
 151 to all of the processes for which the caller had permission to signal.
 152 .SH SEE ALSO
 153 .BR kill (1),
 154 .BR _exit (2),
 155 .BR pidfd_send_signal (2),
 156 .BR signal (2),
 157 .BR tkill (2),
 158 .BR exit (3),
 159 .BR killpg (3),
 160 .BR sigqueue (3),
 161 .BR capabilities (7),
 162 .BR credentials (7),
 163 .BR signal (7)