plug-and-play-event-handler 1 user commands nosh
plug-and-play-event-handler adapt plug and play socket events to a handler API
`plug-and-play-event-handler` prog

## Description

There are two APIs for plug-and-play managent on Linux: One can specify a program to be run via the `/proc/sys/kernel/hotplug` file, or one can listen for plug-and-play event messages from the kernel via a netlink socket. The former has several problems:

- The kernel makes no effort not to run multiple instances of the program at once. This can result in PaP events being handled out of order, if it takes longer to process some events than others. There are also no limits on the number of instances of the plug-in that are run.

- There is no service control mechanism. The plug-in cannot be enabled/disabled started/stopped using normal dæmon management tools. There are no ways to set resource limits or to control privileges. The startup/shutdown systems are not synchronized with them.

- The programs are run as unmanaged children of process #1. They are orphaned in the process tree, and not tracked by any service managers.

`plug-and-play-event-handler` adapts plug-ins for the former to operate with the latter mechanism.

It expects file descriptor 3 to be a datagram socket that has been set up to listen for incoming datagrams. (Usually this will be a netlink datagram, or raw, socket set up with with netlink-datagram-socket-listen 1. But `plug-and-play-event-handler` only requires that it be a datagram socket of some kind; and other socket types can theoretically be used.) It loops forever, reading datagrams. For each datagram read, it spawns `prog` as a child process, with the event message settings in its environment variables, as such plug-ins expect.

It serializes invocations of `prog`. It will not read the next datagram until the previous instance has exited. If it is sent the "graceful" termination signals `SIGTERM`, `SIGINT`, or `SIGHUP` it waits for the child to exit before it exits itself.

## Bugs

Although not strictly speaking a bug in this program, if the receive buffer size for the netlink socket is too small, the kernel can run out of buffers while enqueuing plug and play events. It does not recover from such a situation, leaving the plug and play manager broken until the next reboot. To avoid this, use the --receive-buffer-size option to netlink-datagram-socket-listen 1 and pass a large size.

## Author

Jonathan de Boyne Pollard