Ruby 3.5.0dev (2025-02-22 revision 412997300569c1853c09813e4924b6df3d7e8669)
Functions
signal.h File Reference

(412997300569c1853c09813e4924b6df3d7e8669)

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"
Include dependency graph for signal.h:
This graph shows which files directly or indirectly include this file:

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 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]argcNumber of objects in argv.
[in]argvSignal, followed by target PIDs.
Exceptions
rb_eArgErrorUnknown signal name.
rb_eSystemCallErrorVarious 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.

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]sigThe signal.
Postcondition
Previous signal handler is lost.
Passed signal is sent to the current process.

Definition at line 411 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]signoSignal number to query.
Return values
0No such signal.
otherwiseA 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.

Referenced by ruby_signal_name().

Generated by doxygen 1.9.8