--- /dev/null
+.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
+.I 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).
~mdw / misc / blobdiff