Import my usual \dash macro into all these man pages, and use it for
[sgt/utils] / reservoir / reservoir.but
CommitLineData
775a5112 1\cfg{man-identity}{reservoir}{1}{2008-03-22}{Simon Tatham}{Simon Tatham}
dacb460d 2
92dccb8d 3\define{dash} \u2013{-}
4
dacb460d 5\title Man page for \cw{reservoir}
6
7\U NAME
8
92dccb8d 9\cw{reservoir} \dash delay stage in a pipeline
dacb460d 10
11\U SYNOPSIS
12
775a5112 13\c reservoir [ -o filename | -O filename ]
14\e bbbbbbbbb bb iiiiiiii bb iiiiiiii
dacb460d 15
16\U DESCRIPTION
17
18\cw{reservoir}'s function is to read from its standard input until
19it sees end-of-file, then to write everything it has seen to its
20standard output.
21
22It behaves exactly like \cw{cat} with no arguments, except that it
23writes none of its outgoing data until all of its input has arrived.
24
25\U OPTIONS
26
775a5112 27\dt \cw{-O} \e{filename}
dacb460d 28
29\dd Causes the output to be written to \e{filename} rather than to
30standard output. \e{filename} is not opened until after
31\cw{reservoir} detects end of file on its input.
32
775a5112 33\dt \cw{-o} \e{filename}
34
35\dd Exactly like \cw{-O}, but with one special case: if there is no
36output at all to be written, \cw{reservoir} will not open the output
37file for writing at all. Hence, if the process which is supposed to
38generate the output completely fails to run, \e{filename} will not
39be overwritten.
40
dacb460d 41\U EXAMPLES
42
43If you have a program which filters its input in some way (for
44example, a base-64 decoder, or a \cw{tr}(1) command performing
45rot13), and you wish to copy a small amount of data into that
46program using a terminal emulator's paste function, it can be
47inconvenient to have the output interspersed with the echoed input
48so that you cannot select and copy the output as a whole.
49
50For example:
51
52\c $ tr a-zA-Z n-za-mN-ZA-M
53\e bbbbbbbbbbbbbbbbbbbbbb
54\c Hello, world.
55\e bbbbbbbbbbbbb
56\c Uryyb, jbeyq.
57\c This is a test.
58\e bbbbbbbbbbbbbbb
59\c Guvf vf n grfg.
60
61If your terminal emulator pastes the text line by line, then to copy
62the transformed output requires you to separately select each line
63of the output. If the terminal pastes in larger chunks, you may not
64see the problem quite so quickly, but it will still appear
65eventually.
66
67You can solve this using \cw{reservoir}:
68
69\c $ tr a-zA-Z n-za-mN-ZA-M | reservoir
70\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
71\c Hello, world.
72\e bbbbbbbbbbbbb
73\c This is a test.
74\e bbbbbbbbbbbbbbb
75\c (now the user presses ^D)
76\e iiiiiiiiiiiiiiiiiiiiiiiii
77\c Uryyb, jbeyq.
78\c Guvf vf n grfg.
79
80A common reason why you might want to buffer data in a pipeline is
81in order to transform a file in place. For example, you cannot write
82
83\c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt > temp.txt
84
85because the output redirection will destroy the contents of the file
86before its original contents can be read. \cw{reservoir} can help,
87because it does not begin writing output until after the input has
88all been read.
89
90You still cannot use output redirection, because the presence of the
91\cw{>} operator on your command line will cause the output file to
92be truncated to zero length \e{before} running \cw{reservoir}, so
93there is nothing \cw{reservoir} can do about this. Instead, you can
94use the \cw{-o} option provided by \cw{reservoir}:
95
96\c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt | reservoir -o temp.txt
97
98Now \cw{reservoir} will not open \cw{temp.txt} for output until
99\e{after} the rest of the pipeline has finished reading data from it.
100
101(This is not a reliable means of editing files in place. If
102something goes wrong half way through writing the output, part of
775a5112 103your data will be lost, although the default behaviour of \cw{-o}
104will at least avoid overwriting the file if something goes wrong
105\e{before} the output begins to be written. Also, the file is not
106replaced atomically. This method is very convenient in non-critical
107situations, such as when the target file is backed up in source
108control, but is not recommended for critical or automated use.)
dacb460d 109
f46b27c8 110Another use for \cw{-o} is for requesting a list of files using
111\c{find}(1) or \c{ls}(1), without the output file appearing in the
112list:
113
114\c $ find . -type f | reservoir -o filelist
115
dacb460d 116\U LICENCE
117
118\cw{reservoir} is free software, distributed under the MIT licence. Type
119\cw{reservoir --licence} to see the full licence text.
120
121\versionid $Id$