fish-shell/doc_src/cmds/trap.rst

.. _cmd-trap:

trap - perform an action when the shell receives a signal
=========================================================

Synopsis
--------

::

    trap [OPTIONS] [[ARG] REASON ... ]

Description
-----------

``trap`` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an :ref:`event handler <event>`.

The following parameters are available:

- ``ARG`` is the command to be executed on signal delivery.

- ``REASON`` is the name of the event to trap. For example, a signal like ``INT`` or ``SIGINT``, or the special symbol ``EXIT``.

- ``-l`` or ``--list-signals`` prints a list of signal names.

- ``-p`` or ``--print`` prints all defined signal handlers.

If ``ARG`` and ``REASON`` are both specified, ``ARG`` is the command to be executed when the event specified by ``REASON`` occurs (e.g., the signal is delivered).

If ``ARG`` is absent (and there is a single REASON) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell).  If ``ARG`` is the null string the signal specified by each ``REASON`` is ignored by the shell and by the commands it invokes.

If ``ARG`` is not present and ``-p`` has been supplied, then the trap commands associated with each ``REASON`` are displayed. If no arguments are supplied or if only ``-p`` is given, ``trap`` prints the list of commands associated with each signal.

Signal names are case insensitive and the ``SIG`` prefix is optional.

The exit status is 1 if any ``REASON`` is invalid; otherwise trap returns 0.

Example
-------


::

    trap "status --print-stack-trace" SIGUSR1
    # Prints a stack trace each time the SIGUSR1 signal is sent to the shell.
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 17:05:09 +08:00			`.. _cmd-trap:`

Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00			`trap - perform an action when the shell receives a signal`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`=========================================================`
Switch command docs from \section to reStructuredText 2018-12-17 09:39:33 +08:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`::`
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00
docs: update all command synopsis formatting Adds synopses for those commands missing them. Moves all synopsis sections to code blocks. This improves the appearance, although highlighting as fish code may not be the ideal appearance. 2019-09-17 17:59:04 +08:00			`trap [OPTIONS] [[ARG] REASON ... ]`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Description`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs: Fix remaining references Fixes #5775. 2019-03-31 17:32:40 +08:00			``trap`` is a wrapper around the fish event delivery framework. It exists for backwards compatibility with POSIX shells. For other uses, it is recommended to define an :ref:`event handler <event>`.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
			`The following parameters are available:`

Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``ARG`` is the command to be executed on signal delivery.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``REASON`` is the name of the event to trap. For example, a signal like ``INT`` or ``SIGINT``, or the special symbol ``EXIT``.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-l`` or ``--list-signals`` prints a list of signal names.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			- ``-p`` or ``--print`` prints all defined signal handlers.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			If ``ARG`` and ``REASON`` are both specified, ``ARG`` is the command to be executed when the event specified by ``REASON`` occurs (e.g., the signal is delivered).
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			If ``ARG`` is absent (and there is a single REASON) or -, each specified signal is reset to its original disposition (the value it had upon entrance to the shell). If ``ARG`` is the null string the signal specified by each ``REASON`` is ignored by the shell and by the commands it invokes.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			If ``ARG`` is not present and ``-p`` has been supplied, then the trap commands associated with each ``REASON`` are displayed. If no arguments are supplied or if only ``-p`` is given, ``trap`` prints the list of commands associated with each signal.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			Signal names are case insensitive and the ``SIG`` prefix is optional.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
docs: standardise on exit status terminology Exit status is used in the POSIX specification and is preferred over return code/return status/exit code. [ci skip] 2019-09-17 16:31:39 +08:00			The exit status is 1 if any ``REASON`` is invalid; otherwise trap returns 0.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Convert \\subsection sections into rst format 2018-12-19 10:44:30 +08:00			`Example`
Fix command section separator line lengths 2019-01-03 12:10:47 +08:00			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-17 05:08:41 +08:00
Switch \fish sections to rst format 2018-12-19 11:14:04 +08:00

			`::`

			`trap "status --print-stack-trace" SIGUSR1`
			`# Prints a stack trace each time the SIGUSR1 signal is sent to the shell.`