From 6f13cd197540af0bf5e87f87ab0e03548d9c5f64 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sat, 27 Apr 2019 23:27:39 +0000
Subject:  Doc fixes

---
 doc/index.html                     |  6 +++--
 doc/s6-linux-init-hpr.html         | 15 ++++--------
 doc/s6-linux-init-logouthookd.html | 14 +++++++++++
 doc/s6-linux-init-maker.html       | 15 ++++++------
 doc/s6-linux-init-shutdown.html    | 49 +++++++++++++++++++++++++++++++++-----
 doc/s6-linux-init-shutdownd.html   |  7 ------
 doc/s6-linux-init-telinit.html     | 12 ++++++++++
 doc/s6-linux-init-umountall.html   | 11 +++++++--
 doc/s6-linux-init.html             | 19 ++++++++++-----
 doc/why.html                       |  2 +-
 10 files changed, 108 insertions(+), 42 deletions(-)

(limited to 'doc')

diff --git a/doc/index.html b/doc/index.html
index a428ccf..83464df 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -148,8 +148,10 @@ the previous versions of s6-linux-init and the current one. </li>
 <h3> Commands </h3>
 
 <p>
- All these commands exit 111 if they encounter a temporary error, and
-100 if they encounter a permanent error - such as a misuse.
+ Unless more details are provided in an <em>Exit codes</em> section
+of a specific page, all these commands exit 0 on success, 111 if they encounter a
+temporary error (such as a system call failure) and 100 if they encounter a
+permanent error (such as a misuse).
 </p>
 
 <ul>
diff --git a/doc/s6-linux-init-hpr.html b/doc/s6-linux-init-hpr.html
index 304ed35..5f09574 100644
--- a/doc/s6-linux-init-hpr.html
+++ b/doc/s6-linux-init-hpr.html
@@ -22,8 +22,9 @@
 <p>
  <tt>s6-linux-init-hpr</tt> triggers the software shutdown procedure,
 or, with the <tt>-f</tt> option, it perform an immediate hardware shutdown.
-It is normally invoked as <tt>/sbin/halt</tt>, <tt>/sbin/poweroff</tt> or
-<tt>/sbin/reboot</tt>.
+It is normally invoked through <tt>halt</tt>, <tt>poweroff</tt> or
+<tt>reboot</tt> wrappers created by
+<a href="s6-linux-init-maker.html">s6-linux-init-maker</a>.
 </p>
 
 <h2> Interface </h2>
@@ -33,7 +34,7 @@ It is normally invoked as <tt>/sbin/halt</tt>, <tt>/sbin/poweroff</tt> or
 </pre>
 
 <ul>
- <li> If the <tt>-f</tt> option is present, the hardware command is executed immediately. </li>
+ <li> If the <tt>-f</tt> option is present, the system is stopped or rebooted immediately. </li>
  <li> Else, the machine's shutdown procedure is started.
  <li> The command exits 0; the shutdown procedure happens asynchronously. </li>
 </ul>
@@ -45,14 +46,6 @@ It is normally invoked as <tt>/sbin/halt</tt>, <tt>/sbin/poweroff</tt> or
 <tt>-h</tt>, <tt>-p</tt> or <tt>-r</tt> options.
 </p>
 
-<h2> Exit codes </h2>
-
-<ul>
- <li> 0: shutdown procedure triggered. </li>
- <li> 100: wrong usage, or user does not have root privileges. </li>
- <li> 111: system call failed. </li>
-</ul>
-
 <h2> Options </h2>
 
 <ul>
diff --git a/doc/s6-linux-init-logouthookd.html b/doc/s6-linux-init-logouthookd.html
index 51edca1..088f5d5 100644
--- a/doc/s6-linux-init-logouthookd.html
+++ b/doc/s6-linux-init-logouthookd.html
@@ -70,6 +70,20 @@ local service, which will do nothing but wait until the user's shell dies;
 and when it happens, the user's utmp record will automatically be cleaned up.
 </p>
 
+<h2> Exit codes </h2>
+
+<p>
+ <tt>s6-linux-init-logouthookd</tt>'s exit code does not matter, because
+no program uses it. However, here's the list for completeness:
+</p>
+
+<ul>
+ <li> 0: success, whether or not there was an utmp record to clean up. </li>
+ <li> 1: connection attempt from a non-root user. </li>
+ <li> 2: write attempt from a (misprogrammed) client. </li>
+ <li> 111: system call failed. </li>
+</ul>
+
 <h2> Notes </h2>
 
 <ul>
