1 .TH hush 1 "14 December 2011" "Edgeware tools"
3 hush \- run a program, quietly unless it fails
13 .IR owner ][\fB: group ]
22 program runs a command. The command's output (i.e., what it writes to
23 its standard output and standard error file descriptors) is always
24 logged to a file. If the command succeeds,
26 itself outputs nothing; if it fails, then
28 either writes the command's output to its own stdout, or sends it via
29 email. It is intended to be used when running noisy programs via
31 to reduce the amount of uninteresting mail (`cronspam') produced by an
32 essentially working system.
34 The following command-line options are recognized.
37 Write a help message describing
39 command line options and usage to standard output, and exit.
44 version number to standard output, and exit.
49 rather than the default,
52 .BI "\-m " email-address
53 Rather than writing its output to stdout if the command fails, send the
56 and exit with status 0. (This is perhaps a surprising choice, but it
57 prevents the caller from taking additional action to report a problem
58 which has already been escalated to a human.)
61 If necessary, delete old logfiles so that no more than
66 Set the permissions on the logfile to
68 a mode specification acceptable to
69 .BR chmod (1), though relative permissions will be applied to mode
74 .BI "\-u \fR[" user\fR][ : group\fR]
75 Set the ownership and/or group of the logfile. If the
77 is specified, then the file's owner is set; if the
79 is specified, the file's group is set. (Some care is taken to ensure
80 that the file is never available to members of the wrong group.)
87 with stdin redirected from
89 and stdout and stderr redirected to separate pipes. If it is available,
91 is used to ensure that the
93 stdout is line-buffered.
97 output is collected in a log file named
98 .IB logdir / tag . date # seq
102 is the argument of the
113 as a command-line argument;
116 is the current date, in ISO8601 form (in local time); and
119 is a sequence number, chosen to ensure that log file names are distinct
120 and sort in chronological order.
122 The log file begins with a header giving the exact start time (in local
123 time, with an offset from UTC) and a brief summary of the log format; it
124 ends with another timestamp and the
126 exit status. In between is the command's output. Lines written to
129 lines to stderr begin with
131 The two are interleaved in an attempt to help the reader identify how
134 had made when it encountered an error; however, because the streams are
135 read asynchronously, this isn't perfect, and lines may appear earlier or
136 later than they ought to.
140 succeeds, as mentioned,
142 exits without printing anything. If it fails, and the
144 option was given, the log file is mailed to the appropriate
159 option was given, this log is simply written to standard output.
161 The stream interleaving isn't quite right, but it's hard to see how to
164 Capturing the command's output involves making a fairly large number of
165 auxiliary processes and file descriptors. This is a bit ugly.
167 Mark Wooding, <mdw@distorted.org.uk>