fish-shell/sphinx_doc_src/cmds/trap.rst

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 <a href='index.html#event'>event handler</a>.

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 return 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.
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
			`trap [OPTIONS] [[ARG] REASON ... ]`
Migrate the 'synopsis' sections to .rst format 2018-12-18 09:58:24 +08:00
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
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +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 <a href='index.html#event'>event handler</a>.
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
Switch backticks to double backticks for rst compatibility 2018-12-20 04:02:45 +08:00			The return 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.`