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 | |
| parent | 820a98c94c134745b1da83d10b648e6c8f83791e (diff) | |
| download | execline-2.1.2.0.tar.xz | |
- add trapv2.1.2.0
- rc for 2.1.2.0
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 5 | ||||
| -rw-r--r-- | doc/trap.html | 98 | ||||
| -rw-r--r-- | doc/upgrade.html | 7 |
3 files changed, 108 insertions, 2 deletions
diff --git a/doc/index.html b/doc/index.html index dda1445..5fb4b3c 100644 --- a/doc/index.html +++ b/doc/index.html @@ -51,7 +51,7 @@ shell's syntax, and has no security issues. <li> GNU make, version 4.0 or later. Please be aware that execline will not build with an earlier version. </li> <li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> version -2.3.3.0 or later. It's a build-time requirement. It's also a run-time +2.3.4.0 or later. It's a build-time requirement. It's also a run-time requirement if you link against the shared version of the skalibs library. </li> </ul> @@ -66,7 +66,7 @@ library. </li> <h3> Download </h3> <ul> - <li> The current released version of execline is <a href="execline-2.1.1.1.tar.gz">2.1.1.1</a>. </li> + <li> The current released version of execline is <a href="execline-2.1.2.0.tar.gz">2.1.2.0</a>. </li> <li> Alternatively, you can checkout a copy of the execline git repository: <pre> git clone git://git.skarnet.org/execline </pre> </li> </ul> @@ -136,6 +136,7 @@ to your installation: the shebang lines for your system might be something like <li><a href="exec.html">The <tt>exec</tt> program</a></li> <li><a href="tryexec.html">The <tt>tryexec</tt> program</a></li> <li><a href="exit.html">The <tt>exit</tt> program</a></li> +<li><a href="trap.html">The <tt>trap</tt> program</a></li> </ul> <p> (<a href="el_semicolon.html">Basic block management</a>) 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> diff --git a/doc/upgrade.html b/doc/upgrade.html index 121b210..ff1d40d 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -17,6 +17,13 @@ <h1> What has changed in execline </h1> +<h2> in 2.1.2.0 </h2> + +<ul> + <li> skalibs dependency bumped to 2.3.4.0 </li> + <li> new command: <a href="trap.html">trap</a> </li> +</ul> + <h2> in 2.1.1.1 </h2> <ul> |