.\" $Id: tmbuf.man,v 1.9 2012/07/06 20:21:32 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f |${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/tmbuf.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/tmbuf.1*
.TH TMBUF 1 LOCAL
.SH NAME
tmbuf - timed data slicer
.SH SYNOPSIS
.ds PN "tmbuf
\fI\*(PN\fP [\fB\-e\fP] [\-\fIseconds\fP] [\fB\-t\fP\~\fIseconds\fP]
.br
\fI\*(PN\fP \fB\-h\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
.B Tmbuf
program accepts input on stdin that might be coming out in
``spurts''.  The output might be from a monitoring program, or from
some real time data collector.  The program captures a time based
slice of data from the input then flushes it to the output and
exists.
.P
Because standard UNIX utilities _buffer_ data very well,
when we need to filter a stream, say with grep, as in:
.RS
collect_data | grep \-v "hack_this_out" | control_expr
.RE

what we find is that \fBgrep\fP(1) will buffer lots of data.  It will
in fact buffer until enough "good" data has come in to flush its
output buffer.
.P
So if you get a good "control event" as the first input line you
might not see it until after a few hundred control events make it
through the pipeline.  By that time it is way too late.
.P
If we re-code that as
.RS
.nf
collect_data | while tmbuf >slice ; do
	grep \-v "hack_this_out" <slice | control_expr
done
.fi
.RE
then the process works to feed back in near real time.  Tune the
tmbuf options for the delay you need.  (Because we've force grep to
do a small window, not wait for more input.)

.SH OPTIONS
If the program is called as \fI\*(PN\fP then no options are forced.
.TP
\fB\-\fIseconds\fP
Time to stall between lines (default 5 seconds).
As long as lines flow within \fIseconds\fP seconds of each other
\fBtmbuf\fP passes them through.
.TP
\fB\-e\fP
Exit nonzero at EOF, even if some input was processed.
.TP
\fB\-h\fP
Print this help message.
.TP
\fB\-t\fP \fIseconds\fP
Total time to delay after first read (default forever).
Even though lines are still coming we have to stop processing after
\fIseconds\fP.
.TP
\fB\-V\fP
Show version information.

.SH EXAMPLES
.TP
tail \-0f status | \fBtmbuf\fP \-t 30 | Mail \-s "found" ksb
When the file status gets some lines appened mail ksb with the
subject ``found'', only wait 30 seconds before sending the mail
after the first line appears.

.TP
conserver \-v | pager.ksh
The pager script uses \fBtmbuf\fP internally to slice the
output of the console server.

.TP
.nf
\fBtmbuf\fP \-V
.fi
Output the standard version banner.
.SH BUGS
There should be an initial timeout, but one can do that in the
shell as well.
.SH AUTHOR
KS Braunsdorf
.br
tmbuf at nospam.ksb.npcguild.org
.SH "SEE ALSO"
.hlm 0
mailx(1) Mail(1), tail(1), sh(1), Tee(1l), tee(1), conserver(8l)