html.

1 files changed, 144 insertions, 131 deletions

diff --git a/doc/svlogd.8.html b/doc/svlogd.8.html
index 900a6fc..d85ed79 100644
--- a/doc/svlogd.8.html
+++ b/doc/svlogd.8.html
@@ -29,187 +29,200 @@ sent a TERM signal, see below.
 A log directory <i>log</i> contains
 some number of old log files, and the current log file <i>current</i>. Old log
 files have a file name starting with <i>@</i> followed by a precise timestamp
-(see <i><b>tai64n</b>(8)</i>), indicating when <i>current</i> was rotated and renamed to this
-file. <p>
-A log directory additionally contains the lock file <i>lock</i>, maybe <i>state</i>
-and <i>newstate</i>, and optionally the file <i>config</i>. <b>svlogd</b> creates necessary files
-if they don&rsquo;t exist. <p>
-If <b>svlogd</b> has trouble opening a log directory, it prints
-a warning, and ignores this log directory. If <b>svlogd</b> is unable to open all
-log directories given at the command line, it exits with an error. This
-can happen on start-up or after receiving a HUP signal. 
+(see the daemontools&rsquo; <b>tai64n</b> program), indicating when <i>current</i> was rotated
+and renamed to this file. <p>
+A log directory additionally contains the lock
+file <i>lock</i>, maybe <i>state</i> and <i>newstate</i>, and optionally the file <i>config</i>. <b>svlogd</b>
+creates necessary files if they don&rsquo;t exist. <p>
+If <b>svlogd</b> has trouble opening
+a log directory, it prints a warning, and ignores this log directory. If
+<b>svlogd</b> is unable to open all log directories given at the command line,
+it exits with an error. This can happen on start-up or after receiving a
+HUP signal. 
 <h3><a name='sect4'>Log File Rotation</a></h3>
-<b>svlogd</b>
-appends selected log messages to the <i>current</i> log file. If <i>current</i> has <i>size</i>
-bytes or more (or there is a new-line within the last <i>len</i> of <i>size</i> bytes),
-or is older than a specified amount of <i>time</i>, <i>current</i> is rotated: <p>
-<b>svlogd</b>
-closes <i>current</i>, changes permission of <i>current</i> to 0755, renames <i>current</i>
-to @<i>timestamp.s,</i> and starts with a new empty <i>current</i>. If <b>svlogd</b> sees <i>num</i>
-or more old log files in the log directory, it removes the oldest one. Note
-that this doesn&rsquo;t decrease the number of log files if there are already
-more than <i>num</i> log files. 
+<b>svlogd</b> appends selected log messages to the
+<i>current</i> log file. If <i>current</i> has <i>size</i> bytes or more (or there is a new-line
+within the last <i>len</i> of <i>size</i> bytes), or is older than a specified amount
+of <i>time</i>, <i>current</i> is rotated: <p>
+<b>svlogd</b> closes <i>current</i>, changes permission
+of <i>current</i> to 0755, renames <i>current</i> to @<i>timestamp.s,</i> and starts with a new
+empty <i>current</i>. If <b>svlogd</b> sees <i>num</i> or more old log files in the log directory,
+it removes the oldest one. Note that this doesn&rsquo;t decrease the number of
+log files if there are already more than <i>num</i> log files. 
 <h3><a name='sect5'>Processor</a></h3>
