dacb460d |
1 | \cfg{man-identity}{reservoir}{1}{2005-05-13}{Simon Tatham}{Simon Tatham} |
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 | |
11 | \c reservoir [ -o filename ] |
12 | \e bbbbbbbbb bb iiiiiiii |
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 | |
25 | \dt \cw{-o} \e{filename} |
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 | |
31 | \U EXAMPLES |
32 | |
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. |
39 | |
40 | For example: |
41 | |
42 | \c $ tr a-zA-Z n-za-mN-ZA-M |
43 | \e bbbbbbbbbbbbbbbbbbbbbb |
44 | \c Hello, world. |
45 | \e bbbbbbbbbbbbb |
46 | \c Uryyb, jbeyq. |
47 | \c This is a test. |
48 | \e bbbbbbbbbbbbbbb |
49 | \c Guvf vf n grfg. |
50 | |
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 |
55 | eventually. |
56 | |
57 | You can solve this using \cw{reservoir}: |
58 | |
59 | \c $ tr a-zA-Z n-za-mN-ZA-M | reservoir |
60 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
61 | \c Hello, world. |
62 | \e bbbbbbbbbbbbb |
63 | \c This is a test. |
64 | \e bbbbbbbbbbbbbbb |
65 | \c (now the user presses ^D) |
66 | \e iiiiiiiiiiiiiiiiiiiiiiiii |
67 | \c Uryyb, jbeyq. |
68 | \c Guvf vf n grfg. |
69 | |
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 |
72 | |
73 | \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt > temp.txt |
74 | |
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 |
78 | all been read. |
79 | |
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}: |
85 | |
86 | \c $ tr a-zA-Z n-za-mN-ZA-M < temp.txt | reservoir -o temp.txt |
87 | |
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. |
90 | |
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.) |
96 | |
f46b27c8 |
97 | Another use for \cw{-o} is for requesting a list of files using |
98 | \c{find}(1) or \c{ls}(1), without the output file appearing in the |
99 | list: |
100 | |
101 | \c $ find . -type f | reservoir -o filelist |
102 | |
dacb460d |
103 | \U LICENCE |
104 | |
105 | \cw{reservoir} is free software, distributed under the MIT licence. Type |
106 | \cw{reservoir --licence} to see the full licence text. |
107 | |
108 | \versionid $Id$ |