1 \cfg{man-identity}{reservoir}{1}{2005-05-13}{Simon Tatham}{Simon Tatham}
3 \title Man page for \cw{reservoir}
7 \cw{reservoir} - delay stage in a pipeline
11 \c reservoir [ -o filename ]
12 \e bbbbbbbbb 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.
33 If you have a program which filters its input in some way (for
34 example, a base-64 decoder, or a \cw{tr}(1) command performing
35 rot13), and you wish to copy a small amount of data into that
36 program using a terminal emulator's paste function, it can be
37 inconvenient to have the output interspersed with the echoed input
38 so that you cannot select and copy the output as a whole.
42 \c $ tr a-zA-Z n-za-mN-ZA-M
43 \e bbbbbbbbbbbbbbbbbbbbbb
51 If your terminal emulator pastes the text line by line, then to copy
52 the transformed output requires you to separately select each line
53 of the output. If the terminal pastes in larger chunks, you may not
54 see the problem quite so quickly, but it will still appear
57 You can solve this using \cw{reservoir}:
59 \c $ tr a-zA-Z n-za-mN-ZA-M | reservoir
60 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
65 \c (now the user presses ^D)
66 \e iiiiiiiiiiiiiiiiiiiiiiiii
70 A common reason why you might want to buffer data in a pipeline is
71 in order to transform a file in place. For example, you cannot write
73 \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt > temp.txt
75 because the output redirection will destroy the contents of the file
76 before its original contents can be read. \cw{reservoir} can help,
77 because it does not begin writing output until after the input has
80 You still cannot use output redirection, because the presence of the
81 \cw{>} operator on your command line will cause the output file to
82 be truncated to zero length \e{before} running \cw{reservoir}, so
83 there is nothing \cw{reservoir} can do about this. Instead, you can
84 use the \cw{-o} option provided by \cw{reservoir}:
86 \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt | reservoir -o temp.txt
88 Now \cw{reservoir} will not open \cw{temp.txt} for output until
89 \e{after} the rest of the pipeline has finished reading data from it.
91 (This is not a reliable means of editing files in place. If
92 something goes wrong half way through writing the output, part of
93 your data will be lost. Also, the file is not replaced atomically.
94 This method is very convenient in non-critical situations, but is
95 not recommended for critical or automated use.)
99 \cw{reservoir} is free software, distributed under the MIT licence. Type
100 \cw{reservoir --licence} to see the full licence text.