-If <b>svlogd</b> is told to process recent log
-files, it saves <i>current</i> to @<i>timestamp.u,</i> feeds @<i>timestamp.u</i> through &lsquo;&lsquo;sh -c
-"<i>processor</i>"&rsquo;&rsquo; and writes the output to @<i>timestamp.t.</i> If the <i>processor</i> finishes
-successfully, @<i>timestamp.u</i> is deleted and @<i>timestamp.t</i> is renamed to @<i>timestamp.s,</i>
-otherwise @<i>timestamp.t</i> is deleted and the <i>processor</i> is started again. <b>svlogd</b>
-also saves any output that the <i>processor</i> writes to file descriptor 5, and
-makes that output available on file descriptor 4 when running <i>processor</i>
-on the next log file rotation. <p>
-A <i>processor</i> is run in the background. If <b>svlogd</b>
-sees a previously started <i>processor</i> still running when trying to start
-a new one for the same <i>log</i>, it blocks until the currently running <i>processor</i>
-has finished successfully. Only the HUP signal works in that situation. Note
-that this may block any program feeding its log data to <b>svlogd.</b> 
+If <b>svlogd</b>
+is told to process recent log files, it saves <i>current</i> to @<i>timestamp.u,</i> feeds
+@<i>timestamp.u</i> through &lsquo;&lsquo;sh -c "<i>processor</i>"&rsquo;&rsquo; and writes the output to @<i>timestamp.t.</i>
+If the <i>processor</i> finishes successfully, @<i>timestamp.u</i> is deleted and @<i>timestamp.t</i>
+is renamed to @<i>timestamp.s,</i> otherwise @<i>timestamp.t</i> is deleted and the <i>processor</i>
+is started again. <b>svlogd</b> also saves any output that the <i>processor</i> writes
+to file descriptor 5, and makes that output available on file descriptor
+4 when running <i>processor</i> on the next log file rotation. <p>
+A <i>processor</i> is run
+in the background. If <b>svlogd</b> sees a previously started <i>processor</i> still running
+when trying to start a new one for the same <i>log</i>, it blocks until the currently
+running <i>processor</i> has finished successfully. Only the HUP signal works in
+that situation. Note that this may block any program feeding its log data
+to <b>svlogd.</b> 
 <p> 
 <h3><a name='sect6'>Config</a></h3>
-On
-startup, and after receiving a HUP signal, <b>svlogd</b> checks for each log directory
-<i>log</i> if the configuration file <i>log/config</i> exists, and if so, reads the file
-line by line and adjusts configuration for <i>log</i> as follows: <p>
-If the line
-is empty, less than two characters long, or starts with a &lsquo;&lsquo;#&rsquo;&rsquo;, it is ignored.
-A line of the form 
+On startup, and after receiving a HUP signal, <b>svlogd</b> checks
+for each log directory <i>log</i> if the configuration file <i>log/config</i> exists,
+and if so, reads the file line by line and adjusts configuration for <i>log</i>
+as follows: <p>
+If the line is empty, less than two characters long, or starts
+with a &lsquo;&lsquo;#&rsquo;&rsquo;, it is ignored. A line of the form 
 <dl>
 
 <dt>s<i>size</i> </dt>
-<dd>sets the maximum file size of <i>current</i> when <b>svlogd</b>
-should rotate the current log file to <i>size</i> bytes. Default is 1000000. If
-<i>size</i> is zero, <b>svlogd</b> doesn&rsquo;t rotate log files. You should set <i>size</i> to at
-least (2 * <i>len</i>). </dd>
+<dd>sets the maximum file
+size of <i>current</i> when <b>svlogd</b> should rotate the current log file to <i>size</i>
+bytes. Default is 1000000. If <i>size</i> is zero, <b>svlogd</b> doesn&rsquo;t rotate log files.
+You should set <i>size</i> to at least (2 * <i>len</i>). </dd>
 
 <dt>n<i>num</i> </dt>
-<dd>sets the number of old log files <b>svlogd</b> should maintain
-to <i>num</i>. If <b>svlogd</b> sees more that <i>num</i> old log files in <i>log</i> after log file
-rotation, it deletes the oldest one. Default is 10. If <i>num</i> is zero, <b>svlogd</b>
-doesn&rsquo;t remove old log files. </dd>
+<dd>sets the number of old log
+files <b>svlogd</b> should maintain to <i>num</i>. If <b>svlogd</b> sees more that <i>num</i> old log
+files in <i>log</i> after log file rotation, it deletes the oldest one. Default
+is 10. If <i>num</i> is zero, <b>svlogd</b> doesn&rsquo;t remove old log files. </dd>
 
 <dt>N<i>min</i> </dt>
