From 6f13cd197540af0bf5e87f87ab0e03548d9c5f64 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 27 Apr 2019 23:27:39 +0000 Subject: Doc fixes --- AUTHORS | 1 + 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 +- src/misc/s6-linux-init-echo.c | 2 +- 12 files changed, 110 insertions(+), 43 deletions(-) diff --git a/AUTHORS b/AUTHORS index 825df2c..f0bd677 100644 --- a/AUTHORS +++ b/AUTHORS @@ -4,3 +4,4 @@ Main author: Thanks to: Colin Booth multiplexd + Luis Ressel 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.

Commands

- 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 Exit codes 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).

    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 @@

    s6-linux-init-hpr triggers the software shutdown procedure, or, with the -f option, it perform an immediate hardware shutdown. -It is normally invoked as /sbin/halt, /sbin/poweroff or -/sbin/reboot. +It is normally invoked through halt, poweroff or +reboot wrappers created by +s6-linux-init-maker.

    Interface

    @@ -33,7 +34,7 @@ It is normally invoked as /sbin/halt, /sbin/poweroff or
      -
    • If the -f option is present, the hardware command is executed immediately.
      • +
    • If the -f option is present, the system is stopped or rebooted immediately.
    • Else, the machine's shutdown procedure is started.
    • The command exits 0; the shutdown procedure happens asynchronously.
    @@ -45,14 +46,6 @@ It is normally invoked as /sbin/halt, /sbin/poweroff or -h, -p or -r options.

    -

    Exit codes

    - -
      -
    • 0: shutdown procedure triggered.
      • -
    • 100: wrong usage, or user does not have root privileges.
      • -
    • 111: system call failed.
      • -
    -

    Options

      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.

      +

      Exit codes

      + +

      + s6-linux-init-logouthookd's exit code does not matter, because +no program uses it. However, here's the list for completeness: +

      + +
        +
      • 0: success, whether or not there was an utmp record to clean up.
        • +
      • 1: connection attempt from a non-root user.
        • +
      • 2: write attempt from a (misprogrammed) client.
        • +
      • 111: system call failed.
        • +
      +

      Notes

        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. If it is not the case, the system will fail to boot. [ -d dev_style ] \ [ -s env_store ] \ [ -e initial_envvar ] ... \ - [ -q ] finalsleeptime + [ -q finalsleeptime ] \ [ -D initdefault ] \ [ -U utmp_user ] \ dir @@ -104,7 +104,7 @@ which have been stored into env_store.
      • rc.shutdown: this script will be run as the shutdown sequence, when the administrator runs the shutdown, halt, poweroff or reboot -command. (As well as init 0, init 6. +command. (As well as init 0, init 6, telinit 0 and telinit 6 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 /sbin/init.

        • When the kernel boots, it may run an initramfs first, but in any -case it then runs the basedir/init script, +case it then runs the /sbin/init script, also known as stage 1. This script is just an execution of the s6-linux-init 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 s6-linux-init-logouthookd page for details.

        -

      • -p initial_path : the value to -set the PATH environment variable to, for all the starting processes. +
      • -p initial_path : 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 +-e option. It is absolutely necessary for execline and s6 @@ -315,8 +317,7 @@ services are:
      • s6-svscan-log: the catch-all logger.
      • s6-linux-init-shutdownd: a service that listens to shutdown commands such as reboot and triggers the software -shutdown procedure. The service is asleep for the whole lifetime of -the machine and uses very few resources.
        • +shutdown procedure.
      • s6-linux-init-runleveld: a service that listens to runlevel change commands such as telinit and calls the runlevel 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 /sbin/shutdown.
        • If the -c option is present, a pending shutdown is cancelled.
          • -
        • Else, it triggers the shutdown procedure.
          • -
        • It exits 0. The shutdown procedure happens asynchronously.
          • +
        • Else, it plans the shutdown procedure at time time.
          • +
        • If a message argument has been given, message is +broadcast to all logged in users (as tracked by utmp).
          • +
        • shutdown exits 0. The shutdown procedure happens asynchronously.

        @@ -42,12 +44,42 @@ It is normally invoked as /sbin/shutdown. interface.

        -

        Exit codes

        +

        + time must follow the following format: +[ now | [+]mins | hh:mm ] +

        + +
          +
        • now means: trigger the shutdown sequence immediately.
          • +
        • hh:mm means: absolute time. Trigger the shutdown sequence when the time +hh:mm occurs. If that time has passed for the day, it will wait for the +next day. hh must have 1 or 2 digits; mm must have 2 digits.
          • +
        • mins or +mins means: relative time. Trigger the shutdown +sequence after mins minutes.
          • +
        + +

        Options

          -
        • 0: shutdown procedure triggered.
          • -
        • 100: wrong usage, or user does not have root privileges.
          • -
        • 111: system call failed.
          • +
        • -a : access control. The shutdown sequence will only be +launched if one of the users listed in /etc/shutdown.allow +is currently logged in (as tracked by utmp). /etc/shutdown.allow +is a text file, one user per line, lines starting with # are comments.
          • +
        • -t sec : at the end of the shutdown sequence, +when it's time to kill all processes, have a "grace time" period +of sec seconds between the SIGTERM and the SIGKILL (to allow processes +receiving SIGTERM to exit cleanly). Default is 3 seconds.
          • +
        • -k : warning only. message will be sent to all +logged in users, but the shutdown sequence will not be triggered.
          • +
        • -h : at the end of the shutdown sequence, halt the system.
          • +
        • -p : 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.)
          • +
        • -r : at the end of the shutdown sequence, reboot the system.
          • +
        • -f : ignored.
          • +
        • -F : ignored.
          • +
        • -c l: cancel a planned shutdown (i.e. cancel the effect of a +previous call to shutdown with a time argument that was not now). +This cannot be used to interrupt a shutdown sequence that has already started.

        Notes

        @@ -60,6 +92,11 @@ the bin/ subdirectory of the target will contain a shutdown symlink to s6-linux-init-shutdown. The bin/ subdirectory should be copied by the administrator into /sbin for full interface compatibility with sysvinit.
        • +
      • The -f and -F options are only accepted for compatibility. +LSB says they are used to advise the system to skip or enforce a fsck +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.
      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.
    -

    Exit codes

    - -
      -
    • 100: wrong usage, or user does not have root privileges.
      • -
    • 111: system call failed.
      • -
    -

    Options

      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 0 and 6 runlevels that respectively halt and reboot the machine.
    +

    Exit codes

    + +
      +
    • 100: wrong usage
      • +
    • 111: system call failed
      • +
    • Else, s6-linux-init-telinit exits with the same exit code +as the runlevel script called with the rl argument.
      • +
    • If rl is 0 or 6, in case of success +s6-linux-init-telinit exits 0, but the system shuts down +immediately as it returns.
      • +
    +

    Notes

      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 @@

      The s6-linux-init-umountall program

      - s6-linux-init-umountall unmounts all the filesystems. + s6-linux-init-umountall unmounts all filesystems.

      Interface

      @@ -29,7 +29,7 @@
        -
      • s6-linux-init-umountall unmounts all partitions according to /proc/mounts. +
      • s6-linux-init-umountall unmounts all filesystems according to /proc/mounts. It processes /proc/mounts 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).
        • @@ -38,6 +38,13 @@ it read-only). s6-linux-init-umountall still attempts to unmount all the other ones.
      +

      Exit codes

      + +

      + s6-linux-init-umountall returns the number of errors it encountered +when attempting to unmount all the filesystems listed in /proc/mounts. +

      +

      Notes

        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.
      • -c basedir : read all its initialization data from basedir. If the data has not indeed been copied to basedir, the system will not boot.
        • -
      • -p initial_path : the value to -set the initial PATH environment variable to. +
      • -p initial_path : the initial value for +the PATH environment variable.
      • -s env_store : the place where to dump kernel environment variables.
        • -
      • -m initial_umask : the value of -the initial file umask.
        • +
      • -m initial_umask : the initial file umask.
      • -d dev_style : how /dev is handled on this system. 0 means a static /dev, 1 means devtmpfs but not automounted by the kernel at boot time, and 2 means @@ -130,8 +129,16 @@ the arguments given to rc.init.
        • 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. rc.init can then -perform stage 2 of the initialization process, i.e. the initialization -sequence per se. +perform stage 2 of the initialization process, i.e. the handoff to +the service manager. +

        + +

        Exit codes

        + +

        + s6-linux-init never exits. It spawns the rc.init script +and execs into s6-svscan, +which runs forever until the machine stops or reboots.

        Notes

        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 s6-svscan 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.

        diff --git a/src/misc/s6-linux-init-echo.c b/src/misc/s6-linux-init-echo.c index d39e649..483efe2 100644 --- a/src/misc/s6-linux-init-echo.c +++ b/src/misc/s6-linux-init-echo.c @@ -10,7 +10,7 @@ int main (int argc, char const *const *argv) { char sep = ' ' ; char donl = 1 ; - PROG = "s6-echo" ; + PROG = "s6-linux-init-echo" ; { subgetopt_t l = SUBGETOPT_ZERO ; for (;;) -- cgit v1.2.3