(37a72b0150ec36b4ea27175039afc28c62207b0c)
Signal handling APIs.
More...
Go to the source code of this file.
Signal handling APIs.
- Author
- Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
- Copyright
- This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.
- Warning
- Symbols prefixed with either
RBIMPL
or rbimpl
are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.
- Note
- To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance
__VA_ARGS__
is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.
Definition in file signal.h.
◆ rb_f_kill()
Sends a signal ("kills") to processes.
The first argument is the signal, either in:
- Numerical representation (e.g.
9
), or
- Textual representation of canonical (e.g.
:SIGKILL
) name or abbreviated (e.g. :KILL
) name, either in rb_cSymbol or rb_cString.
All the remaining arguments are numerical representations of process IDs. This function iterates over them to send the specified signal.
You can specify both negative PIDs and negative signo to this function:
sig \ pid | >= 1 | == 0 | == -1 | <= -2
===========+======+======+=======+=======
> 0 | #1 | #2 | #3 | #4
== 0 | #5 | #6 | #7 | #8
< 0 | #9 | #10 | #11
- Case #1: When signo and PID are both positive, this function sends the specified signal to the specified process (intuitive).
- Case #2: When signo is positive and PID is zero, this function sends that signal to the current process group.
- Case #3: When signo is positive and PID is -1, this function sends that signal to everything that the current process is allowed to kill.
- Case #4: When signo is positive and PID is negative (but not -1), this function sends that signal to every processes in a process group, whose process group ID is the absolute value of the passed PID.
- Case #5: When signo is zero and PID is positive, this function just checks for the existence of the specified process and doesn't send anything to anyone. In case the process is absent
Errno::ESRCH
is raised.
- Case #6: When signo and PID are both zero, this function checks for the existence of the current process group. And it must do. This function is effectively a no-op then.
- Case #7: When signo is zero and PID is -1, this function checks if there is any other process that the current process can kill. At least init (PID 1) must exist, so this must not fail.
- Case #8: When signo is zero and PID is negative (but not -1), this function checks if there is a process group whose process group ID is the absolute value of the passed PID. In case the process group is absent
Errno::ESRCH
is raised.
- Case #9: When signo is negative and PID is positive, this function sends the absolute value of the passed signo to the process group specified as the PID.
- Case #10: When signo is negative and PID is zero, it is highly expected that this function sends the absolute value of the passed signo to the current process group. Strictly speaking, IEEE Std 1003.1-2017 specifies that this (
killpg(3posix)
with an argument of zero) is an undefined behaviour. But no operating system is known so far that does things differently.
- Case #11: When signo and PID are both negative, the behaviour of this function depends on how
killpg(3)
works. On Linux, it seems such attempt is strictly prohibited and Errno::EINVAL
is raised. But on macOS, it seems it tries to send the signal actually to the process group.
- Note
- Above description is in fact different from how
kill(2)
works. We interpret the passed arguments before passing them through to system calls.
- Parameters
-
[in] | argc | Number of objects in argv . |
[in] | argv | Signal, followed by target PIDs. |
- Exceptions
-
rb_eArgError | Unknown signal name. |
rb_eSystemCallError | Various errors sending signal to processes. |
- Returns
- Something numeric. The meaning of this return value is unclear. It seems in case of #1 above, this could be the body count. But other cases remain mysterious.
Definition at line 430 of file signal.c.
◆ ruby_default_signal()
void ruby_default_signal |
( |
int |
sig | ) |
|
Pretends as if there was no custom signal handler.
This function sets the signal action to SIG_DFL, then kills itself.
- Parameters
-
- Postcondition
- Previous signal handler is lost.
-
Passed signal is sent to the current process.
Definition at line 411 of file signal.c.
◆ ruby_signal_name()
const char* ruby_signal_name |
( |
int |
signo | ) |
|
Queries the name of the signal.
It returns for instance "KILL"
for SIGKILL.
- Parameters
-
[in] | signo | Signal number to query. |
- Return values
-
0 | No such signal. |
otherwise | A pointer to a static C string that is the name of the signal. |
- Warning
- Don't free the return value.
Definition at line 317 of file signal.c.