191 lines
6.5 KiB
Groff
191 lines
6.5 KiB
Groff
.\" $NetBSD: disklabel.9,v 1.8 1999/03/16 00:40:47 garbled 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 *clp"
|
|
.Ft int
|
|
.Fn writedisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp"
|
|
.Ft int
|
|
.Fn setdisklabel "struct disklabel *olp" "struct disklabel *nlp" "u_long openmask" "struct cpu_disklabel *clp"
|
|
.Ft int
|
|
.Fn bounds_check_with_label "struct buf *bp" "struct disklabel *lp" "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,
|
|
.Fn readdisklabel
|
|
may resort to constructing a label from other machine-dependent information
|
|
using the provided buffer passed in the
|
|
.Fa clp
|
|
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 clp
|
|
.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 ,
|
|
sets the
|
|
.Dv B_ERROR
|
|
flag in
|
|
.Dq Va b_flags ,
|
|
and returns -1.
|
|
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 ,
|
|
the
|
|
.Dv B_ERROR
|
|
flag is set in
|
|
.Dq Va b_flags ,
|
|
and -1 is returned.
|
|
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.
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr disklabel 5 ,
|
|
.Xr disklabel 8
|