775a5112 |
1 | \cfg{man-identity}{reservoir}{1}{2008-03-22}{Simon Tatham}{Simon Tatham} |
dacb460d |
2 | |
3 | \title Man page for \cw{reservoir} |
4 | |
5 | \U NAME |
6 | |
7 | \cw{reservoir} - delay stage in a pipeline |
8 | |
9 | \U SYNOPSIS |
10 | |
775a5112 |
11 | \c reservoir [ -o filename | -O filename ] |
12 | \e bbbbbbbbb bb iiiiiiii bb iiiiiiii |
dacb460d |
13 | |
14 | \U DESCRIPTION |
15 | |
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 |
18 | standard output. |
19 | |
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. |
22 | |
23 | \U OPTIONS |
24 | |
775a5112 |
25 | \dt \cw{-O} \e{filename} |
dacb460d |
26 | |
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. |
30 | |
775a5112 |
31 | \dt \cw{-o} \e{filename} |
32 | |
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 |
37 | be overwritten. |
38 | |
dacb460d |
39 | \U EXAMPLES |
40 | |
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. |
47 | |
48 | For example: |
49 | |
50 | \c $ tr a-zA-Z n-za-mN-ZA-M |
51 | \e bbbbbbbbbbbbbbbbbbbbbb |
52 | \c Hello, world. |
53 | \e bbbbbbbbbbbbb |
54 | \c Uryyb, jbeyq. |
55 | \c This is a test. |
56 | \e bbbbbbbbbbbbbbb |
57 | \c Guvf vf n grfg. |
58 | |
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 |
63 | eventually. |
64 | |
65 | You can solve this using \cw{reservoir}: |
66 | |
67 | \c $ tr a-zA-Z n-za-mN-ZA-M | reservoir |
68 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
69 | \c Hello, world. |
70 | \e bbbbbbbbbbbbb |
71 | \c This is a test. |
72 | \e bbbbbbbbbbbbbbb |
73 | \c (now the user presses ^D) |
74 | \e iiiiiiiiiiiiiiiiiiiiiiiii |
75 | \c Uryyb, jbeyq. |
76 | \c Guvf vf n grfg. |
77 | |
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 |
80 | |
81 | \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt > temp.txt |
82 | |
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 |
86 | all been read. |
87 | |
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}: |
93 | |
94 | \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt | reservoir -o temp.txt |
95 | |
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. |
98 | |
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 |
775a5112 |
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.) |
dacb460d |
107 | |
f46b27c8 |
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 |
110 | list: |
111 | |
112 | \c $ find . -type f | reservoir -o filelist |
113 | |
dacb460d |
114 | \U LICENCE |
115 | |
116 | \cw{reservoir} is free software, distributed under the MIT licence. Type |
117 | \cw{reservoir --licence} to see the full licence text. |
118 | |
119 | \versionid $Id$ |