Blame docs/src/signal.rst

Packit b5b901
Packit b5b901
.. _signal:
Packit b5b901
Packit b5b901
:c:type:`uv_signal_t` --- Signal handle
Packit b5b901
=======================================
Packit b5b901
Packit b5b901
Signal handles implement Unix style signal handling on a per-event loop bases.
Packit b5b901
Packit Service e08953
Windows notes
Packit Service e08953
-------------
Packit Service e08953
Packit Service e08953
Reception of some signals is emulated:
Packit b5b901
Packit b5b901
* SIGINT is normally delivered when the user presses CTRL+C. However, like
Packit b5b901
  on Unix, it is not generated when terminal raw mode is enabled.
Packit b5b901
Packit b5b901
* SIGBREAK is delivered when the user pressed CTRL + BREAK.
Packit b5b901
Packit b5b901
* SIGHUP is generated when the user closes the console window. On SIGHUP the
Packit b5b901
  program is given approximately 10 seconds to perform cleanup. After that
Packit b5b901
  Windows will unconditionally terminate it.
Packit b5b901
Packit Service e08953
* SIGWINCH is raised whenever libuv detects that the console has been
Packit Service e08953
  resized. When a libuv app is running under a console emulator, or when a
Packit Service e08953
  32-bit libuv app is running on 64-bit system, SIGWINCH will be emulated. In
Packit Service e08953
  such cases SIGWINCH signals may not always be delivered in a timely manner.
Packit Service e08953
  For a writable :c:type:`uv_tty_t` handle libuv will only detect size changes
Packit Service e08953
  when the cursor is moved. When a readable :c:type:`uv_tty_t` handle is used,
Packit Service e08953
  resizing of the console buffer will be detected only if the handle is in raw
Packit Service e08953
  mode and is being read.
Packit Service e08953
Packit b5b901
* Watchers for other signals can be successfully created, but these signals
Packit b5b901
  are never received. These signals are: `SIGILL`, `SIGABRT`, `SIGFPE`, `SIGSEGV`,
Packit b5b901
  `SIGTERM` and `SIGKILL.`
Packit b5b901
Packit b5b901
* Calls to raise() or abort() to programmatically raise a signal are
Packit b5b901
  not detected by libuv; these will not trigger a signal watcher.
Packit b5b901
Packit b5b901
.. versionchanged:: 1.15.0 SIGWINCH support on Windows was improved.
Packit Service e08953
.. versionchanged:: 1.31.0 32-bit libuv SIGWINCH support on 64-bit Windows was
Packit Service e08953
                           rolled back to old implementation.
Packit Service e08953
Packit Service e08953
Unix notes
Packit Service e08953
----------
Packit Service e08953
Packit Service e08953
* SIGKILL and SIGSTOP are impossible to catch.
Packit Service e08953
Packit Service e08953
* Handling SIGBUS, SIGFPE, SIGILL or SIGSEGV via libuv results into undefined behavior.
Packit Service e08953
Packit Service e08953
* SIGABRT will not be caught by libuv if generated by `abort()`, e.g. through `assert()`.
Packit Service e08953
Packit Service e08953
* On Linux SIGRT0 and SIGRT1 (signals 32 and 33) are used by the NPTL pthreads library to
Packit Service e08953
  manage threads. Installing watchers for those signals will lead to unpredictable behavior
Packit Service e08953
  and is strongly discouraged. Future versions of libuv may simply reject them.
Packit Service e08953
Packit b5b901
Packit b5b901
Data types
Packit b5b901
----------
Packit b5b901
Packit b5b901
.. c:type:: uv_signal_t
Packit b5b901
Packit b5b901
    Signal handle type.
Packit b5b901
Packit b5b901
.. c:type:: void (*uv_signal_cb)(uv_signal_t* handle, int signum)
Packit b5b901
Packit b5b901
    Type definition for callback passed to :c:func:`uv_signal_start`.
Packit b5b901
Packit b5b901
Packit b5b901
Public members
Packit b5b901
^^^^^^^^^^^^^^
Packit b5b901
Packit b5b901
.. c:member:: int uv_signal_t.signum
Packit b5b901
Packit b5b901
    Signal being monitored by this handle. Readonly.
Packit b5b901
Packit b5b901
.. seealso:: The :c:type:`uv_handle_t` members also apply.
Packit b5b901
Packit b5b901
Packit b5b901
API
Packit b5b901
---
Packit b5b901
Packit b5b901
.. c:function:: int uv_signal_init(uv_loop_t* loop, uv_signal_t* signal)
Packit b5b901
Packit b5b901
    Initialize the handle.
Packit b5b901
Packit b5b901
.. c:function:: int uv_signal_start(uv_signal_t* signal, uv_signal_cb cb, int signum)
Packit b5b901
Packit b5b901
    Start the handle with the given callback, watching for the given signal.
Packit b5b901
Packit b5b901
.. c:function:: int uv_signal_start_oneshot(uv_signal_t* signal, uv_signal_cb cb, int signum)
Packit b5b901
Packit b5b901
    .. versionadded:: 1.12.0
Packit b5b901
Packit b5b901
    Same functionality as :c:func:`uv_signal_start` but the signal handler is reset the moment
Packit b5b901
    the signal is received.
Packit b5b901
Packit b5b901
.. c:function:: int uv_signal_stop(uv_signal_t* signal)
Packit b5b901
Packit b5b901
    Stop the handle, the callback will no longer be called.
Packit b5b901
Packit b5b901
.. seealso:: The :c:type:`uv_handle_t` API functions also apply.