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 .Dd June 29, 2023
  26 .Dt LIBSTDBUF 3
  27 .Os
  28 .Sh NAME
  29 .Nm libstdbuf
  30 .Nd preloaded library to change standard streams initial buffering
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 library is meant to be preloaded with the
  35 .Ev LD_PRELOAD
  36 environment variable to as to change the initial buffering
  37 of standard input, standard output and standard error streams.
  38 .Pp
  39 Although you may load and configure this library manually,
  40 an utility,
  41 .Xr stdbuf 1 ,
  42 can be used to run a command with the appropriate environment variables.
  43 .Sh ENVIRONMENT
  44 Each stream can be configured independently through the following
  45 environment variables (values are defined below):
  46 .Bl -tag -width size -offset indent
  47 .It Ev _STDBUF_I
  48 Initial buffering definition for the standard input stream
  49 .It Ev _STDBUF_O
  50 Initial buffering definition for the standard output stream
  51 .It Ev _STDBUF_E
  52 Initial buffering definition for the standard error stream
  53 .El
  54 .Pp
  55 Each variable may take one of the following values:
  56 .Bl -tag -width size -offset indent
  57 .It Qq 0
  58 unbuffered
  59 .It Qq L
  60 line buffered
  61 .It Qq B
  62 fully buffered with the default buffer size
  63 .It Ar size
  64 fully buffered with a buffer of
  65 .Ar size
  66 bytes (suffixes 'k', 'M' and 'G' are accepted)
  67 .El
  68 .Sh EXAMPLE
  69 In the following example, the stdout stream of the
  70 .Xr awk 1
  71 command
  72 will be fully buffered by default because it does not refer
  73 to a terminal.
  74 .Nm
  75 is used to force it to be line-buffered so
  76 .Xr vmstat 8 Ns 's
  77 output will not stall until the full buffer fills.
  78 .Bd -literal -offset indent
  79 # vmstat 1 | LD_PRELOAD=/usr/lib/libstdbuf.so \\
  80     STDBUF_1=L awk '$2 > 1 || $3 > 1' | cat -n
  81 .Ed
  82 .Pp
  83 See
  84 .Xr stdbuf 1
  85 for a simpler way to do this.
  86 .Sh SEE ALSO
  87 .Xr rtld 1 ,
  88 .Xr stdbuf 1
  89 .Sh HISTORY
  90 The
  91 .Nm
  92 library first appeared in
  93 .Fx 8.4 .
  94 .Sh AUTHORS
  95 .An -nosplit
  96 The original idea of the
  97 .Nm
  98 command comes from
  99 .An Padraig Brady
 100 who implemented it in the GNU coreutils.
 101 .An Jeremie Le Hen
 102 implemented it on
 103 .Fx .