summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2017-04-14 11:09:40 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2017-04-14 11:09:40 +0000
commit6cdac30aed3d1199cbcde2c10e61691af9fc77e3 (patch)
treebe782d5f890637e929b7b0f1ad39a5f33e6be394 /doc
parent30bb26f896777144eb20a620440a97fa5c2be50f (diff)
downloads6-linux-utils-6cdac30aed3d1199cbcde2c10e61691af9fc77e3.tar.xz
Change s6-uevent-listener API: don't spawn, write events to stdout
Diffstat (limited to 'doc')
-rw-r--r--doc/index.html5
-rw-r--r--doc/s6-uevent-listener.html42
-rw-r--r--doc/upgrade.html6
3 files changed, 34 insertions, 19 deletions
diff --git a/doc/index.html b/doc/index.html
index 6627d5b..2e7897d 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -30,7 +30,8 @@
<h3> Requirements </h3>
<ul>
- <li> A Linux-based system with a standard C development environment </li>
+ <li> A Linux-based system with a standard C development environment.
+The Linux kernel must be 3.5 or later. </li>
<li> GNU make, version 3.81 or later </li>
<li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> version
2.5.0.0 or later. It's a build-time requirement. It's also a run-time
@@ -49,7 +50,7 @@ library. </li>
<ul>
<li> The current released version of s6-linux-utils is
-<a href="s6-linux-utils-2.3.0.0.tar.gz">2.3.0.0</a>. </li>
+<a href="s6-linux-utils-2.4.0.0.tar.gz">2.4.0.0</a>. </li>
<li> Alternatively, you can checkout a copy of the
<a href="http://git.skarnet.org/cgi-bin/cgit.cgi/s6-linux-utils/">s6-linux-utils
git repository</a>:
diff --git a/doc/s6-uevent-listener.html b/doc/s6-uevent-listener.html
index 4db31d8..b1908a1 100644
--- a/doc/s6-uevent-listener.html
+++ b/doc/s6-uevent-listener.html
@@ -19,27 +19,29 @@
<h1> The <tt>s6-uevent-listener</tt> program </h1>
<p>
-<tt>s6-uevent-listener</tt> spawns a long-lived helper program.
-It then listens to the netlink interface for uevents (also called
-"hotplug" or "udev" events), and passes those events to the
-helper program's standard input, using a simple format.
+<tt>s6-uevent-listener</tt> listens to the netlink interface for uevents
+(also called "hotplug" or "udev" events), and writes those uevents to
+its standard output, using a simple format.
</p>
<h2> Interface </h2>
<pre>
- s6-uevent-listener [ -v <em>verbosity</em> ] [ -b kbufsz ] <em>prog...</em>
+ s6-uevent-listener [ -v <em>verbosity</em> ] [ -b kbufsz ]
</pre>
<ul>
- <li> s6-uevent-listener spawns <em>prog...</em> with a pipe writing to
-<em>prog</em>' stdin. </li>
<li> s6-uevent-listener binds to the netlink interface and listens for
hotplug events, as the <em>udev</em> program does. </li>
- <li> It transmits event information to <em>prog</em> via the pipe. </li>
- <li> s6-uevent-listener, like <em>prog</em>, is a long-lived program.
+ <li> It writes event information to its stdout. The output contains
+null characters, so a terminal will not display them correctly. To
+properly use s6-uevent-listener, it should be piped into a handler
+program such as
+<a href="s6-uevent-spawner.html">s6-uevent-spawner</a> or
+<a href="mdevd.html">mdevd</a>. </li>
+ <li> s6-uevent-listener is a long-lived program.
When it receives a SIGTERM, it stops listening; it will
-exit as soon as it has flushed its event queue to <em>prog</em>. </li>
+exit as soon as it has flushed its event queue to stdout. </li>
</ul>
<h2> Options </h2>
@@ -58,8 +60,6 @@ the large side). </li>
<h2> Protocol </h2>
<ul>
- <li> <em>prog</em> should read a series of events on its stdin, and exit
-on EOF. </li>
<li> An event is a series of null-terminated strings as they are sent by
the kernel to the netlink; s6-uevent-listener adds a final empty string
(i.e. an additional null character) to mark the end of the series. </li>
@@ -90,11 +90,19 @@ as <a href="http://skarnet.org/software/s6/">s6</a>. </li>
<li> If you are running s6-uevent-listener, <em>prog...</em> should be the
only program handling uevents, which means that
<tt>/proc/sys/kernel/hotplug</tt> should be empty. </li>
- <li> If you want the serialization benefit of the netlink, but still
-want to spawn a program such as <a href="http://busybox.net/">busybox</a>'s
-or <a href="http://landley.net/toybox/">toybox</a>'s <tt>mdev</tt>, use
-<tt><a href="s6-uevent-spawner.html">s6-uevent-spawner</a> mdev</tt> as
-s6-uevent-listener's <em>prog</em>. </li>
+ <li> Examples of valid uses of s6-uevent-listener:
+ <ul>
+ <li> <tt>s6-uevent-listener | s6-uevent-spawner mdev</tt> </li>
+ <li> <tt>s6-uevent-listener | mdevd</tt> </li>
+ <li> Those examples can be made safer by using a supervision system:
+under <a href="http://skarnet.org/software/s6/">s6</a> or
+<a href="http://skarnet.org/software/s6-rc/">s6-rc</a>, write a service
+pipeline where <tt>s6-uevent-listener</tt> is a producer and
+<tt>s6-uevent-spawner mdev</tt> or <tt>mdevd</tt> is a consumer. This
+setup has the advantage, among others, that you can restart the netlink
+listener and the event handler separately. </li>
+ </ul>
+ </li>
</ul>
</body>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index f5c14b0..91a143a 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -18,6 +18,12 @@
<h1> What has changed in s6-linux-utils </h1>
+<h2> in 2.4.0.0 </h2>
+
+<ul>
+ <li> Linux dependency bumped to 3.5. </li>
+</ul>
+
<h2> in 2.3.0.0 </h2>
<ul>