Several documentation fixups related to device minor/major numbers:

- Document the minor(3), major(3) and makedev(3) macro's. They also
  apply to umajor() and uminor() in the kernel, but hopefully we'll sort
  that out one day.

- Briefly dev2unit() inside the make_dev(9) manual page, since this is
  now the preferred macro to obtain character device unit numbers inside
  the kernel.

- Remove the device_ids(9) manual page. It contains highly inaccurate
  information, such as a description of the nonexistent major().

5 files changed, 97 insertions, 82 deletions

diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile
index 2513a60..13c5e14 100644
--- a/share/man/man3/Makefile
+++ b/share/man/man3/Makefile
@@ -8,6 +8,7 @@ MAN=		assert.3 \
 		end.3 \
 		fpgetround.3 \
 		intro.3 \
+		makedev.3 \
 		${PTHREAD_MAN} \
 		queue.3 \
 		siginfo.3 \
@@ -36,6 +37,8 @@ MLINKS+=	fpgetround.3 fpgetmask.3 \
 		fpgetround.3 fpsetmask.3 \
 		fpgetround.3 fpsetprec.3 \
 		fpgetround.3 fpsetround.3
+MLINKS+=	makedev.3 major.3 \
+		makedev.3 minor.3
 MLINKS+=	${PTHREAD_MLINKS}
 MLINKS+=	queue.3 LIST_EMPTY.3 \
 		queue.3 LIST_ENTRY.3 \
diff --git a/share/man/man3/makedev.3 b/share/man/man3/makedev.3
new file mode 100644
index 0000000..b4a1391
--- /dev/null
+++ b/share/man/man3/makedev.3
@@ -0,0 +1,90 @@
+.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd September 28, 2008
+.Dt MAKEDEV 3
+.Os
+.Sh NAME
+.Nm makedev ,
+.Nm major ,
+.Nm minor
+.Nd device number conversion
+.Sh SYNOPSIS
+.In sys/types.h
+.Ft dev_t
+.Fn makedev "int major" "int minor"
+.Ft int
+.Fn major "dev_t dev"
+.Ft int
+.Fn minor "dev_t dev"
+.Sh DESCRIPTION
+The
+.Fn makedev
+macro allows a unique device number to be generated based on its
+.Fa major
+and
+.Fa minor
+number.
+The
+.Fn major
+and
+.Fn minor
+macros can be used to obtain the original numbers from the device number
+.Fa dev .
+.Pp
+In previous implementations of
+.Fx
+all block and character devices were uniquely identified by a pair of
+major and minor numbers.
+The major number referred to a certain device class (e.g. disks, TTYs)
+while the minor number identified an instance within the device class.
+Later versions of
+.Fx
+automatically generate a unique device number for each character device
+visible in
+.Pa /dev/ .
+These numbers are not divided in device classes.
+.Pp
+On
+.Fx
+these macros are only used by utilities that need to exchange numbers
+with other operating systems that may use different encodings for
+.Vt dev_t ,
+but also applications that present these numbers to the user in a more
+conventional way.
+.Sh RETURN VALUES
+The
+.Fn major
+macro returns a device major number that has a value between 0 and 255.
+The
+.Fn minor
+macro returns a device minor number whose value can span the complete
+range of an
+.Vt int .
+.Sh SEE ALSO
+.Xr devfs 5 ,
+.Xr devtoname 3 ,
+.Xr mknod 2
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index cc600ee..2705b6b 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -82,7 +82,6 @@ MAN=	accept_filter.9 \
 	device_get_sysctl.9 \
 	device_get_unit.9 \
 	DEVICE_IDENTIFY.9 \
-	device_ids.9 \
 	device_printf.9 \
 	DEVICE_PROBE.9 \
 	device_probe_and_attach.9 \
@@ -566,10 +565,6 @@ MLINKS+=device_get_state.9 device_busy.9 \
 	device_get_state.9 device_unbusy.9
 MLINKS+=device_get_sysctl.9 device_get_sysctl_ctx.9 \
 	device_get_sysctl.9 device_get_sysctl_tree.9
-MLINKS+=device_ids.9 major.9 \
-	device_ids.9 minor.9 \
-	device_ids.9 umajor.9 \
-	device_ids.9 uminor.9
 MLINKS+=device_quiet.9 device_is_quiet.9 \
 	device_quiet.9 device_verbose.9
 MLINKS+=device_set_desc.9 device_get_desc.9 \
diff --git a/share/man/man9/device_ids.9 b/share/man/man9/device_ids.9
deleted file mode 100644
index fc7c9fd..0000000
--- a/share/man/man9/device_ids.9
+++ /dev/null
@@ -1,75 +0,0 @@
-.\"
-.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice(s), this list of conditions and the following disclaimer as
-.\"    the first lines of this file unmodified other than the possible
-.\"    addition of one or more copyright notices.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice(s), this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
-.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-.\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
-.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
-.\" DAMAGE.
-.\"
-.\" $FreeBSD$
-.\"
-.Dd June 22, 2004
-.Dt DEVICE_IDS 9
-.Os
-.Sh NAME
-.Nm device_ids ,
-.Nm major ,
-.Nm minor ,
-.Nm umajor ,
-.Nm uminor
-.Nd "calculate device ids"
-.Sh SYNOPSIS
-.In sys/types.h
-.In sys/systm.h
-.Ft int
-.Fn major "struct cdev *dev"
-.Ft int
-.Fn minor "struct cdev *dev"
-.Ft int
-.Fn umajor "dev_t id"
-.Ft int
-.Fn uminor "dev_t id"
-.Sh DESCRIPTION
-The
-.Nm
-family of functions take either the raw device ID,
-.Fa id ,
-or a pointer to the device structure,
-.Fa dev ,
-and return the integer
-value that is the major or minor device ID as requested.
-.Pp
-The actual major and minor device IDs are values masked from of the raw device ID.
-For details on the actual calculations used to determine the major or minor IDs see
-the actual source in
-.Pa kern_conf.c .
-.Sh RETURN VALUES
-An integer greater than zero and less than
-.Dv NUMCDEVSW .
-.Fn major
-and
-.Fn minor
-will return
-.Dv NODEV
-if the device is invalid.
-.Sh AUTHORS
-This manual page was written by
-.An Chad David Aq davidc@acns.ab.ca .
diff --git a/share/man/man9/make_dev.9 b/share/man/man9/make_dev.9
index 7eb1ecd..b39ca8b 100644
--- a/share/man/man9/make_dev.9
+++ b/share/man/man9/make_dev.9
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 8, 2008
+.Dd September 28, 2008
 .Os
 .Dt MAKE_DEV 9
 .Sh NAME
@@ -186,7 +186,9 @@ Both fields are of type
 These are designed to replace the
 .Fa unit
 argument to
-.Fn make_dev .
+.Fn make_dev ,
+which can be obtained with
+.Fn dev2unit .
 .Pp
 The
 .Fn destroy_dev