fish-shell/doc_src/cmds/trap.rst
Johannes Altmanninger 414d9a1eb1 Reference more non-fish shell builtins that have relevant differences
When writing scripts for other shells, it can be confusing and annoying
that our `man` function shadows other manual pages, for example `exec(1p)`
from [Linux man-pages]. I almost never want to see the fish variant for such
contended cases (which obviuosly don't include fish-specific commands like
`string`, only widely-known shell builtins).

For the contented cases like `exec`, the POSIX documentation is more
substantial and useful, since it describes a (sub)set of languages widely
used for scripting.

Because of this I think we should stop overriding the system's man pages.
Nowadays we offer `exec -h` as intuitive way to show the documentation for
the fish-specific command (note that `help` is not a good replacement because
it uses a web browser).

Looking through the contended commands, it seems like for most of them,
the fish version is not substantially different from the system version.
A notable exception is `read` but I don't think it's a very important one.

So I think we should can sacrifice a bit of the native fish-scripting
experience in exchange for playing nicer with other shells. I think the
latter is more important because scripting is not our focus, the way I see it.
So maybe put our manpath at the end.

In lieu of that, let's at least have `exec.rst` reference the system variant.

[Linux man-pages]: https://www.kernel.org/doc/man-pages/

Closes 
2024-04-20 13:34:08 +02:00

60 lines
2.0 KiB
ReStructuredText

.. _cmd-trap:
trap - perform an action when the shell receives a signal
=========================================================
Synopsis
--------
.. synopsis::
trap [OPTIONS] [[ARG] REASON ... ]
Description
-----------
.. only:: builder_man
NOTE: This page documents the fish builtin ``trap``.
To see the documentation on any non-fish versions, use ``command man trap``.
``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*
Command to be executed on signal delivery.
*REASON*
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.
**-h** or **--help**
Displays help about using this command.
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. Trapping a signal will prevent fish from exiting in response to that signal.
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.