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

   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
  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
 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$