diff --git a/doc/s6-linux-init-maker.html b/doc/s6-linux-init-maker.html
index eed5d79..a9f6e8b 100644
--- a/doc/s6-linux-init-maker.html
+++ b/doc/s6-linux-init-maker.html
@@ -57,7 +57,7 @@ machine</em>. If it is not the case, the system will fail to boot.
        [ -d <em>dev_style</em> ] \
        [ -s <em>env_store</em> ] \
        [ -e <em>initial_envvar</em> ] ... \
-       [ -q ] <em>finalsleeptime</em>
+       [ -q <em>finalsleeptime</em> ] \
        [ -D <em>initdefault</em> ] \
        [ -U <em>utmp_user</em> ] \
        <em>dir</em>
@@ -104,7 +104,7 @@ which have been stored into <em>env_store</em>. </li>
  <li> <tt>rc.shutdown</tt>: this script will be run as the
 <em>shutdown sequence</em>, when the administrator runs the
 <tt>shutdown</tt>, <tt>halt</tt>, <tt>poweroff</tt> or <tt>reboot</tt>
-command. (As well as <tt>init 0</tt>, <tt>init 6</tt>.
+command. (As well as <tt>init 0</tt>, <tt>init 6</tt>,
 <tt>telinit 0</tt> and <tt>telinit 6</tt> for compatibility
 reasons.) It should ask the service manager to bring all the
 services down, and exit when it's done (in other words: it should
@@ -134,7 +134,7 @@ be accessible as <tt>/sbin/init</tt>. </li>
 
 <p>
  When the kernel boots, it may run an initramfs first, but in any
-case it then runs the <tt><em>basedir</em>/init</tt> script,
+case it then runs the <tt>/sbin/init</tt> script,
 also known as <em>stage 1</em>. This script is just an execution
 of the <a href="s6-linux-init.html">s6-linux-init</a> program with
 some command-line options that are directly transferred from the
@@ -181,8 +181,10 @@ service to clean up utmp records at user logout time. Check the
 <a href="s6-linux-init-logouthookd">s6-linux-init-logouthookd</a> page
 for details. </li> <p />
 
- <li> <tt>-p</tt>&nbsp;<em>initial_path</em>&nbsp;: the value to
-set the PATH environment variable to, for all the starting processes.
+ <li> <tt>-p</tt>&nbsp;<em>initial_path</em>&nbsp;: the initial value
+for the PATH environment variable, that will be transmitted to all the
+starting process unless it's overridden by a PATH declaration via the
+<tt>-e</tt> option.
 It is absolutely necessary for
 <a href="//skarnet.org/software/execline/">execline</a> and
 <a href="//skarnet.org/software/s6/">s6</a>
@@ -315,8 +317,7 @@ services are:
      <li> <tt>s6-svscan-log</tt>: the catch-all logger. </li>
      <li> <tt>s6-linux-init-shutdownd</tt>: a service that listens
 to shutdown commands such as <tt>reboot</tt> and triggers the software
-shutdown procedure. The service is asleep for the whole lifetime of
-the machine and uses very few resources. </li>
+shutdown procedure. </li>
      <li> <tt>s6-linux-init-runleveld</tt>: a service that listens
 to runlevel change commands such as <tt>telinit</tt> and calls the
 <em>runlevel</em> script in a reproducible environment to bring the
diff --git a/doc/s6-linux-init-shutdown.html b/doc/s6-linux-init-shutdown.html
index b48ea61..519d1e3 100644
--- a/doc/s6-linux-init-shutdown.html
+++ b/doc/s6-linux-init-shutdown.html
@@ -32,8 +32,10 @@ It is normally invoked as <tt>/sbin/shutdown</tt>.
 
 <ul>
  <li> If the <tt>-c</tt> option is present, a pending shutdown is cancelled. </li>
- <li> Else, it triggers the shutdown procedure. </li>
- <li> It exits 0. The shutdown procedure happens asynchronously. </li>
+ <li> Else, it plans the shutdown procedure at time <em>time</em>. </li>
+ <li> If a <em>message</em> argument has been given, <em>message</em> is
+broadcast to all logged in users (as tracked by utmp). </li>
+ <li> <tt>shutdown</tt> exits 0. The shutdown procedure happens asynchronously. </li>
 </ul>
 
 <p>
@@ -42,12 +44,42 @@ It is normally invoked as <tt>/sbin/shutdown</tt>.
 interface.
 </p>
 
-<h2> Exit codes </h2>
+<p>
+ <em>time</em> must follow the following format:
+<tt>[&nbsp;now&nbsp;|&nbsp;[+]<em>mins</em>&nbsp;|&nbsp;<em>hh</em>:<em>mm</em>&nbsp;]
+</p>
+
+<ul>
+ <li> <tt>now</tt> means: trigger the shutdown sequence immediately. </li>
+ <li> <em>hh</em>:<em>mm</em> means: absolute time. Trigger the shutdown sequence when the time
+<em>hh</em>:<em>mm</em> occurs. If that time has passed for the day, it will wait for the
+next day. <em>hh</em> must have 1 or 2 digits; <em>mm</em> must have 2 digits. </li>
+ <li> <em>mins</em> or <tt>+</tt><em>mins</em> means: relative time. Trigger the shutdown
+sequence after <em>mins</em> minutes. </li>
+</ul>
+
+<h2> Options </h2>
 
 <ul>
- <li> 0: shutdown procedure triggered. </li>
- <li> 100: wrong usage, or user does not have root privileges. </li>
- <li> 111: system call failed. </li>
+ <li> <tt>-a</tt>&nbsp;: access control. The shutdown sequence will only be
+launched if one of the users listed in <tt>/etc/shutdown.allow</tt>
+is currently logged in (as tracked by utmp). <tt>/etc/shutdown.allow</tt>
+is a text file, one user per line, lines starting with <tt>#</tt> are comments. </li>
+ <li> <tt>-t</tt>&nbsp;<em>sec</em>&nbsp;: at the end of the shutdown sequence,
+when it's time to kill all processes, have a "grace time" period
+of <em>sec</em> seconds between the SIGTERM and the SIGKILL (to allow processes
+receiving SIGTERM to exit cleanly). Default is 3 seconds. </li>
+ <li> <tt>-k</tt>&nbsp;: warning only. <em>message</em> will be sent to all
+logged in users, but the shutdown sequence will not be triggered. </li>
+ <li> <tt>-h</tt>&nbsp;: at the end of the shutdown sequence, halt the system. </li>
+ <li> <tt>-p</tt>&nbsp;: at the end of the shutdown sequence, power off the system.
+(This option is provided as an extension, it is not required by the LSB interface.) </li>
+ <li> <tt>-r</tt>&nbsp;: at the end of the shutdown sequence, reboot the system. </li>
+ <li> <tt>-f</tt>&nbsp;: ignored. </li>
+ <li> <tt>-F</tt>&nbsp;: ignored. </li>
+ <li> <tt>-c</tt>&nbspl: cancel a planned shutdown (i.e. cancel the effect of a
+previous call to <tt>shutdown</tt> with a <em>time</em> argument that was not <tt>now</tt>).
+This cannot be used to interrupt a shutdown sequence that has already started. </li>
 </ul>
 
 <h2> Notes </h2>
@@ -60,6 +92,11 @@ the <tt>bin/</tt> subdirectory of the target will contain a <tt>shutdown</tt>
 symlink to <tt>s6-linux-init-shutdown</tt>. The <tt>bin/</tt> subdirectory
 should be copied by the administrator into <tt>/sbin</tt> for full
 interface compatibility with sysvinit. </li>
+ <li> The <tt>-f</tt> and <tt>-F</tt> options are only accepted for compatibility.
+LSB says they are used to advise the system to skip or enforce a <tt>fsck</tt>
+after rebooting. But they are only advisory, and for decades now systems have used
+other methods of evaluating whether they should perform filesystem checks, so these
+options are largely obsolete nowadays. </li>
 </ul>
 
 </body>
diff --git a/doc/s6-linux-init-shutdownd.html b/doc/s6-linux-init-shutdownd.html
index c601466..8889a9e 100644
--- a/doc/s6-linux-init-shutdownd.html
+++ b/doc/s6-linux-init-shutdownd.html
@@ -47,13 +47,6 @@ which unmounts the file systems and halts, powers off or reboots the
 machine. </li>
 </ul>
 
-<h2> Exit codes </h2>
-
-<ul>
- <li> 100: wrong usage, or user does not have root privileges. </li>
- <li> 111: system call failed. </li>
-</ul>
-
 <h2> Options </h2>
 
 <ul>
diff --git a/doc/s6-linux-init-telinit.html b/doc/s6-linux-init-telinit.html
index bc7f12d..2bea4e5 100644
--- a/doc/s6-linux-init-telinit.html
+++ b/doc/s6-linux-init-telinit.html
@@ -46,6 +46,18 @@ for compatibility with sysvinit's <em>0</em> and <em>6</em> runlevels
 that respectively halt and reboot the machine. </li>
 </ul>
 
+<h2> Exit codes </h2>
+
+<ul>
+ <li> 100: wrong usage </li>
+ <li> 111: system call failed </li>
+ <li> Else, <tt>s6-linux-init-telinit</tt> exits with the same exit code
+as the <em>runlevel</em> script called with the <em>rl</em> argument. </li>
+ <li> If <em>rl</em> is 0 or 6, in case of success
+<tt>s6-linux-init-telinit</tt> exits 0, but the system shuts down
+immediately as it returns. </li>
+</ul>
+
 <h2> Notes </h2>
 
 <ul>
diff --git a/doc/s6-linux-init-umountall.html b/doc/s6-linux-init-umountall.html
index c2402fd..2d1bf99 100644
--- a/doc/s6-linux-init-umountall.html
+++ b/doc/s6-linux-init-umountall.html
@@ -19,7 +19,7 @@
 <h1> The <tt>s6-linux-init-umountall</tt> program </h1>
 
 <p>
- <tt>s6-linux-init-umountall</tt> unmounts all the filesystems.
+ <tt>s6-linux-init-umountall</tt> unmounts all filesystems.
 </p>
 
 <h2> Interface </h2>
@@ -29,7 +29,7 @@
 </pre>
 
 <ul>
- <li> <tt>s6-linux-init-umountall</tt> unmounts all partitions according to <tt>/proc/mounts</tt>.
+ <li> <tt>s6-linux-init-umountall</tt> unmounts all filesystems according to <tt>/proc/mounts</tt>.
 It processes <tt>/proc/mounts</tt> in the reverse order, starting with the most recently mounted
 partition and ending with the root filesystem ("unmounting" the root filesystem means remounting
 it read-only). </li>
@@ -38,6 +38,13 @@ it read-only). </li>
 <tt>s6-linux-init-umountall</tt> still attempts to unmount all the other ones. </li>
 </ul>
 
