diff options
Diffstat (limited to 'lib/libstdbuf/libstdbuf.3')
-rw-r--r-- | lib/libstdbuf/libstdbuf.3 | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/lib/libstdbuf/libstdbuf.3 b/lib/libstdbuf/libstdbuf.3 new file mode 100644 index 0000000..c60ffd7 --- /dev/null +++ b/lib/libstdbuf/libstdbuf.3 @@ -0,0 +1,102 @@ +.\" Copyright (c) 2012 Jeremie Le Hen <jlh@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code and documentation must retain the above +.\" copyright notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 28, 2012 +.Dt LIBSTDBUF 3 +.Os +.Sh NAME +.Nm libstdbuf +.Nd preloaded library to change standard streams initial buffering +.Sh DESCRIPTION +The +.Nm +library is meant to be preloaded with the +.Ev LD_PRELOAD +environment variable to as to change the initial buffering +of standard input, standard output and standard error streams. +.Pp +Although you may load and configure this library manually, +an utility, +.Xr stdbuf 1 , +can be used to run a command with the appropriate environment variables. +.Sh ENVIRONMENT +Each stream can be configured indepentently through the following +environment variables (values are defined below): +.Bl -tag -width size -offset indent +.It Ev _STDBUF_I +Initial buffering definition for the standard input stream +.It Ev _STDBUF_O +Initial buffering definition for the standard output stream +.It Ev _STDBUF_E +Initial buffering definition for the standard error stream +.El +.Pp +Each variable may take one of the following values: +.Bl -tag -width size -offset indent +.It Qq 0 +unbuffered +.It Qq L +line buffered +.It Qq B +fully buffered with the default buffer size +.It Ar size +fully buffered with a buffer of +.Ar size +bytes (suffixes 'k', 'M' and 'G' are accepted) +.El +.Sh EXAMPLE +In the following example, the stdout stream of the +.Xr awk 1 +command +will be fully buffered by default because it does not refer +to a terminal. +.Nm +is used to force it to be line-buffered so +.Xr vmstat 8 Ns 's +output will not stall until the full buffer fills. +.Bd -literal -offset indent +# vmstat 1 | LD_PRELOAD=/usr/lib/libstdbuf.so \\ + STDBUF_1=L awk '$2 > 1 || $3 > 1' | cat -n +.Ed +.Pp +See also the manpage of +.Xr stdbuf 1 +for a simpler way to do this. +.Sh HISTORY +The +.Nm +library first appeared in +.Fx 8.4 . +.Sh AUTHORS +.An -nosplit +The original idea of the +.Nm +command comes from +.An Padraig Brady +who implemented it in the GNU coreutils. +.An Jeremie Le Hen +implemented it on +.Fx . |