Add hotplug(4) man page, with help from jmc@.

1 files changed, 104 insertions, 0 deletions

diff --git a/share/man/man4/hotplug.4 b/share/man/man4/hotplug.4
new file mode 100644
index 00000000000..abf8b82c877
--- /dev/null
+++ b/share/man/man4/hotplug.4
@@ -0,0 +1,104 @@
+.\"	$OpenBSD: hotplug.4,v 1.1 2004/05/30 08:35:19 grange Exp $
+.\"
+.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd March 30, 2004
+.Dt HOTPLUG 4
+.Os
+.Sh NAME
+.Nm hotplug
+.Nd devices hot plugging
+.Sh SYNOPSIS
+.Cd "pseudo-device hotplug 1"
+.Pp
+.Fd #include <sys/types.h>
+.Fd #include <sys/device.h>
+.Fd #include <sys/hotplug.h>
+.Sh DESCRIPTION
+The
+.Nm
+pseudo-device passes device attachment and detachment events to
+userland.
+When a device attaches or detaches, the corresponding event is queued.
+The events can then be obtained from the queue through the
+.Xr read 2
+call on the
+.Pa /dev/hotplug
+device file.
+Once an event has been read, it's deleted from the queue.
+The event queue has a limited size and if it's full all new events will be
+dropped.
+Each event is described with the following structure declared in the
+.Aq Pa sys/hotplug.h
+header file:
+.Bd -literal -offset indent
+struct hotplug_event {
+	int		he_type;	/* event type		*/
+	enum devclass	he_devclass;	/* device class		*/
+	char		he_devname[16];	/* device name		*/
+};
+
+.Ed
+The
+.Va he_type
+field describes the event type and can be either
+.Dv HOTPLUG_DEVAT
+for device attachment or
+.Dv HOTPLUG_DEVDT
+for detachment.
+The
+.Va he_devclass
+field describes the device class.
+All device classes can be found in the
+.Aq Pa sys/device.h
+header file:
+.Bd -literal -offset indent
+enum devclass {
+	DV_DULL,	/* generic, no special info */
+	DV_CPU,		/* CPU (carries resource utilization) */
+	DV_DISK,	/* disk drive (label, etc) */
+	DV_IFNET,	/* network interface */
+	DV_TAPE,	/* tape device */
+	DV_TTY		/* serial line interface */
+};
+
+.Ed
+The
+.Va he_devname
+is a device name including unit number, e.g.\&
+.Pa sd1 .
+.Pp
+Only one structure can be read per call.
+If there are no events in the queue, the
+.Xr read 2
+call will block until an event appears.
+.Sh DIAGNOSTICS
+.Bl -diag
+.It "hotplug: event lost, queue full"
+New events will be dropped until pending events aren't read.
+.El
+.Sh SEE ALSO
+.Xr read 2 ,
+.Xr hotplugd 8
+.Sh HISTORY
+The
+.Nm
+device first appeared in
+.Ox 3.6 .
+.Sh AUTHORS
+The
+.Nm
+driver was written by
+.An Alexander Yurchenko Aq grange@openbsd.org .