mdw@git.distorted.org.uk Git - sgt/utils/blob - reservoir/reservoir.but

   1 \cfg{man-identity}{reservoir}{1}{2008-03-22}{Simon Tatham}{Simon Tatham}
   2
   3 \define{dash} \u2013{-}
   4
   5 \title Man page for \cw{reservoir}
   6
   7 \U NAME
   8
   9 \cw{reservoir} \dash delay stage in a pipeline
  10
  11 \U SYNOPSIS
  12
  13 \c reservoir [ -o filename | -O filename ]
  14 \e bbbbbbbbb   bb iiiiiiii   bb iiiiiiii
  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
  27 \dt \cw{-O} \e{filename}
  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
  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
  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
 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.)
 109
 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
 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$