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.