execline: the trap command
Keywords: execline command trap signal

execline
Software
skarnet.org

# The `trap` program

`trap` traps signals and runs a variety of commands according to the signals it catches.

## Interface

In an execlineb script:

         trap [ -x ]
         {
           [ SIGTERM { progsigterm... } ]
           [ quit { progsigquit... } ]
           [ 1 { progsighup... } ]
           [ default { progdefault... } ]
           ...
         }
         prog...

- `trap` reads a sequence of directives in a block. It expects at least one directive.
- Each directive is a keyword followed by a block.
- The keyword can be the special word `timeout`, a signal name (case-insensitive, with or without the `SIG` prefix), or a signal number. The block following it is a command line to run when the specified event occurs.
- `trap` sets traps for the various directives it reads. A trap for `SIGTERM` will be triggered when the `trap` program receives a SIGTERM. A `default` trap will be used for any signal that is not caught by another trap.
- It spawns a child executing prog....
- It sets the `!` environment variable to the pid of the prog... process, and the `SIGNAL` environment variable to the trapped signal.
- Whenever it catches a signal, it spawns the program described in the corresponding directive. It will not spawn a program for the same signal twice: if the first subprocess is still active when another instance of the same signal arrives, this second instance is ignored.
- When prog... exits, `trap` exits with an approximation of the same exit code.

## Options

- `-x` : forward signals. If this option is given, any signal that `trap` receives and that is not explicitly trapped will be sent to prog. By default, `trap` does not forward any signals, and does not ignore them either - for instance a SIGTERM, unless caught by a `SIGTERM` directive, will kill the `trap` process (and leave prog running). With the `-x` option, without a `SIGTERM` directive, a SIGTERM will still be caught by `trap`, that will send it to prog. Note that if a `default` directive is present, this option does nothing.

## Notes

- Programs defined in command line directives can start with `importas ! !` to retrieve the pid of prog in `$!`. If they need the signal number, which can be the case in `default` directives, they can for instance use `multisubstitute { importas ! ! importas SIGNAL SIGNAL }`to get both `$!` and `$SIGNAL` substitutions.``
- The `-x` option is basically a shortcut for a `default { multisubstitute { importas ! ! importas SIGNAL SIGNAL } kill -$SIGNAL $! }` directive.
- `trap` is a standard shell builtin, with similar functionality. It is more idiomatic, and probably more efficient, to use that builtin in shell scripts, and to only use the `trap` program in execline scripts.