summaryrefslogtreecommitdiff
path: root/doc/fdreserve.html
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2014-09-18 20:03:23 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2014-09-18 20:03:23 +0000
commitf316a2ed52195135a35e32d7096e876357c48c69 (patch)
tree5f4486b9a5a213a69e66ef574d6bc643a207981c /doc/fdreserve.html
downloadexecline-f316a2ed52195135a35e32d7096e876357c48c69.tar.xz
initial commit: rc for execline-2.0.0.0
Diffstat (limited to 'doc/fdreserve.html')
-rw-r--r--doc/fdreserve.html92
1 files changed, 92 insertions, 0 deletions
diff --git a/doc/fdreserve.html b/doc/fdreserve.html
new file mode 100644
index 0000000..ef047dc
--- /dev/null
+++ b/doc/fdreserve.html
@@ -0,0 +1,92 @@
+<html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>execline: the fdreserve program</title>
+ <meta name="Description" content="execline: the fdreserve program" />
+ <meta name="Keywords" content="execline command fdreserve file descriptor" />
+ <!-- <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>fdreserve</tt> program </h1>
+
+<p>
+<tt>fdreserve</tt> updates the environment with file descriptors that
+are guaranteed safe to use, then executes a program.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+ fdreserve <em>n</em> <em>prog...</em>
+</pre>
+
+<ul>
+ <li> <tt>fdreserve</tt> tries to reserve <em>n</em> file descriptors. </li>
+ <li> <tt>fdreserve</tt> sets the <tt>FD0</tt>, <tt>FD1</tt>, ...,
+<tt>FD<em>n-1</em></tt> environment variables: each FD<em>i</em> contains a
+valid file descriptor, that can be safely opened. </li>
+ <li> <tt>fdreserve</tt> then execs into <em>prog</em> with its arguments.
+</ul>
+
+<h2> Common use </h2>
+
+<p>
+<tt>fdreserve</tt> can be used when you do not want to hardcode file
+descriptors in your scripts. For instance, to create a pipe, you could
+use:
+</p>
+
+<pre>
+ #!/command/execlineb
+ fdreserve 2
+ multisubstitute
+ {
+ importas fdr FD0
+ importas fdw FD1
+ }
+ piperw $fdr $fdw
+ <em>prog...</em>
+</pre>
+
+<p>
+ Warning: <tt>fdreserve</tt> does not allocate descriptors, it merely returns
+descriptors that are free at the time it is run. A program like
+</p>
+
+<pre>
+ #!/command/execlineb
+ fdreserve 3
+ multisubstitute
+ {
+ importas fdr FD0
+ importas fdw FD1
+ }
+ piperw $fdr $fdw
+ fdreserve 1
+ multisubstitute
+ {
+ importas oldfd FD2
+ importas newfd FD0
+ }
+ <em>prog...</em>
+</pre>
+
+<p>
+may fail, because <em>oldfd</em> and <em>newfd</em> may be the same.
+To avoid that, you should make sure that all descriptors returned by
+<tt>fdreserve</tt> are actually allocated before calling <tt>fdreserve</tt>
+again.
+(Thanks to <a href="http://code.dogmap.org/">Paul Jarc</a> for having
+spotted that case.)
+</p>
+
+</body>
+</html>