Ruby: include/ruby/internal/intern/signal.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Functions
signal.h File Reference

Signal handling APIs. More...

`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Functions
VALUE | rb_f_kill (int argc, const VALUE *argv)
| Sends a signal ("kills") to processes.
const char * | ruby_signal_name (int signo)
| Queries the name of the signal.
void | ruby_default_signal (int sig)
| Pretends as if there was no custom signal handler.

## Detailed Description

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.

## Function Documentation

## ◆ rb_f_kill()

VALUE rb_f_kill | ( | int | argc,
|  | const VALUE * | argv )

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 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 423 of file signal.c.

Referenced by rb_f_kill().

## ◆ 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

  [in] | sig | The signal.

Postcondition
  Previous signal handler is lost.
  Passed signal is sent to the current process.

Definition at line 407 of file signal.c.

Referenced by ruby_default_signal().

## ◆ 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 316 of file signal.c.

Referenced by ruby_signal_name().