lib/libstdbuf/libstdbuf.3

   1 .\" Copyright (c) 2012 Jeremie Le Hen <jlh@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code and documentation must retain the above
   8 .\"    copyright notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd April 28, 2012
  28 .Dt LIBSTDBUF 3
  29 .Os
  30 .Sh NAME
  31 .Nm libstdbuf
  32 .Nd preloaded library to change standard streams initial buffering
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 library is meant to be preloaded with the
  37 .Ev LD_PRELOAD
  38 environment variable to as to change the initial buffering
  39 of standard input, standard output and standard error streams.
  40 .Pp
  41 Although you may load and configure this library manually,
  42 an utility,
  43 .Xr stdbuf 1 ,
  44 can be used to run a command with the appropriate environment variables.
  45 .Sh ENVIRONMENT
  46 Each stream can be configured independently through the following
  47 environment variables (values are defined below):
  48 .Bl -tag -width size -offset indent
  49 .It Ev _STDBUF_I
  50 Initial buffering definition for the standard input stream
  51 .It Ev _STDBUF_O
  52 Initial buffering definition for the standard output stream
  53 .It Ev _STDBUF_E
  54 Initial buffering definition for the standard error stream
  55 .El
  56 .Pp
  57 Each variable may take one of the following values:
  58 .Bl -tag -width size -offset indent
  59 .It Qq 0
  60 unbuffered
  61 .It Qq L
  62 line buffered
  63 .It Qq B
  64 fully buffered with the default buffer size
  65 .It Ar size
  66 fully buffered with a buffer of
  67 .Ar size
  68 bytes (suffixes 'k', 'M' and 'G' are accepted)
  69 .El
  70 .Sh EXAMPLE
  71 In the following example, the stdout stream of the
  72 .Xr awk 1
  73 command
  74 will be fully buffered by default because it does not refer
  75 to a terminal.
  76 .Nm
  77 is used to force it to be line-buffered so
  78 .Xr vmstat 8 Ns 's
  79 output will not stall until the full buffer fills.
  80 .Bd -literal -offset indent
  81 # vmstat 1 | LD_PRELOAD=/usr/lib/libstdbuf.so \\
  82     STDBUF_1=L awk '$2 > 1 || $3 > 1' | cat -n
  83 .Ed
  84 .Pp
  85 See also the manpage of
  86 .Xr stdbuf 1
  87 for a simpler way to do this.
  88 .Sh HISTORY
  89 The
  90 .Nm
  91 library first appeared in
  92 .Fx 8.4 .
  93 .Sh AUTHORS
  94 .An -nosplit
  95 The original idea of the
  96 .Nm
  97 command comes from
  98 .An Padraig Brady
  99 who implemented it in the GNU coreutils.
 100 .An Jeremie Le Hen
 101 implemented it on
 102 .Fx .