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
70 though relative permissions will be applied to mode
75 .BI "\-u \fR[" user\fR][ : group\fR]
76 Set the ownership and/or group of the logfile. If the
78 is specified, then the file's owner is set; if the
80 is specified, the file's group is set. (Some care is taken to ensure
81 that the file is never available to members of the wrong group.)
88 with stdin redirected from
90 and stdout and stderr redirected to separate pipes. If it is available,
92 is used to ensure that the
94 stdout is line-buffered.
98 output is collected in a log file named
99 .IB logdir / tag . date # seq
103 is the argument of the
114 as a command-line argument;
117 is the current date, in ISO8601 form (in local time); and
120 is a sequence number, chosen to ensure that log file names are distinct
121 and sort in chronological order.
123 The log file begins with a header giving the exact start time (in local
124 time, with an offset from UTC) and a brief summary of the log format; it
125 ends with another timestamp and the
127 exit status. In between is the command's output. Lines written to
130 lines to stderr begin with
132 The two are interleaved in an attempt to help the reader identify how
135 had made when it encountered an error; however, because the streams are
136 read asynchronously, this isn't perfect, and lines may appear earlier or
137 later than they ought to.
141 succeeds, as mentioned,
143 exits without printing anything. If it fails, and the
145 option was given, the log file is mailed to the appropriate
160 option was given, this log is simply written to standard output.
162 The stream interleaving isn't quite right, but it's hard to see how to
165 Capturing the command's output involves making a fairly large number of
166 auxiliary processes and file descriptors. This is a bit ugly.
168 Mark Wooding, <mdw@distorted.org.uk>