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 |
19 | it sees end-of-file, then to write everything it has seen to its |
20 | standard output. |
21 | |
22 | It behaves exactly like \cw{cat} with no arguments, except that it |
23 | writes 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 |
30 | standard 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 |
36 | output at all to be written, \cw{reservoir} will not open the output |
37 | file for writing at all. Hence, if the process which is supposed to |
38 | generate the output completely fails to run, \e{filename} will not |
39 | be overwritten. |
40 | |
dacb460d |
41 | \U EXAMPLES |
42 | |
43 | If you have a program which filters its input in some way (for |
44 | example, a base-64 decoder, or a \cw{tr}(1) command performing |
45 | rot13), and you wish to copy a small amount of data into that |
46 | program using a terminal emulator's paste function, it can be |
47 | inconvenient to have the output interspersed with the echoed input |
48 | so that you cannot select and copy the output as a whole. |
49 | |
50 | For 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 | |
61 | If your terminal emulator pastes the text line by line, then to copy |
62 | the transformed output requires you to separately select each line |
63 | of the output. If the terminal pastes in larger chunks, you may not |
64 | see the problem quite so quickly, but it will still appear |
65 | eventually. |
66 | |
67 | You 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 | |
80 | A common reason why you might want to buffer data in a pipeline is |
81 | in 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 | |
85 | because the output redirection will destroy the contents of the file |
86 | before its original contents can be read. \cw{reservoir} can help, |
87 | because it does not begin writing output until after the input has |
88 | all been read. |
89 | |
90 | You still cannot use output redirection, because the presence of the |
91 | \cw{>} operator on your command line will cause the output file to |
92 | be truncated to zero length \e{before} running \cw{reservoir}, so |
93 | there is nothing \cw{reservoir} can do about this. Instead, you can |
94 | use 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 | |
98 | Now \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 |
102 | something goes wrong half way through writing the output, part of |
775a5112 |
103 | your data will be lost, although the default behaviour of \cw{-o} |
104 | will at least avoid overwriting the file if something goes wrong |
105 | \e{before} the output begins to be written. Also, the file is not |
106 | replaced atomically. This method is very convenient in non-critical |
107 | situations, such as when the target file is backed up in source |
108 | control, but is not recommended for critical or automated use.) |
dacb460d |
109 | |
f46b27c8 |
110 | Another 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 |
112 | list: |
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$ |