.TH hush 1 "14 December 2011" "Edgeware tools"
.SH NAME
hush \- run a program, quietly unless it fails
.SH SYNOPSIS
.B hush
.RB [ \-d
.IR directory ]
.RB [ \-m
.IR email-address ]
.RB [ \-n
.IR maxlog ]
.RB [ \-u
.IR owner ][\fB: group ]
.br
	\c
.I tag
.I command
.IR arguments ...
.SH DESCRIPTION
The
.B hush
program runs a command.  The command's output (i.e., what it writes to
its standard output and standard error file descriptors) is always
logged to a file.  If the command succeeds,
.B hush
itself outputs nothing; if it fails, then
.B hush
either writes the command's output to its own stdout, or sends it via
email.  It is intended to be used when running noisy programs via
.BR cron (8),
to reduce the amount of uninteresting mail (`cronspam') produced by an
essentially working system.
.PP
The following command-line options are recognized.
.TP
.B \-h
Write a help message describing
.BR hush 's
command line options and usage to standard output, and exit.
.TP
.B \-v
Write
.BR hush 's
version number to standard output, and exit.
.TP
.BI "\-d " directory
Write log files to
.I directory
rather than the default,
.BR "@logdir@" .
.TP
.BI "\-m " email-address
Rather than writing its output to stdout if the command fails, send the
command's output to
.IR email-address .
and exit with status 0.  (This is perhaps a surprising choice, but it
prevents the caller from taking additional action to report a problem
which has already been escalated to a human.)
.TP
.BI "\-n " maxlog
If necessary, delete old logfiles so that no more than
.I maxlog
log files are left.
.TP
.BI "\-p " mode
Set the permissions on the logfile to
.IR mode ,
a mode specification acceptable to
.BR chmod (1),
though relative permissions will be applied to mode
.B 600
(i.e.,
.BR u=rw,og= ).
.TP
.BI "\-u \fR[" user\fR][ : group\fR]
Set the ownership and/or group of the logfile.  If the
.I user
is specified, then the file's owner is set; if the
.I group
is specified, the file's group is set.  (Some care is taken to ensure
that the file is never available to members of the wrong group.)
.SS Operation
The given
.I command
is executed with the
given
.IR arguments ,
with stdin redirected from
.BR /dev/null ,
and stdout and stderr redirected to separate pipes.  If it is available,
.BR stdbuf (1)
is used to ensure that the
.IR command 's
stdout is line-buffered.
.PP
The
.IR command 's
output is collected in a log file named
.IB logdir / tag . date # seq
where
.TP
.I logdir
is the argument of the
.B \-d
option, or
.B @logdir@
by default;
.TP
.I tag
is the
.I tag
string given to
.B hush
as a command-line argument;
.TP
.I date
is the current date, in ISO8601 form (in local time); and
.TP
.I seq
is a sequence number, chosen to ensure that log file names are distinct
and sort in chronological order.
.PP
The log file begins with a header giving the exact start time (in local
time, with an offset from UTC) and a brief summary of the log format; it
ends with another timestamp and the
.IR command 's
exit status.  In between is the command's output.  Lines written to
stdout begin with
.RB ` | ';
lines to stderr begin with
.RB ` * '.
The two are interleaved in an attempt to help the reader identify how
much progress the
.I command
had made when it encountered an error; however, because the streams are
read asynchronously, this isn't perfect, and lines may appear earlier or
later than they ought to.
.PP
If the
.I command
succeeds, as mentioned,
.B hush
exits without printing anything.  If it fails, and the
.B \-m
option was given, the log file is mailed to the appropriate
.I email-address
with a subject line
.IP
.IB tag :
.I command
.B failed (status =
.IB rc )
.PP
where
.I rc
is the
.IR command 's
exit status.  If no
.B \-m
option was given, this log is simply written to standard output.
.SH BUGS
The stream interleaving isn't quite right, but it's hard to see how to
improve it.
.PP
Capturing the command's output involves making a fairly large number of
auxiliary processes and file descriptors.  This is a bit ugly.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.SH SEE ALSO
.BR cron (8).