From 7b9931e6403db6aeabb0ccc26e126dcf74cf3c03 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 10 Jan 2023 01:33:51 +0000 Subject: Add doc for s6-instance-list and s6-instance-status Signed-off-by: Laurent Bercot --- COPYING | 2 +- NEWS | 3 +++ doc/index.html | 2 ++ doc/instances.html | 26 +++++++++--------- doc/s6-instance-control.html | 1 + doc/s6-instance-list.html | 60 +++++++++++++++++++++++++++++++++++++++++ doc/s6-instance-status.html | 64 ++++++++++++++++++++++++++++++++++++++++++++ doc/upgrade.html | 1 + 8 files changed, 146 insertions(+), 13 deletions(-) create mode 100644 doc/s6-instance-list.html create mode 100644 doc/s6-instance-status.html diff --git a/COPYING b/COPYING index 0dfd4b1..08c9298 100644 --- a/COPYING +++ b/COPYING @@ -1,4 +1,4 @@ -Copyright (c) 2011-2022 Laurent Bercot +Copyright (c) 2011-2023 Laurent Bercot Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above diff --git a/NEWS b/NEWS index fe1418e..b6f8b5b 100644 --- a/NEWS +++ b/NEWS @@ -9,6 +9,9 @@ In 2.11.2.0 as the third argument to ./finish. - The 1-second service restart delay can now only be skipped when the service is ready. + - Implementation of instances! New programs: s6-instance-maker, +s6-instance-create, s6-instance-delete, s6-instance-control, +s6-instance-status, s6-instance-list. In 2.11.1.2 diff --git a/doc/index.html b/doc/index.html index 8b87d71..e41fa67 100644 --- a/doc/index.html +++ b/doc/index.html @@ -279,6 +279,8 @@ synchronization.
  • The s6-instance-create program
  • The s6-instance-delete program
  • The s6-instance-control program
    • +
  • The s6-instance-status program
    • +
  • The s6-instance-list program

    • Timed lock acquisition

    diff --git a/doc/instances.html b/doc/instances.html index 78b3cd5..8f49923 100644 --- a/doc/instances.html +++ b/doc/instances.html @@ -65,18 +65,16 @@ supervision tree - the instanced service is an instances.
  • Create and delete instances at will with the s6-instance-create and -s6-instance-delete programs. Instances -are regular supervised processes; you can control them with -s6-instance-control. These tools are -online: they work with live service directories (i.e. that are -being supervised by s6-supervise). They -are really syntactic sugar around the -s6-svlink, -s6-svunlink and -s6-svc programs; they provide you with the -same functionality but allow you to address individual instances via the -instanced service name (the service directory running the nested -supervision tree) and the instance name.
    • +s6-instance-delete programs; you +can list all the available instances with +s6-instance-list. + These tools are online: they work with live service directories, +i.e. that are being supervised by s6-supervise. +
  • Instances are regular supervised processes. You can control individual +instances with s6-instance-control, +and check their status with +s6-instance-status. These tools +are online as well.

    • Internal workings

    @@ -101,6 +99,10 @@ process running on instance/name, and the instance may be up or not depending on the given options.
  • s6-instance-control is syntactic sugar around s6-svc on instance/name.
    • +
  • s6-instance-status is syntactic sugar +around s6-svstat on instance/name.
    • +
  • s6-instance-list is roughly equivalent +to ls -1 instance .
  • s6-instance-delete is syntactic sugar around s6-svunlink on instance/name.
    • diff --git a/doc/s6-instance-control.html b/doc/s6-instance-control.html index b52819a..b58fb18 100644 --- a/doc/s6-instance-control.html +++ b/doc/s6-instance-control.html @@ -54,6 +54,7 @@ the name instance. understood by s6-svc.

    +

    In fact, s6-instance-control is nothing more than a call to s6-svc on the service directory representing the name instance. It is syntactic sugar so diff --git a/doc/s6-instance-list.html b/doc/s6-instance-list.html new file mode 100644 index 0000000..69cb342 --- /dev/null +++ b/doc/s6-instance-list.html @@ -0,0 +1,60 @@ + + + + + + s6: the s6-instance-list program + + + + + + +

    +s6
    +Software
    +skarnet.org +

    + +

    The s6-instance-list program

    + +

    +s6-instance-list gives a list of all currently created instances of an +instanced service. +

    + +

    Interface

    + +
    +     s6-instance-list servicedir
+
    + +
      +
    • s6-instance-list expects a running, supervised +instanced service in servicedir, +as well as an existing instance of this service named name.
      • +
    • It prints to stdout, one per line, the names of all existing instances of servicedir, i.e. +the ones that have been created and not deleted. It does not matter if the instances are +up or down; if they've been created and not deleted, they're printed.
      • +
    • It exits 0.
      • +
    + +

    Exit codes

    + +
      +
    • 0: success
      • +
    • 100: wrong usage
      • +
    • 111: system call failed
      • +
    + +

    Notes

    + +
      +
    • The list is unsorted, the instance names are printed in an unspecified order.
      • +
    • You can use s6-instance-list to script commands that handle sets of instances. +For instance, to get the status of all the instances of a given service, you could write: + for i in `s6-instance-list service` ; do printf "%s: " $i ; s6-instance-status service $i ; done
      • +
    + + + diff --git a/doc/s6-instance-status.html b/doc/s6-instance-status.html new file mode 100644 index 0000000..4bc6b75 --- /dev/null +++ b/doc/s6-instance-status.html @@ -0,0 +1,64 @@ + + + + + + s6: the s6-instance-status program + + + + + + +

    +s6
    +Software
    +skarnet.org +

    + +

    The s6-instance-status program

    + +

    +s6-instance-status gives the status of a running instance of an +instanced service, as a short human-readable +summary or programmatically parsable output. +

    + +

    Interface

    + +
    +     s6-instance-status [ -uwNrpest | -o up,wantedup,normallyup,ready,paused,pid,exitcode,signal,signum,updownsince,readysince,updownfor,readyfor ] [ -n ] servicedir name
+
    + +
      +
    • s6-instance-status expects a running, supervised +instanced service in servicedir, +as well as an existing instance of this service named name.
      • +
    • It prints information to stdout about the monitored instance of servicedir named name.
      • +
    • It exits 0.
      • +
    + +

    Exit codes

    + +
      +
    • 0: success
      • +
    • 100: wrong usage
      • +
    • 111: system call failed
      • +
    + +

    Options

    + +

    + The options are exactly the same as the ones understood by s6-svstat. +

    + +

    + In fact, s6-instance-status is +nothing more than a call to s6-svstat on the service +directory representing the name instance. It is syntactic sugar so +the user does not have to depend on the internal representation of instances +and the location of instances' service directories. +

    + + + diff --git a/doc/upgrade.html b/doc/upgrade.html index 077b9d8..7afba07 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -27,6 +27,7 @@ dependency bumped to 2.13.0.0. optional dependency bumped to 0.2.0.2.
  • execline recommended dependency bumped to 2.9.1.0.
    • +
  • New feature: implementation of instances.

    • in 2.11.1.2

    -- cgit v1.2.3