+<h2> Exit codes </h2>
+
+<p>
+ <tt>s6-linux-init-umountall</tt> returns the number of errors it encountered
+when attempting to unmount all the filesystems listed in <tt>/proc/mounts</tt>.
+</p>
+
 <h2> Notes </h2>
 
 <ul>
diff --git a/doc/s6-linux-init.html b/doc/s6-linux-init.html
index e8ab361..31014d6 100644
--- a/doc/s6-linux-init.html
+++ b/doc/s6-linux-init.html
@@ -52,12 +52,11 @@ If there is a discrepancy, the system might not boot.
  <li> <tt>-c</tt>&nbsp;<em>basedir</em>&nbsp;: read all its initialization
 data from <em>basedir</em>. If the data has not indeed been copied to
 <em>basedir</em>, <strong>the system will not boot</strong>. </li>
- <li> <tt>-p</tt>&nbsp;<em>initial_path</em>&nbsp;: the value to
-set the initial PATH environment variable to.
+ <li> <tt>-p</tt>&nbsp;<em>initial_path</em>&nbsp;: the initial value for
+the PATH environment variable. </li>
  <li> <tt>-s</tt>&nbsp;<em>env_store</em>&nbsp;: the place where to dump
 kernel environment variables. </li>
- <li> <tt>-m</tt>&nbsp;<em>initial_umask</em>&nbsp;: the value of
-the initial file umask. </li>
+ <li> <tt>-m</tt>&nbsp;<em>initial_umask</em>&nbsp;: the initial file umask. </li>
  <li> <tt>-d</tt>&nbsp;<em>dev_style</em>&nbsp;: how <tt>/dev</tt> is
 handled on this system. 0 means a static <tt>/dev</tt>, 1 means
 devtmpfs but not automounted by the kernel at boot time, and 2 means
