TRAP(1)

NAME
trap - trap signals and run a variety of commands according to the signals caught

SYNOPSIS
In an execlineb(1) script:

trap [-x]
{

[ SIGTERM { progsigterm... }]

[ quit { progsigquit ... }]

[ 1 { progsighup ... }]

[ default { progdefault ... }]

...

}

prog...

DESCRIPTION
trap reads a sequence of directives in a block ( cf. execline-block(7)). It expects at least one directive.

Each directive is a keyword followed by a block.

The keyword can be the special word ‘default’, 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 ( cf. execline-exitcodes(7)) of the same exit code.

Programs defined in command line directives can start with ‘importas’!! ( cf. importas(1)) 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 }’ ( cf. multisubstitute(1)) 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.

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.

SEE ALSO
emptyenv(1), envfile(1), exec(1), execline-cd(1), execline-umask(1), execlineb(1), exit(1), export(1), fdblock(1), fdclose(1), fdmove(1), fdreserve(1), fdswap(1), getcwd(1), getpid(1), heredoc(1), importas(1), multisubstitute(1), piperw(1), posix-cd(1), posix-umask(1), redirfd(1), tryexec(1), unexport(1), wait(1), withstdinas(1), execline-block(7), execline-exitcodes(7)

This man page is ported from the authoritative documentation at: https://skarnet.org/software/execline/trap.html

AUTHORS
Laurent Bercot Alexis <flexibeast@gmail.com> (man page port)