diff options
Diffstat (limited to 'doc/s6-uevent-listener.html')
| -rw-r--r-- | doc/s6-uevent-listener.html | 42 |
1 files changed, 25 insertions, 17 deletions
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> |