-<dd>sets the minimum number of old log files
-<b>svlogd</b> should maintain to <i>min</i>. <i>min</i> must be less than <i>num</i>. If <i>min</i> is set,
-and <b>svlogd</b> cannot write to <i>current</i> because the filesystem is full, and
-it sees more than <i>min</i> old log files, it deletes the oldest one. </dd>
-
-<dt>t<i>timeout</i>
-</dt>
-<dd>sets the maximum age of the <i>current</i> log file when <b>svlogd</b> should rotate
-the current log file to <i>timeout</i> seconds. If <i>current</i> is <i>timeout</i> seconds old,
-and is not empty, <b>svlogd</b> forces log file rotation. </dd>
+<dd>sets the
+minimum number of old log files <b>svlogd</b> should maintain to <i>min</i>. <i>min</i> must
+be less than <i>num</i>. If <i>min</i> is set, and <b>svlogd</b> cannot write to <i>current</i> because
+the filesystem is full, and it sees more than <i>min</i> old log files, it deletes
+the oldest one. </dd>
+
+<dt>t<i>timeout</i> </dt>
+<dd>sets the maximum age of the <i>current</i> log file when
+<b>svlogd</b> should rotate the current log file to <i>timeout</i> seconds. If <i>current</i>
+is <i>timeout</i> seconds old, and is not empty, <b>svlogd</b> forces log file rotation.
+</dd>
 
 <dt>!<i>processor</i> </dt>
-<dd>tells <b>svlogd</b>
-to feed each recent log file through <i>processor</i> (see above) on log file
-rotation. By default log files are not processed. </dd>
+<dd>tells <b>svlogd</b> to feed each recent log file through <i>processor</i>
+(see above) on log file rotation. By default log files are not processed.
+</dd>
 
 <dt>u<i>a.b.c.d[:port]</i> </dt>
-<dd>tells <b>svlogd</b>
-to transmit the first <i>len</i> characters of selected log messages to the IP
-address <i>a.b.c.d</i>, port number <i>port</i>. If <i>port</i> isn&rsquo;t set, the default port for syslog
-is used (514). <i>len</i> can be set through the -l option, see below. If <b>svlogd</b>
-has trouble sending udp packets, it writes error messages to the log directory.
-Attention: logging through udp is unreliable, and should be used in private
-networks only. </dd>
+<dd>tells <b>svlogd</b> to transmit the first <i>len</i> characters of selected
+log messages to the IP address <i>a.b.c.d</i>, port number <i>port</i>. If <i>port</i> isn&rsquo;t set,
+the default port for syslog is used (514). <i>len</i> can be set through the -l
+option, see below. If <b>svlogd</b> has trouble sending udp packets, it writes
+error messages to the log directory. Attention: logging through udp is unreliable,
+and should be used in private networks only. </dd>
 
 <dt>U<i>a.b.c.d[:port]</i> </dt>
-<dd>is the same as the <i>u</i> line above, but the log
-messages are no longer written to the log directory, but transmitted through
-udp only. Error messages from <b>svlogd</b> concerning sending udp packages still
-go to the log directory. </dd>
+<dd>is the same as
+the <i>u</i> line above, but the log messages are no longer written to the log
+directory, but transmitted through udp only. Error messages from <b>svlogd</b>
+concerning sending udp packages still go to the log directory. </dd>
 </dl>
 <p>
-If a line starts with a <i>-</i>, <i>+</i>, <i>e</i>, or <i>E</i>, <b>svlogd</b> matches
-the first <i>len</i> characters of each log message against <i>pattern</i> and acts accordingly:
-
+If a line
+starts with a <i>-</i>, <i>+</i>, <i>e</i>, or <i>E</i>, <b>svlogd</b> matches the first <i>len</i> characters of
+each log message against <i>pattern</i> and acts accordingly: 
 <dl>
 
 <dt>-<i>pattern</i> </dt>
-<dd>the log message is deselected. </dd>
+<dd>the log
+message is deselected. </dd>
 
 <dt>+<i>pattern</i> </dt>
-<dd>the log message is selected.
-</dd>
+<dd>the log message is selected. </dd>
 
 <dt>e<i>pattern</i> </dt>
-<dd>the log message is selected to be printed to standard error. </dd>
+<dd>the
+log message is selected to be printed to standard error. </dd>
 
