diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2015-05-05 13:10:13 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2015-05-05 13:10:13 +0000 |
| commit | 2c59f669553677838022d65f2433b31a04bc632d (patch) | |
| tree | 90b723368a2be42aaa2f36c7dc9b351f98a93e12 /doc/trap.html | |
| parent | 820a98c94c134745b1da83d10b648e6c8f83791e (diff) | |
| download | execline-2c59f669553677838022d65f2433b31a04bc632d.tar.xz | |
- add trapv2.1.2.0
- rc for 2.1.2.0
Diffstat (limited to 'doc/trap.html')
| -rw-r--r-- | doc/trap.html | 98 |
1 files changed, 98 insertions, 0 deletions
diff --git a/doc/trap.html b/doc/trap.html new file mode 100644 index 0000000..ff03c2e --- /dev/null +++ b/doc/trap.html @@ -0,0 +1,98 @@ +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>execline: the trap command</title> + <meta name="Description" content="execline: the trap command" /> + <meta name="Keywords" content="execline command trap signal" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> +</head> +<body> + +<p> +<a href="index.html">execline</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>trap</tt> program </h1> + +<tt>trap</tt> traps signals and runs a variety of commands according +to the signals it catches. + +<h2> Interface </h2> + +<p> + In an <a href="execlineb.html">execlineb</a> script: +</p> + +<pre> + trap [ -x ] [ -t <em>millisecs</em> ] + { + [ timeout { <em>progtimeout...</em> } ] + [ SIGTERM { <em>progsigterm...</em> } ] + [ quit { <em>progsigquit...</em> } ] + [ 1 { <em>progsighup</em>... } ] + ... + } + <em>prog...</em> +</pre> + +<ul> + <li> <tt>trap</tt> reads a sequence of directives in a +<a href="el_semicolon.html">block</a>. It expects at least one +directive. </li> + <li> Each directive is a keyword followed by a block. </li> + <li> The keyword can be the special word <tt>timeout</tt>, a signal +name (case-insensitive, with or without the <tt>SIG</tt> prefix), + or a signal number. The block following it is a command line to +run when the specified event occurs. </li> + <li> <tt>trap</tt> sets traps for the various directives it reads. +A trap for <tt>SIGTERM</tt> will be triggered when the <tt>trap</tt> +program receives a SIGTERM. +A trap for <tt>timeout</tt> will be triggered when <em>millisecs</em> +milliseconds elapse without a signal being caught. </li> + <li> It spawns a child executing <em>prog...</em>. </li> + <li> It sets the <tt>!</tt> environment +variable to the pid of the <em>prog...</em> process. </li> + <li> 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. </li> + <li> When <em>prog...</em> exits, <tt>trap</tt> exits with an +<a href="exitcodes.html">approximation</a> of the same exit code. </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-x</tt> : forward signals. If this option is given, +any signal that <tt>trap</tt> receives and that is not explicitly +trapped will be sent to <em>prog</em>. By default, <tt>trap</tt> does +not forward any signals, and does not ignore them either - for instance a +SIGTERM, unless caught by a <tt>SIGTERM</tt> directive, will kill the +<tt>trap</tt> process (and leave <em>prog</em> running). With the +<tt>-x</tt> option, without a <tt>SIGTERM</tt> directive, a SIGTERM +will be still be caught by <tt>trap</tt>, that will send it to +<em>prog</em>. </li> + <li> <tt>-t <em>millisecs</em></tt> : if a <tt>timeout</tt> +directive exists, the corresponding <em>progtimeout...</em> will be run +every time <em>millisecs</em> milliseconds elapse without <tt>trap</tt> +receiving a signal. By default, <em>millisecs</em> is 0, which means +infinite (i.e. a <tt>timeout</tt> directive will never trigger). </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> Programs defined in command line directives can start with +<tt><a href="import.html">import</a> !</tt> to retrieve the pid of +<em>prog</em> in <tt>${!}</tt> </li> + <li> <tt>trap</tt> 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 +<tt>trap</tt> program in execline scripts. </li> +</ul> + +</body> +</html> |