# The trap builtin command

## Synopsis

    trap [-lp] [[ARGUMENT] SIGNAL]

## Description

The `trap` command is used to "trap" signals and other events. In this
context, "trapping" means to install handler code.

The shell code `ARGUMENT` is to be read and executed whenever the shell
receives a signal or another event `SIGNAL`. The given `SIGNAL`
specification can be

-   the name of a signal with the SIG prefix, e.g. `SIGTERM`
-   the name of a signal without the SIG prefix, e.g. `TERM`
-   the number of a signal (see `trap -l`), e.g. `15`
-   the name or number of a special event (see table below), e.g. `EXIT`

Without any options or operands, `trap` prints a list of installed traps
in a reusable format (equivalent to the `-p` option).

Special `ARGUMENT`s

-   if `ARGUMENT` is absent or `-` (dash), the signal/event handler is
    reset to its original value
-   if `ARGUMENT` is the null string, the signal/event is ignored

Special events

|Name|Code|Description|
|----|----|-----------|
|`EXIT`|0|executed on shell exit|
|`DEBUG`||executed before every simple command|
|`RETURN`||executed when a shell function or a sourced code finishes executing|
|`ERR`||executed each time a command's failure would cause the shell to exit when the [`-e` option (`errexit`)](../../commands/builtin/set.md) is enabled|

### Options

|Option|Description|
|------|-----------|
|`-l`|print a list of signal names and their corresponding numbers|
|`-p`|display the trap commands associated with each signal specification in a reusable format|

### Return status

|Status|Reason|
|------|------|
|0|no error/success|
|!=0|invalid option|
|!=0|invalid signal specification|

## Examples

### List installed traps

    trap

### Ignore terminal interrupt (Ctrl-C, SIGINT)

    trap '' INT

## Portability considerations

-   `trap` is specified by POSIX(R) without the `-l` and `-p` options
-   in POSIX(R), beside signals, only `EXIT` (0) is valid as an event

## See also

-   [the set command](../../commands/builtin/set.md) for the `-e` (`errexit`)
    option