path: root/upstream/archlinux/man3p/kill.3p

'\" et
.TH KILL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
kill
\(em send a signal to a process or a group of processes
.SH SYNOPSIS
.LP
.nf
#include <signal.h>
.P
int kill(pid_t \fIpid\fP, int \fIsig\fP);
.fi
.SH DESCRIPTION
The
\fIkill\fR()
function shall send a signal to a process or a group of processes
specified by
.IR pid .
The signal to be sent is specified by
.IR sig
and is either one from the list given in
.IR <signal.h> 
or 0. If
.IR sig
is 0 (the null signal), error checking is performed but no signal is
actually sent. The null signal can be used to check the validity of
.IR pid .
.P
For a process to have permission to send a signal to a process
designated by
.IR pid ,
unless the sending process has appropriate privileges, the real or
effective user ID of the sending process shall match the real or saved
set-user-ID of the receiving process.
.P
If
.IR pid
is greater than 0,
.IR sig
shall be sent to the process whose process ID is equal to
.IR pid .
.P
If
.IR pid
is 0,
.IR sig
shall be sent to all processes (excluding an unspecified set of system
processes) whose process group ID is equal to the process group ID of
the sender, and for which the process has permission to send a signal.
.P
If
.IR pid
is \-1,
.IR sig
shall be sent to all processes (excluding an unspecified set of system
processes) for which the process has permission to send that signal.
.P
If
.IR pid
is negative, but not \-1,
.IR sig
shall be sent to all processes (excluding an unspecified set of system
processes) whose process group ID is equal to the absolute value of
.IR pid ,
and for which the process has permission to send a signal.
.P
If the value of
.IR pid
causes
.IR sig
to be generated for the sending process, and if
.IR sig
is not blocked for the calling thread and if no other thread has
.IR sig
unblocked or is waiting in a
\fIsigwait\fR()
function for
.IR sig ,
either
.IR sig
or at least one pending unblocked signal shall be delivered to the
sending thread before
\fIkill\fR()
returns.
.P
The user ID tests described above shall not be applied when sending
SIGCONT to a process that is a member of the same session as the
sending process.
.P
An implementation that provides extended security controls may impose
further implementation-defined restrictions on the sending of
signals, including the null signal. In particular, the system may deny
the existence of some or all of the processes specified by
.IR pid .
.P
The
\fIkill\fR()
function is successful if the process has permission to send
.IR sig
to any of the processes specified by
.IR pid .
If
\fIkill\fR()
fails, no signal shall be sent.
.SH "RETURN VALUE"
Upon successful completion, 0 shall be returned. Otherwise, \-1
shall be returned and
.IR errno
set to indicate the error.
.SH ERRORS
The
\fIkill\fR()
function shall fail if:
.TP
.BR EINVAL
The value of the
.IR sig
argument is an invalid or unsupported signal number.
.TP
.BR EPERM
The process does not have permission to send the signal to any
receiving process.
.TP
.BR ESRCH
No process or process group can be found corresponding to that
specified by
.IR pid .
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
The semantics for permission checking for
\fIkill\fR()
differed between System V and most other implementations, such as
Version 7 or
4.3 BSD. The semantics chosen for this volume of POSIX.1\(hy2017 agree with System V.
Specifically, a set-user-ID
process cannot protect itself against signals (or at least not against
SIGKILL)
unless it changes its real user ID.
This choice allows the user who starts an application to send it
signals even if it changes its effective user ID.
The other semantics give more power to an application that wants to
protect itself from the user who ran it.
.P
Some implementations provide semantic extensions to the
\fIkill\fR()
function when the absolute value of
.IR pid
is greater than some maximum, or otherwise special, value. Negative
values are a flag to
\fIkill\fR().
Since most implementations return
.BR [ESRCH] 
in this case, this behavior is not included in this volume of POSIX.1\(hy2017, although
a conforming implementation could provide such an extension.
.P
The unspecified processes to which a signal cannot be sent
may include the scheduler or
.IR init .
.P
There was initially strong sentiment to specify that, if
.IR pid
specifies that a signal be sent to the calling process and that signal
is not blocked, that signal would be delivered before
\fIkill\fR()
returns. This would permit a process to call
\fIkill\fR()
and be guaranteed that the call never return. However, historical
implementations that provide only the
\fIsignal\fR()
function make only the weaker guarantee in this volume of POSIX.1\(hy2017, because they
only deliver one signal each time a process enters the kernel.
Modifications to such implementations to support the
\fIsigaction\fR()
function generally require entry to the kernel following return from a
signal-catching function, in order to restore the signal mask. Such
modifications have the effect of satisfying the stronger requirement,
at least when
\fIsigaction\fR()
is used, but not necessarily when
\fIsignal\fR()
is used. The standard developers considered making the
stronger requirement except when
\fIsignal\fR()
is used, but felt this would be unnecessarily complex. Implementors
are encouraged to meet the stronger requirement whenever possible. In
practice, the weaker requirement is the same, except in the rare case
when two signals arrive during a very short window. This reasoning
also applies to a similar requirement for
\fIsigprocmask\fR().
.P
In 4.2 BSD, the SIGCONT
signal can be sent to any descendant process regardless of user-ID
security checks.
This allows a job control shell to continue a job even if processes in
the
job have altered their user IDs (as in the
.IR su
command). In keeping with the addition of the concept of sessions,
similar functionality is provided by allowing the SIGCONT
signal to be sent to any process in the same session regardless of user
ID security checks. This is less restrictive than BSD in the sense
that ancestor processes (in the same session) can now be the recipient.
It is more restrictive than BSD in the sense that descendant processes
that form new sessions are now subject to the user ID checks. A similar
relaxation of security is not necessary for the other job control
signals since those signals are typically sent by the terminal driver
in recognition of special characters being typed; the terminal driver
bypasses all security checks.
.P
In secure implementations, a process may be restricted
from sending a signal to a process having a different security label.
In order to prevent the existence or nonexistence of a process from
being used as a covert channel,
such processes should appear nonexistent to the sender; that is,
.BR [ESRCH] 
should be returned, rather than
.BR [EPERM] ,
if
.IR pid
refers only to such processes.
.P
Historical implementations varied on the result of a
\fIkill\fR()
with
.IR pid
indicating a zombie process. Some indicated success on such a call
(subject to permission checking), while others gave an error of
.BR [ESRCH] .
Since the definition of process lifetime in this volume of POSIX.1\(hy2017
covers zombie processes, the
.BR [ESRCH] 
error as described is inappropriate in this case and implementations
that give this error do not conform. This means that an application
cannot have a parent process check for termination of a particular
child by sending it the null signal with
\fIkill\fR(),
but must instead use
\fIwaitpid\fR()
or
\fIwaitid\fR().
.P
There is some belief that the name
\fIkill\fR()
is misleading, since the function is not always intended to cause
process termination. However, the name is common to all historical
implementations, and any change would be in conflict with the goal of
minimal changes to existing application code.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIgetpid\fR\^(\|)",
.IR "\fIraise\fR\^(\|)",
.IR "\fIsetsid\fR\^(\|)",
.IR "\fIsigaction\fR\^(\|)",
.IR "\fIsigqueue\fR\^(\|)",
.IR "\fIwait\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<signal.h>\fP",
.IR "\fB<sys_types.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .