1 \cfg{man-identity}{reservoir}{1}{2008-03-22}{Simon Tatham}{Simon Tatham}
3 \title Man page for \cw{reservoir}
7 \cw{reservoir} - delay stage in a pipeline
11 \c reservoir [ -o filename | -O filename ]
12 \e bbbbbbbbb bb iiiiiiii bb iiiiiiii
16 \cw{reservoir}'s function is to read from its standard input until
17 it sees end-of-file, then to write everything it has seen to its
20 It behaves exactly like \cw{cat} with no arguments, except that it
21 writes none of its outgoing data until all of its input has arrived.
25 \dt \cw{-O} \e{filename}
27 \dd Causes the output to be written to \e{filename} rather than to
28 standard output. \e{filename} is not opened until after
29 \cw{reservoir} detects end of file on its input.
31 \dt \cw{-o} \e{filename}
33 \dd Exactly like \cw{-O}, but with one special case: if there is no
34 output at all to be written, \cw{reservoir} will not open the output
35 file for writing at all. Hence, if the process which is supposed to
36 generate the output completely fails to run, \e{filename} will not
41 If you have a program which filters its input in some way (for
42 example, a base-64 decoder, or a \cw{tr}(1) command performing
43 rot13), and you wish to copy a small amount of data into that
44 program using a terminal emulator's paste function, it can be
45 inconvenient to have the output interspersed with the echoed input
46 so that you cannot select and copy the output as a whole.
50 \c $ tr a-zA-Z n-za-mN-ZA-M
51 \e bbbbbbbbbbbbbbbbbbbbbb
59 If your terminal emulator pastes the text line by line, then to copy
60 the transformed output requires you to separately select each line
61 of the output. If the terminal pastes in larger chunks, you may not
62 see the problem quite so quickly, but it will still appear
65 You can solve this using \cw{reservoir}:
67 \c $ tr a-zA-Z n-za-mN-ZA-M | reservoir
68 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
73 \c (now the user presses ^D)
74 \e iiiiiiiiiiiiiiiiiiiiiiiii
78 A common reason why you might want to buffer data in a pipeline is
79 in order to transform a file in place. For example, you cannot write
81 \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt > temp.txt
83 because the output redirection will destroy the contents of the file
84 before its original contents can be read. \cw{reservoir} can help,
85 because it does not begin writing output until after the input has
88 You still cannot use output redirection, because the presence of the
89 \cw{>} operator on your command line will cause the output file to
90 be truncated to zero length \e{before} running \cw{reservoir}, so
91 there is nothing \cw{reservoir} can do about this. Instead, you can
92 use the \cw{-o} option provided by \cw{reservoir}:
94 \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt | reservoir -o temp.txt
96 Now \cw{reservoir} will not open \cw{temp.txt} for output until
97 \e{after} the rest of the pipeline has finished reading data from it.
99 (This is not a reliable means of editing files in place. If
100 something goes wrong half way through writing the output, part of
101 your data will be lost, although the default behaviour of \cw{-o}
102 will at least avoid overwriting the file if something goes wrong
103 \e{before} the output begins to be written. Also, the file is not
104 replaced atomically. This method is very convenient in non-critical
105 situations, such as when the target file is backed up in source
106 control, but is not recommended for critical or automated use.)
108 Another use for \cw{-o} is for requesting a list of files using
109 \c{find}(1) or \c{ls}(1), without the output file appearing in the
112 \c $ find . -type f | reservoir -o filelist
116 \cw{reservoir} is free software, distributed under the MIT licence. Type
117 \cw{reservoir --licence} to see the full licence text.