diff options
author | ed <ed@FreeBSD.org> | 2008-09-28 20:15:45 +0000 |
---|---|---|
committer | ed <ed@FreeBSD.org> | 2008-09-28 20:15:45 +0000 |
commit | 3b64cecd5c2923c9f448c44fd0decb39d2e65791 (patch) | |
tree | 8b91d1629ac6a37f72cebf109a4816f35056fa38 | |
parent | 954d43d96810c30de5084004d0e56905298a9378 (diff) | |
download | FreeBSD-src-3b64cecd5c2923c9f448c44fd0decb39d2e65791.zip FreeBSD-src-3b64cecd5c2923c9f448c44fd0decb39d2e65791.tar.gz |
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().
-rw-r--r-- | ObsoleteFiles.inc | 6 | ||||
-rw-r--r-- | share/man/man3/Makefile | 3 | ||||
-rw-r--r-- | share/man/man3/makedev.3 | 90 | ||||
-rw-r--r-- | share/man/man9/Makefile | 5 | ||||
-rw-r--r-- | share/man/man9/device_ids.9 | 75 | ||||
-rw-r--r-- | share/man/man9/make_dev.9 | 6 |
6 files changed, 103 insertions, 82 deletions
diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc index ec37d0b..31904e3 100644 --- a/ObsoleteFiles.inc +++ b/ObsoleteFiles.inc @@ -14,6 +14,12 @@ # The file is partitioned: OLD_FILES first, then OLD_LIBS and OLD_DIRS last. # +# 20080928: removal of inaccurate device_ids(9) manual page +OLD_FILES+=usr/share/man/man9/device_ids.9.gz +OLD_FILES+=usr/share/man/man9/major.9.gz +OLD_FILES+=usr/share/man/man9/minor.9.gz +OLD_FILES+=usr/share/man/man9/umajor.9.gz +OLD_FILES+=usr/share/man/man9/uminor.9.gz # 20080917: removal of manpage for axed kernel primitive suser(9) OLD_FILES+=usr/share/man/man9/suser.9.gz OLD_FILES+=usr/share/man/man9/suser_cred.9.gz 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 |