@@ -130,8 +129,16 @@ the arguments given to <em>rc.init</em>. </li>
 as pid 1 and has spawned its early services - at least the catch-all logger,
 and the other services, including the early getty if it has been defined, are
 started in parallel and will be ready instantly. <em>rc.init</em> can then
-perform <em>stage 2</em> of the initialization process, i.e. the initialization
-sequence per se.
+perform <em>stage 2</em> of the initialization process, i.e. the handoff to
+the service manager.
+</p>
+
+<h2> Exit codes </h2>
+
+<p>
+ <tt>s6-linux-init</tt> never exits. It spawns the <em>rc.init</em> script
+and execs into <a href="//skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>,
+which runs forever until the machine stops or reboots.
 </p>
 
 <h2> Notes </h2>
diff --git a/doc/why.html b/doc/why.html
index 43c7f84..8898cbd 100644
--- a/doc/why.html
+++ b/doc/why.html
@@ -117,7 +117,7 @@ needs to perform before executing into <tt>s6-svscan</tt> is a bit
 tricky. It can be scripted, but it's not easy, and since it's so early
 in the lifetime of the machine, there's no safety net at all (the
 supervision tree itself, and the early getty, are supposed to be the
-safety net! and they're not there yet). So it's better to automate
+safety net, and they're not there yet). So it's better to automate
 these operations.
 </p>
 
-- 
cgit v1.3.1