diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2021-08-30 19:11:44 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2021-08-30 19:11:44 +0000 |
| commit | 691c69e626e4ceb85567a5288348bd04378fd410 (patch) | |
| tree | 9ae1c3f2c2984aafa2b9caf7987fe0011fcf6828 /doc | |
| parent | 1719a60278cf36558b568349c0c9f9b5eb91c999 (diff) | |
| download | s6-691c69e626e4ceb85567a5288348bd04378fd410.tar.xz | |
s6-svlink, s6-svunlink, .h changes
Renamed from s6-svdir-(un)link.
Doc added. Full functionality added.
Still need to be tested.
Unrelated: .h names simplified.
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 2 | ||||
| -rw-r--r-- | doc/libs6/fdholder.html (renamed from doc/libs6/s6-fdholder.html) | 6 | ||||
| -rw-r--r-- | doc/libs6/index.html | 4 | ||||
| -rw-r--r-- | doc/libs6/lock.html (renamed from doc/libs6/s6lock.html) | 2 | ||||
| -rw-r--r-- | doc/s6-svlink.html | 111 | ||||
| -rw-r--r-- | doc/s6-svunlink.html | 90 | ||||
| -rw-r--r-- | doc/upgrade.html | 4 |
7 files changed, 213 insertions, 6 deletions
diff --git a/doc/index.html b/doc/index.html index d3e7e6f..ef0d786 100644 --- a/doc/index.html +++ b/doc/index.html @@ -174,6 +174,8 @@ a user interface to control those processes and monitor service states. <li><a href="s6-svok.html">The <tt>s6-svok</tt> program</a></li> <li><a href="s6-svstat.html">The <tt>s6-svstat</tt> program</a></li> <li><a href="s6-svperms.html">The <tt>s6-svperms</tt> program</a></li> +<li><a href="s6-svlink.html">The <tt>s6-svlink</tt> program</a></li> +<li><a href="s6-svunlink.html">The <tt>s6-svunlink</tt> program</a></li> <li><a href="s6-svwait.html">The <tt>s6-svwait</tt> program</a></li> <li><a href="s6-svlisten1.html">The <tt>s6-svlisten1</tt> program</a></li> <li><a href="s6-svlisten.html">The <tt>s6-svlisten</tt> program</a></li> diff --git a/doc/libs6/s6-fdholder.html b/doc/libs6/fdholder.html index 4a2fb25..c874805 100644 --- a/doc/libs6/s6-fdholder.html +++ b/doc/libs6/fdholder.html @@ -17,10 +17,10 @@ <a href="//skarnet.org/">skarnet.org</a> </p> -<h1> The <tt>s6-fdholder</tt> library interface </h1> +<h1> The <tt>fdholder</tt> library interface </h1> <p> - The <tt>s6-fdholder</tt> library provides an API for clients + The <tt>fdholder</tt> library provides an API for clients wanting to communicate with a <a href="../s6-fdholderd.html">s6-fdholderd</a> daemon. </p> @@ -28,7 +28,7 @@ wanting to communicate with a <h2> Programming </h2> <p> - Check the <tt>s6/s6-fdholder.h</tt> header for the + Check the <tt>s6/fdholder.h</tt> header for the exact function prototypes. </p> diff --git a/doc/libs6/index.html b/doc/libs6/index.html index 2f93493..1db2e5e 100644 --- a/doc/libs6/index.html +++ b/doc/libs6/index.html @@ -65,9 +65,9 @@ provides functions to check credentials against configuration files. </li> functions to subscribe to fifodirs and be notified of events. </li> <li> The <a href="ftrigw.html">s6/ftrigw.h</a> header provides functions to manage fifodirs and send notifications to them. </li> - <li> The <a href="s6lock.html">s6/s6lock.h</a> header provides + <li> The <a href="lock.html">s6/lock.h</a> header provides functions to acquire locks with a timeout. </li> - <li> The <a href="s6-fdholder.html">s6/s6-fdholder.h</a> header provides + <li> The <a href="fdholder.html">s6/fdholder.h</a> header provides functions to communicate with a <a href="../s6-fdholderd.html">s6-fdholderd</a> server and exchange file descriptors with it. </li> diff --git a/doc/libs6/s6lock.html b/doc/libs6/lock.html index 049ed44..1cc896d 100644 --- a/doc/libs6/s6lock.html +++ b/doc/libs6/lock.html @@ -31,7 +31,7 @@ poll-free locks that can timeout during attempted acquisition. <h2> Programming </h2> <ul> - <li> Check the <tt>s6/s6lock.h</tt> header + <li> Check the <tt>s6/lock.h</tt> header for the prototypes. The functions documented here are often simplified macros, for instance relying on the STAMP global variable to hold the current time. Fully reentrant functions with more control diff --git a/doc/s6-svlink.html b/doc/s6-svlink.html new file mode 100644 index 0000000..2e03eec --- /dev/null +++ b/doc/s6-svlink.html @@ -0,0 +1,111 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-svlink program</title> + <meta name="Description" content="s6: the s6-svlink program" /> + <meta name="Keywords" content="s6 command s6-svlink supervision service start scandir servicedir" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The s6-svlink program </h1> + +<p> + <tt>s6-svlink</tt> creates, in a <a href="scandir.html">scan +directory</a>, a symlink to a <a href="servicedir.html">service +directory</a>, and notifies <a href="s6-svscan.html">s6-svscan</a> +that a new service has been registered. It waits until a +<a href="s6-supervise.html">s6-supervise</a> supervisor process has +been spawned to manage the new service, then exits. +</p> + +<p> + The point of <tt>s6-svlink</tt> is to help integrate existing +service directories into an existing service manager sequence and +eliminating race conditions. +</p> + +<h2> Interface </h2> + +<pre> + s6-svlink [ -d | -D ] [ -P ] [ -f ] [ -t <em>timeout</em> ] <em>scandir</em> <em>servicedir</em> [ <em>name</em> ] +</pre> + +<ul> + <li> <tt>s6-svlink</tt> expects a running <a href="s6-svscan.html">s6-svscan</a> +process on <em>scandir</em> and a fully functional, but unsupervised, +<a href="servicedir.html">service directory</a> in <em>servicedir</em>. </li> + <li> It symlinks <em>servicedir</em> into <em>scandir</em>. The symbolic link +is named <em>name</em>; if no <em>name</em> argument has been given, the name given +to the symbolic link is the basename of <em>servicedir</em>. </li> + <li> It sends a command to <a href="s6-svscan.html">s6-svscan</a> to signal it +that a new service is available. </li> + <li> It waits for a <a href="s6-supervise.html">s6-supervise</a> process to be +spawned on <em>servicedir</em>. </li> + <li> It exits 0. </li> +</ul> + +<h2> Exit codes </h2> + +<ul> + <li> 0: success </li> + <li> 99: timeout while waiting for the supervisor to start </li> + <li> 100: wrong usage </li> + <li> 111: system call failed </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-d</tt> : down. The supervisor will be started, but the service +itself will remain down. Any <em>servicedir</em><tt>/down</tt> file will be +deleted. By default, if neither the <tt>-d</tt> nor <tt>-D</tt> options have +been given, the supervisor auto-starts the service as soon as it runs. </li> + <li> <tt>-D</tt> : down, and stay down. The supervisor will be started, +but the service itself will remain down. A <em>servicedir</em><tt>/down</tt> file +will be created. By default, if neither the <tt>-d</tt> nor <tt>-D</tt> options have +been given, the supervisor auto-starts the service as soon as it runs. </li> + <li> <tt>-P</tt> : public. If <em>servicedir</em><tt>/event</tt> does not +exist, it will be created as public, i.e. anyone will be able to subscribe to +this <a href="fifodir.html">fifodir</a>. By default, it will be created as private, +i.e. only processes running with the same gid as the <a href="s6-svscan.html">s6-svscan</a> +process will be able to susbscribe to it. </li> + <li> <tt>-f</tt> : force permissions. The presence or absence of the <tt>-P</tt> +option (i.e. the public or private state of <em>servicedir</em><tt>/event</tt>) will be +enforced even if <em>servicedir</em><tt>/event</tt> already exists. By default, +<tt>s6-svlink</tt> exits with an error message if <em>servicedir</em><tt>/event</tt> +exists and its public/private state mismatches what is requested. </li> + <li> <tt>-t <em>timeout</em></tt> : if the supervisor has not started +after <em>timeout</em> milliseconds, <tt>s6-svlink</tt> will print a message +to stderr and exit 99. By default, <em>timeout</em> is 0, which means no time +limit. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> Using <tt>s6-svlink</tt> to start services is a suboptimal pattern: it +requires precise manipulations involving use of <a href="s6-ftrigrd.html">s6-ftrigrd</a> +in order to avoid race conditions, so it is relatively expensive. The simpler, +more efficient pattern is to have all the supervisors already started at boot +time, so the existence of the supervisor can be relied on, and starting the +service becomes a trival and instant operation - this is, for instance, how +the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager behaves. +However, it can be difficult to implement this pattern with other services +managers such as OpenRC; in those cases, <tt>s6-svlink</tt>, which starts the +supervisors one at a time, can be used instead. </li> + <li> If <em>servicedir</em> is logged, i.e. <em>servicedir</em><tt>/log</tt> +is also a valid service directory, then <tt>s6-svlink</tt> will wait until +supervisors have been spawned for both the service and its logger. </li> +</ul> + +</body> +</html> diff --git a/doc/s6-svunlink.html b/doc/s6-svunlink.html new file mode 100644 index 0000000..c2ac807 --- /dev/null +++ b/doc/s6-svunlink.html @@ -0,0 +1,90 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6: the s6-svunlink program</title> + <meta name="Description" content="s6: the s6-svunlink program" /> + <meta name="Keywords" content="s6 command s6-svunlink supervision service stop unlink scandir servicedir" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The s6-svunlink program </h1> + +<p> + <tt>s6-svunlink</tt> unlinks a <a href="servicedir.html">service +directory from a <a href="scandir.html">scan directory</a>, then +notify the <a href="s6-svscan.html">s6-svscan</a> that a service has +been unregistered. It waits until the <a href="s6-supervise.html">s6-supervise</a> +supervisor process has disappeared, then exits. +</p> + +<p> + The point of <tt>s6-svunlink</tt> is to help integrate existing +service directories into an existing service manager sequence and +eliminating race conditions. +</p> + +<h2> Interface </h2> + +<pre> + s6-svunlink [ -X ] [ -t <em>timeout</em> ] <em>scandir</em> <em>name</em> +</pre> + +<ul> + <li> <tt>s6-svunlink</tt> expects a running <a href="s6-svscan.html">s6-svscan</a> +process on <em>scandir</em> and a fully functional supervised service on +<a href="servicedir.html">service directory</a> in <em>scandir</em><tt>/</tt><em>name</em>, +which must be a symbolic link to a real directory located somewhere else. </li> + <li> It deletes the <em>scandir</em><tt>/</tt><em>name</em> symlink. </li> + <li> It sends a command to <a href="s6-svscan.html">s6-svscan</a> to signal it +that a service has disappeared. </li> + <li> It waits for the <a href="s6-supervise.html">s6-supervise</a> process +managing the service directory to exit. </li> + <li> It exits 0. </li> +</ul> + +<h2> Exit codes </h2> + +<ul> + <li> 0: success </li> + <li> 100: wrong usage </li> + <li> 111: system call failed </li> +</ul> + +<h2> Options </h2> + +<ul> + <li> <tt>-X</tt> : don't wait. <tt>s6-svunlink</tt> will exit right +away, without waiting for the supervisor to exit first. </li> + <li> <tt>-t <em>timeout</em></tt> : if the supervisor has not exited +after <em>timeout</em> milliseconds, <tt>s6-svlink</tt> will still exit. +The default is 0, meaning no time limit.. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> Using <tt>s6-svlink</tt> to stop services is a suboptimal pattern: +starting and stopping supervisors is a heavier operation than just stopping +services. The simpler, more efficient pattern is to simply perform +<a href="s6-svc.html">s6-svc -dwD <em>scandir</em><tt>/</tt><em>name</em>, +which only commands, and waits for, the death of the service, without +impacting the supervisor. Nevertheless, for symmetry with +<a href="s6-svlink">s6-svlink</a>, this program is provided. </li> + <li> <tt>s6-svunlink</tt> is a destructor; as is, it returns 0 even in +situations that are nominally a failure. For instance, it returns 0 even +if its timeout expires; the rationale is that there is no sensible action +for the user to do if this error is reported. <tt>s6-svunlink</tt> only +reports errors when they uncover a deeper problem in the system. </li> +</ul> + +</body> +</html> diff --git a/doc/upgrade.html b/doc/upgrade.html index 13e8291..44efbb2 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -29,6 +29,10 @@ optional dependency bumped to 0.1.0.2. </li> optional dependency bumped to 2.8.1.0. </li> <li> <a href="s6-svwait.html">s6-svwait</a> now supports the <tt>-r</tt> and <tt>-R</tt> options, to wait for service restarts. </li> + <li> The <tt>s6/lock.h</tt>, <tt>s6/supervise.h</tt> and <tt>s6/fdholder.h</tt> +headers replace their previous versions that had an extra <tt>s6</tt> prefix. </li> + <li> New binaries: <a href="s6-svlink.html">s6-svlink</a> and +<a href="s6-svunlink.html">s6-svunlink</a>. </li> </ul> <h2> in 2.10.0.3 </h2> |