-<dt>E<i>pattern</i>
-</dt>
-<dd>the log message is deselected to be printed to standard error. </dd>
+<dt>E<i>pattern</i> </dt>
+<dd>the log
+message is deselected to be printed to standard error. </dd>
 </dl>
 <p>
-Initially
-each line is selected to be written to <i>log/current</i>. Deselected log messages
-are discarded from <i>log</i>. Initially each line is deselected to be written
-to standard err. Log messages selected for standard error are written to
-standard error. 
+Initially each line
+is selected to be written to <i>log/current</i>. Deselected log messages are discarded
+from <i>log</i>. Initially each line is deselected to be written to standard err.
+Log messages selected for standard error are written to standard error.
+
 <h2><a name='sect7'>Pattern Matching</a></h2>
-<b>svlogd</b> matches a log message against the
-string <i>pattern</i> as follows: <p>
-<i>pattern</i> is applied to the log message one character
-by one, starting with the first. A character not a star (&lsquo;&lsquo;*&rsquo;&rsquo;) and not a plus
-(&lsquo;&lsquo;+&rsquo;&rsquo;) matches itself. A plus matches the next character in <i>pattern</i> in the
-log message one or more times. A star before the end of <i>pattern</i> matches
-any string in the log message that does not include the next character
-in <i>pattern</i>. A star at the end of <i>pattern</i> matches any string. <p>
-Timestamps optionally
-added by <b>svlogd</b> are not considered part of the log message. 
+<b>svlogd</b> matches a log message against the string <i>pattern</i>
+as follows: <p>
+<i>pattern</i> is applied to the log message one character by one,
+starting with the first. A character not a star (&lsquo;&lsquo;*&rsquo;&rsquo;) and not a plus (&lsquo;&lsquo;+&rsquo;&rsquo;) matches
+itself. A plus matches the next character in <i>pattern</i> in the log message
+one or more times. A star before the end of <i>pattern</i> matches any string in
+the log message that does not include the next character in <i>pattern</i>. A star
+at the end of <i>pattern</i> matches any string. <p>
+Timestamps optionally added by
+<b>svlogd</b> are not considered part of the log message. <p>
+An <b>svlogd</b> pattern is
+not a regular expression. For example consider a log message like this <p>
+
+2005-12-18_09:13:50.97618 tcpsvd: info: pid 1977 from 10.4.1.14<br>
+ <p>
+The following pattern doesn&rsquo;t match <p>
+ -*pid*<br>
+ <p>
+because the first star matches up to the first p in tcpsvd, and then the
+match fails because i is not s. To match this log message, you can use a
+pattern like this instead <p>
+ -*: *: pid *<br>
+ 
 <h2><a name='sect8'>Options</a></h2>
 
 <dl>
 
 <dt><b>-t</b> </dt>
-<dd>timestamp.
-Prefix each selected line with a precise timestamp (see <i><b>tai64n</b>(8)</i>) when
-writing to <i>log</i> or to standard error. </dd>
+<dd>timestamp. Prefix each selected line with a precise timestamp
+(see the daemontools&rsquo; <b>tai64n</b> program) when writing to <i>log</i> or to standard
+error. </dd>
 
 <dt><b>-tt</b> </dt>
-<dd>timestamp. Prefix each selected line
-with a human readable, sortable UTC timestamp of the form YYYY-MM-DD_HH:MM:SS.xxxxx
-when writing to <i>log</i> or to standard error. </dd>
+<dd>timestamp. Prefix each selected line with a human readable, sortable
+UTC timestamp of the form YYYY-MM-DD_HH:MM:SS.xxxxx when writing to <i>log</i> or
+to standard error. </dd>
 
 <dt><b>-r <i>c</b> </i></dt>
-<dd>replace. <i>c</i> must be a single
-character. Replace non-printable characters in log messages with <i>c</i>. Characters
-are replaced before pattern matching is applied. </dd>
+<dd>replace. <i>c</i> must be a single character. Replace non-printable
+characters in log messages with <i>c</i>. Characters are replaced before pattern
+matching is applied. </dd>
 
 <dt><b>-R <i>xyz</b> </i></dt>
