diff options
Diffstat (limited to 'upstream/archlinux/man3p/kill.3p')
| -rw-r--r-- | upstream/archlinux/man3p/kill.3p | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/kill.3p b/upstream/archlinux/man3p/kill.3p new file mode 100644 index 00000000..8d64a257 --- /dev/null +++ b/upstream/archlinux/man3p/kill.3p @@ -0,0 +1,290 @@ +'\" 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 . |