diff options
Diffstat (limited to 'doc/redirfd.html')
| -rw-r--r-- | doc/redirfd.html | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/doc/redirfd.html b/doc/redirfd.html new file mode 100644 index 0000000..fd29ef4 --- /dev/null +++ b/doc/redirfd.html @@ -0,0 +1,100 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>execline: the redirfd command</title> + <meta name="Description" content="execline: the redirfd command" /> + <meta name="Keywords" content="execline command redirfd" /> + <!-- <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>redirfd</tt> program </h1> + +<p> +<tt>redirfd</tt> redirects a given file descriptor to a file, then +executes a program. +</p> + +<h2> Interface </h2> + +<pre> + redirfd [ -r | -w | -u | -a | -c | -x ] [ -n | -b ] <em>fd</em> <em>file</em> <em>prog...</em> +</pre> + +<p> +<tt>redirfd</tt> redirects the file descriptor number <em>fd</em> +to <em>file</em>, then execs into <em>prog...</em>. +</p> + +<h2> Options </h2> + +<p> + One and only one of the -r, -w, -u, -a, -c, or -x options must be given; +the -n and -b options may be added in any case. +</p> + +<ul> + <li> <tt>-r</tt> : open <em>file</em> for reading. </li> + <li> <tt>-w</tt> : open <em>file</em> for writing, truncating it if it already exists. </li> + <li> <tt>-u</tt> : open <em>file</em> for reading and writing. </li> + <li> <tt>-a</tt> : open <em>file</em> for appending, creating it if it doesn't exist. </li> + <li> <tt>-c</tt> : open <em>file</em> for appending. Do not create it if it doesn't exist. </li> + <li> <tt>-x</tt> : open <em>file</em> for writing, creating it, failing if it already exists. </li> + <li> <tt>-n</tt> : open <em>file</em> in non-blocking mode. </li> + <li> <tt>-b</tt> : change mode of <em>file</em> after opening it: +to non-blocking mode if the <tt>-n</tt> option was not given, +to blocking mode if it was. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> <tt>redirfd -r <em>n</em> <em>file</em> prog...</tt> is roughly equivalent to +<tt>sh -c 'exec prog... <em>n</em><<em>file</em>'</tt></li> + <li> <tt>redirfd -w <em>n</em> <em>file</em> prog...</tt> is roughly equivalent to +<tt>sh -c 'exec prog... <em>n</em>><em>file</em>'</tt></li> + <li> <tt>redirfd -u <em>n</em> <em>file</em> prog...</tt> is roughly equivalent to +<tt>sh -c 'exec prog... <em>n</em><><em>file</em>'</tt></li> + <li> <tt>redirfd -a <em>n</em> <em>file</em> prog...</tt> is roughly equivalent to +<tt>sh -c 'exec prog... <em>n</em>>><em>file</em>'</tt></li> + <li> <tt>redirfd -c <em>n</em> <em>file</em> prog...</tt> has no portable +shell equivalent. Some shells provide the <em>noclobber</em> option for +a similar feature. </li> + <li> <tt>redirfd -x <em>n</em> <em>file</em> prog...</tt> has no portable +shell equivalent.</tt> </li> +</ul> + +<h2> Special fifo handling </h2> + +<p> + The <tt>-n</tt> and <tt>-b</tt> options are especially useful with +named pipes. +</p> + +<ul> + <li> Opening a fifo for reading, blocking if there is no writer: +<tt>redirfd -r <em>n</em> <em>fifo</em> prog...</tt></li> + <li> Opening a fifo for reading, with instant success even if +there is no writer, and blocking at the first attempt to read from it: +<tt>redirfd -r -nb <em>n</em> <em>fifo</em> prog...</tt></li> + <li> Opening a fifo for writing, blocking if there is no reader: +<tt>redirfd -w <em>n</em> <em>fifo</em> prog...</tt></li> + <li> Opening a fifo for writing, with instant success even if +there is no reader: +<tt>redirfd -w -nb <em>n</em> <em>fifo</em> prog...</tt>. Warning: +the first attempt to write to the fifo will raise a SIGPIPE if there is +still no reader at that time. The named pipe semantics normally do not +allow a fifo to be open for writing without a reading end, and you +should know what you are doing if you're using <tt>redirfd</tt> +this way. </li> +</ul> + +</body> +</html> |