disklabel manipulation routines page from netbsd w/ some adjustments; no history section

1 files changed, 195 insertions, 0 deletions

diff --git a/share/man/man9/disklabel.9 b/share/man/man9/disklabel.9
new file mode 100644
index 00000000000..9fc39f64d75
--- /dev/null
+++ b/share/man/man9/disklabel.9
@@ -0,0 +1,195 @@
+.\"	$NetBSD: disklabel.9,v 1.7 1999/03/06 22:09:29 mycroft Exp $
+.\"
+.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Paul Kranenburg.
+.\"
+.\" 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd December 26, 1996
+.Dt DISKLABEL 9
+.Os
+.Sh NAME
+.Nm disklabel ,
+.Nm readdisklabel ,
+.Nm writedisklabel ,
+.Nm setdisklabel ,
+.Nm bounds_check_with_label
+.Nd disk label management routines
+.Sh SYNOPSIS
+.Ft char *
+.Fn readdisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *osdep" "int spoofonly"
+.Ft int
+.Fn writedisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *osdep"
+.Ft int
+.Fn setdisklabel "struct disklabel *olp" "struct disklabel *nlp" "u_long openmask" "struct cpu_disklabel *osdep"
+.Ft int
+.Fn bounds_check_with_label "struct buf *bp" "struct disklabel *lp" "struct cpu_disklabel *osdep" "int wlabel"
+.Sh DESCRIPTION
+This collection of routines provides a disklabel management interface to
+kernel device drivers.
+These routines are classified as machine- or architecture-dependent because
+of restrictions imposed by the machine architecture and boot-strapping code
+on the location of the label, or because cooperation with other operating
+systems requires specialized conversion code.
+.Pp
+.Fn readdisklabel
+attempts to read a disklabel from the device identified by
+.Fa dev ,
+using the device strategy routine passed in
+.Fa strat .
+Note that a buffer structure is required to pass to the strategy routine;
+it needs to be acquired and parametrized for the intended I/O operation,
+and disposed of when the operation has completed.
+Some fields in the in the disklabel passed in
+.Fa lp
+may be pre-initialized by the caller in order to meet device driver
+requirements for the I/O operation initiated to get to the disklabel data
+on the medium.
+In particular, the field
+.Dq d_secsize ,
+if non-zero, is used by
+.Fn readdisklabel
+to get an appropriately sized buffer to pass to the device strategy routine.
+Unspecified fields in
+.Fa lp
+should be set to zero.
+If the medium does not contain a native disklabel that can be read in directly
+or
+.Fa spoofonly
+argument is a true value,
+.Fn readdisklabel
+may resort to constructing a label from other machine-dependent information
+using the provided buffer passed in the
+.Fa osdep
+argument.
+If a disk label can not be found or constructed, a string containing
+an approximated description of the failure mode is returned.
+Otherwise the
+.Dv NULL
+string is returned.
+.Pp
+.Fn writedisklabel
+stores disk label information contained in the disk label structure given by
+.Fa lp
+on the device identified by
+.Fa dev .
+Like
+.Fn readdisklabel ,
+it acquires and sets up an I/O buffer to pass to the strategy routine
+.Fa strat .
+.Fn writedisklabel
+may elect to do a machine-dependent conversion of the native disk label
+structure
+.Po
+using the buffer pointed at by
+.Fa osdep
+.Pc ,
+to store the disk label onto the medium in a format complying with
+architectural contraints.
+.Fn writedisklabel
+returns 0 on success and
+.Dv EINVAL
+if the disk label specifies invalid or unconvertable values.
+Otherwise, any error condition reported by the device strategy routine
+in the buffer's
+.Dq Va b_error
+field is returned.
+.Pp
+.Fn setdisklabel
+checks a proposed new disk label passed in
+.Fa nlp
+for some amount of basic sanity.
+This includes a check on attempts to
+change the location, or reduce the size, of an existing disk partition
+that is currently in use by the system.
+The current disposition of the disk partitions is made available through
+.Fa olp
+and
+.Fa openmask ,
+which provide, respectively, the existing disk label and a bit mask
+identifying the partitions that are currently in use.
+Failure to pass on
+.Dq basic sanity ,
+results in a
+.Dv EINVAL
+return value, while a vetoed update of the partition layout is signaled by a
+.Dv EBUSY
+return value.
+Otherwise, 0 is returned.
+.Pp
+.Fn bounds_check_with_label
+is used to check whether a device transfer described by
+.Fa bp
+to the device identified by
+.Fa dev ,
+is properly contained within a disk partition of the disk with label
+.Fa lp .
+If this check fails,
+.Fn bounds_check_with_label
+sets the buffer's
+.Dq Va b_error
+field to
+.Dv EINVAL
+and sets the
+.Dv B_ERROR
+flag in
+.Dq Va b_flags .
+If the argument
+.Fa wlabel
+is zero, and the transfer is a write operation, a check is done if the transfer
+would overwrite
+.Pq a portion of
+the disklabel area on the medium.
+If that is the case,
+.Dv EROFS
+is set in
+.Dq Va b_error
+and the
+.Dv B_ERROR
+flag is set in
+.Dq Va b_flags .
+Note that
+.Fa wlabel
+should be set to a non-zero value if the intended operation is expected to
+install or update the disk label.
+Programs that intend to do so using the raw device interface should notify
+the driver by using a
+.Dv DIOCWLABEL
+ioctl function.
+Zero value is returned if any of the bound checks failed or
+transfer was attempted exactly at the end of disk partition.
+Otherwise the value of 1 is returned.
+.Pp
+.Sh SEE ALSO
+.Xr disklabel 5 ,
+.Xr disklabel 8 ,
+.Xr fdisk 8