commit c1b983b8b82db08211c8bca1b9dbeef6220c1e14
parent dfe4f9d2469f5404817543bbaf7619b500ff0cbe
Author: Gerrit Pape <pape@smarden.org>
Date: Sat, 6 Nov 2004 15:41:54 +0000
html.
Diffstat:
| M | doc/chpst.8.html | | | 51 | ++++++++++++++++++++++++++++----------------------- |
| M | doc/runsv.8.html | | | 55 | ++++++++++++++++++++++++++++--------------------------- |
| M | doc/svlogd.8.html | | | 194 | +++++++++++++++++++++++++++++++++++++++++++------------------------------------ |
3 files changed, 161 insertions(+), 139 deletions(-)
diff --git a/doc/chpst.8.html b/doc/chpst.8.html
@@ -12,40 +12,45 @@
chpst - runs a program with a changed process state
<h2><a name='sect1'>Synopsis</a></h2>
<b>chpst</b> [-vP012]
-[-u <i>user</i>] [-U <i>user</i>] [-e <i>dir</i>] [-/ <i>root</i>] [-l|-L <i>lock</i>] [-m <i>bytes</i>] [-o <i>n</i>] [-p <i>n</i>] [-f <i>bytes</i>]
-[-c <i>bytes</i>] <i>prog</i>
+[-u <i>user</i>] [-U <i>user</i>] [-e <i>dir</i>] [-/ <i>root</i>] [-n <i>inc</i>] [-l|-L <i>lock</i>] [-m <i>bytes</i>] [-o <i>n</i>] [-p
+<i>n</i>] [-f <i>bytes</i>] [-c <i>bytes</i>] <i>prog</i>
<h2><a name='sect2'>Description</a></h2>
-<i>prog</i> consists of one or more arguments. <p>
-<b>chpst</b>
-changes the process state according to the given options, and runs <i>prog</i>.
-
+<i>prog</i> consists of one or more arguments.
+<p>
+<b>chpst</b> changes the process state according to the given options, and runs
+<i>prog</i>.
<h2><a name='sect3'>Options</a></h2>
<dl>
<dt><b>-u <i>user[:group]</b> </i></dt>
-<dd>setuidgid. Set uid and gid to the <i>user</i>’s uid and gid.
-If <i>user</i> is followed by a colon and a <i>group</i>, set the gid to <i>group</i>’s gid instead
-of <i>user</i>’s gid. All supplementary groups are removed. </dd>
+<dd>setuidgid. Set uid and gid to the <i>user</i>’s uid and
+gid. If <i>user</i> is followed by a colon and a <i>group</i>, set the gid to <i>group</i>’s gid
+instead of <i>user</i>’s gid. All supplementary groups are removed. </dd>
-<dt><b>-U <i>user[:group]</b> </i></dt>
-<dd>envuidgid.
-Set the environment variables $UID and $GID to the <i>user</i>’s uid and gid. If
-<i>user</i> is followed by a colon and a <i>group</i>, set $GID to the <i>group</i>’s gid instead
-of <i>user</i>’s gid. </dd>
+<dt><b>-U <i>user[:group]</b>
+</i></dt>
+<dd>envuidgid. Set the environment variables $UID and $GID to the <i>user</i>’s uid
+and gid. If <i>user</i> is followed by a colon and a <i>group</i>, set $GID to the <i>group</i>’s
+gid instead of <i>user</i>’s gid. </dd>
<dt><b>-e <i>dir</b> </i></dt>
-<dd>envdir. Set various environment variables as specified
-by files in the directory <i>dir</i>: If <i>dir</i> contains a file named <i>k</i> whose first
-line is <i>v</i>, <b>chpst</b> removes the environment variable <i>k</i> if it exists, and then
-adds the environment variable <i>k</i> with the value <i>v</i>. The name <i>k</i> must not contain
-=. Spaces and tabs at the end of <i>v</i> are removed, and nulls in <i>v</i> are changed
-to newlines. If the file <i>k</i> is empty (0 bytes long), <b>chpst</b> removes the environment
-variable <i>k</i> if it exists, without adding a new variable. </dd>
+<dd>envdir. Set various environment variables
+as specified by files in the directory <i>dir</i>: If <i>dir</i> contains a file named
+<i>k</i> whose first line is <i>v</i>, <b>chpst</b> removes the environment variable <i>k</i> if it
+exists, and then adds the environment variable <i>k</i> with the value <i>v</i>. The name
+<i>k</i> must not contain =. Spaces and tabs at the end of <i>v</i> are removed, and nulls
+in <i>v</i> are changed to newlines. If the file <i>k</i> is empty (0 bytes long), <b>chpst</b>
+removes the environment variable <i>k</i> if it exists, without adding a new variable.
+</dd>
<dt><b>-/ <i>root</b> </i></dt>
-<dd>chroot. Change
-the root directory to <i>root</i> before starting <i>prog</i>. </dd>
+<dd>chroot. Change the root directory to <i>root</i> before starting <i>prog</i>. </dd>
+
+<dt><b>-n
+<i>inc</b> </i></dt>
+<dd>nice. Add <i>inc</i> to the <i><b>nice</b>(2)</i> value before starting <i>prog</i>. <i>inc</i> must be
+an integer, and may start with a minus or plus. </dd>
<dt><b>-l <i>lock</b> </i></dt>
<dd>lock. Open the file
diff --git a/doc/runsv.8.html b/doc/runsv.8.html
@@ -47,32 +47,32 @@ pipe:
restart it. </dd>
<dt><b>d</b> </dt>
-<dd>Down. If the service is running, send it a TERM signal. If ./run
-exits, start ./finish if it exists. After it stops, do not restart service.
-</dd>
+<dd>Down. If the service is running, send it a TERM signal, and
+then a CONT signal. If ./run exits, start ./finish if it exists. After it stops,
+do not restart service. </dd>
<dt><b>o</b> </dt>
-<dd>Once. If the service is not running, start it. Do not restart it if it
-stops. </dd>
+<dd>Once. If the service is not running, start it. Do
+not restart it if it stops. </dd>
<dt><b>p</b> </dt>
-<dd>Pause. If the service is running, send it a STOP signal. </dd>
+<dd>Pause. If the service is running, send it a
+STOP signal. </dd>
<dt><b>c</b> </dt>
-<dd>Continue.
-If the service is running, send it a CONT signal. </dd>
+<dd>Continue. If the service is running, send it a CONT signal.
+</dd>
<dt><b>h</b> </dt>
-<dd>Hangup. If the service
-is running, send it a HUP signal. </dd>
+<dd>Hangup. If the service is running, send it a HUP signal. </dd>
<dt><b>a</b> </dt>
-<dd>Alarm. If the service is running, send
-it a ALRM signal. </dd>
+<dd>Alarm. If the
+service is running, send it a ALRM signal. </dd>
<dt><b>i</b> </dt>
-<dd>Interrupt. If the service is running, send it a INT signal.
-</dd>
+<dd>Interrupt. If the service is
+running, send it a INT signal. </dd>
<dt><b>q</b> </dt>
<dd>Quit. If the service is running, send it a QUIT signal. </dd>
@@ -83,25 +83,26 @@ it a ALRM signal. </dd>
<dt><b>2</b> </dt>
<dd>User-defined 2. If the service is running, send it a USR2 signal. </dd>
-<dt><b>t</b> </dt>
-<dd>Terminate. If the service is running,
-send it a TERM signal. </dd>
+<dt><b>t</b>
+</dt>
+<dd>Terminate. If the service is running, send it a TERM signal. </dd>
<dt><b>k</b> </dt>
-<dd>Kill. If the service is running, send it a KILL
-signal. </dd>
+<dd>Kill. If the
+service is running, send it a KILL signal. </dd>
<dt><b>x or <b>e</b> </b></dt>
-<dd>Exit. If the service is running, send it a TERM signal. Do
-not restart the service. If the service is down, and no log service exists,
-<b>runsv</b> exits. If the service is down and a log service exists, <b>runsv</b> closes
-the standard input of the log service, and waits for it to terminate. If
-the log service is down, <b>runsv</b> exits. This command is ignored if it is given
-to <i>service</i>/log/supervise/control. </dd>
+<dd>Exit. If the service is
+running, send it a TERM signal, and then a CONT signal. Do not restart the
+service. If the service is down, and no log service exists, <b>runsv</b> exits.
+If the service is down and a log service exists, <b>runsv</b> closes the standard
+input of the log service, and waits for it to terminate. If the log service
+is down, <b>runsv</b> exits. This command is ignored if it is given to <i>service</i>/log/supervise/control.
+</dd>
</dl>
<p>
-Example: to send a TERM signal to the
-socklog-unix service, either do # runsvctrl term /var/service/socklog-unix<br>
+Example: to send a TERM signal to the socklog-unix service, either do
+# runsvctrl term /var/service/socklog-unix<br>
or<br>
# echo -n t >/var/service/socklog-unix/supervise/control<br>
<p>
diff --git a/doc/svlogd.8.html b/doc/svlogd.8.html
@@ -41,52 +41,65 @@ 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)
-<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 <i>dir</i>, it removes the oldest
-one.
+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 <i>dir</i>, it removes the oldest one.
<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 ‘‘sh -c "<i>processor</i>"’’ 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 ‘‘sh -c "<i>processor</i>"’’ 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 <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 ‘‘#’’, it is ignored. A line of the form
+On startup, and after receiving a HUP signal, <b>svlogd</b> checks
+for each <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 ‘‘#’’, 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’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’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 maximum 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. </dd>
+<dd>sets the maximum 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.
+</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>
<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
@@ -113,89 +126,92 @@ each log message against <i>pattern</i> and acts accordingly:
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>log
-messages matching <i>pattern</i> are 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>log messages
-not matching <i>pattern</i> are printed to standard error. </dd>
+<dd>the log
+message is deselected to be printed to standard error. </dd>
</dl>
<p>
Initially each line
-is selected. Deselected log messages are discarded from <i>log</i>.
+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 (‘‘*’’) and not a plus (‘‘+’’) 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 (‘‘*’’) and not a plus (‘‘+’’) 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.
<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 <i><b>tai64n</b>(8)</i>) 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 ‘‘_’’). </dd>
+<dd>replace charset. Additionally
+to non-printable characters, replace all characters found in <i>xyz</i> with <i>c</i>
+(default ‘‘_’’). </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>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>http://smarden.org/runit/</i>
<h2><a name='sect11'>Author</a></h2>
-Gerrit Pape <pape@smarden.org> <p>
+Gerrit Pape <pape@smarden.org>
+<p>
<hr><p>
<a name='toc'><b>Table of Contents</b></a><p>
