From 3b64cecd5c2923c9f448c44fd0decb39d2e65791 Mon Sep 17 00:00:00 2001
From: ed <ed@FreeBSD.org>
Date: Sun, 28 Sep 2008 20:15:45 +0000
Subject: 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().
---
 share/man/man3/makedev.3 | 90 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 share/man/man3/makedev.3

(limited to 'share/man/man3/makedev.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
-- 
cgit v1.1