-<dd>replace charset. Additionally
-to non-printable characters, replace all characters found in <i>xyz</i> with <i>c</i>
-(default &lsquo;&lsquo;_&rsquo;&rsquo;). </dd>
+<dd>replace charset. Additionally to non-printable
+characters, replace all characters found in <i>xyz</i> with <i>c</i> (default &lsquo;&lsquo;_&rsquo;&rsquo;). </dd>
 
-<dt><b>-l <i>len</b> </i></dt>
-<dd>line length. Pattern matching applies to the first <i>len</i>
-characters of a log message only. Default is 1000. </dd>
+<dt><b>-l <i>len</b>
+</i></dt>
+<dd>line length. Pattern matching applies to the first <i>len</i> characters of a log
+message only. Default is 1000. </dd>
 
 <dt><b>-b <i>buflen</b> </i></dt>
-<dd>buffer size. Set
-the size of the buffer <b>svlogd</b> uses when reading from standard input and
-writing to <i>logs</i> to <i>buflen</i>. Default is 1024. <i>buflen</i> must be greater than <i>len</i>.
-</dd>
+<dd>buffer size. Set the size of the buffer
+<b>svlogd</b> uses when reading from standard input and writing to <i>logs</i> to <i>buflen</i>.
+Default is 1024. <i>buflen</i> must be greater than <i>len</i>. </dd>
 
 <dt><b>-v</b> </dt>
-<dd>verbose. Print verbose messages to standard error. </dd>
+<dd>verbose. Print verbose
+messages to standard error. </dd>
 </dl>
 
 <h2><a name='sect9'>Signals</a></h2>
-If <b>svlogd</b> is
-sent a HUP signal, it closes and reopens all <i>logs</i>, and updates their configuration
-according to <i>log/config</i>. If <b>svlogd</b> has trouble opening a log directory,
-it prints a warning, and discards this log directory. If <b>svlogd</b> is unable
-to open all log directories given at the command line, it exits with an
-error. <p>
-If <b>svlogd</b> is sent a TERM signal, or if it sees end-of-file on standard
-input, it stops reading standard input, processes the data in the buffer,
-waits for all <i>processor</i> subprocesses to finish if any, and exits 0 as soon
-as possible. <p>
-If <b>svlogd</b> is sent an ALRM signal, it forces log file rotation
-for all <i>logs</i> with a non empty <i>current</i> log file. 
+If <b>svlogd</b> is sent a HUP signal, it closes
+and reopens all <i>logs</i>, and updates their configuration according to <i>log/config</i>.
+If <b>svlogd</b> has trouble opening a log directory, it prints a warning, and
+discards this log directory. If <b>svlogd</b> is unable to open all log directories
+given at the command line, it exits with an error. <p>
+If <b>svlogd</b> is sent a TERM
+signal, or if it sees end-of-file on standard input, it stops reading standard
+input, processes the data in the buffer, waits for all <i>processor</i> subprocesses
+to finish if any, and exits 0 as soon as possible. <p>
+If <b>svlogd</b> is sent an
+ALRM signal, it forces log file rotation for all <i>logs</i> with a non empty
+<i>current</i> log file. 
 <h2><a name='sect10'>See Also</a></h2>
-<i>runsv(8)</i>, <i>runsvctrl(8)</i>,
-<i>runsvstat(8)</i>, <i>chpst(8)</i>, <i>runit(8)</i>, <i>runit-init(8)</i>, <i>runsvdir(8)</i>, <i>runsvchdir(8)</i>,
-<i>utmpset(8)</i>, <i>multilog(8)</i> <p>
+<i>sv(8)</i>, <i>runsv(8)</i>, <i>chpst(8)</i>, <i>runit(8)</i>, <i>runit-init(8)</i>,
+<i>runsvdir(8)</i>, <i>runsvchdir(8)</i> <p>
 <i>http://smarden.org/runit/</i> 
 <h2><a name='sect11'>Author</a></h2>
 Gerrit Pape &lt;pape@smarden.org&gt;