1.\" $NetBSD: disklabel.9,v 1.13 2008/04/30 13:10:58 martin Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd December 26, 1996 31.Dt DISKLABEL 9 32.Os 33.Sh NAME 34.Nm disklabel , 35.Nm readdisklabel , 36.Nm writedisklabel , 37.Nm setdisklabel , 38.Nm bounds_check_with_label 39.Nd disk label management routines 40.Sh SYNOPSIS 41.Ft char * 42.Fn readdisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp" 43.Ft int 44.Fn writedisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp" 45.Ft int 46.Fn setdisklabel "struct disklabel *olp" "struct disklabel *nlp" "u_long openmask" "struct cpu_disklabel *clp" 47.Ft int 48.Fn bounds_check_with_label "struct buf *bp" "struct disklabel *lp" "int wlabel" 49.Sh DESCRIPTION 50This collection of routines provides a disklabel management interface to 51kernel device drivers. 52These routines are classified as machine- or architecture-dependent because 53of restrictions imposed by the machine architecture and boot-strapping code 54on the location of the label, or because cooperation with other operating 55systems requires specialized conversion code. 56.Pp 57.Fn readdisklabel 58attempts to read a disklabel from the device identified by 59.Fa dev , 60using the device strategy routine passed in 61.Fa strat . 62Note that a buffer structure is required to pass to the strategy routine; 63it needs to be acquired and parameterized for the intended I/O operation, 64and disposed of when the operation has completed. 65Some fields in the disklabel passed in 66.Fa lp 67may be pre-initialized by the caller in order to meet device driver 68requirements for the I/O operation initiated to get to the disklabel data 69on the medium. 70In particular, the field 71.Dq d_secsize , 72if non-zero, is used by 73.Fn readdisklabel 74to get an appropriately sized buffer to pass to the device strategy routine. 75Unspecified fields in 76.Fa lp 77should be set to zero. 78If the medium does not contain a native disklabel that can be read in directly, 79.Fn readdisklabel 80may resort to constructing a label from other machine-dependent information 81using the provided buffer passed in the 82.Fa clp 83argument. 84If a disk label can not be found or constructed, a string containing 85an approximated description of the failure mode is returned. 86Otherwise the 87.Dv NULL 88string is returned. 89.Pp 90.Fn writedisklabel 91stores disk label information contained in the disk label structure given by 92.Fa lp 93on the device identified by 94.Fa dev . 95Like 96.Fn readdisklabel , 97it acquires and sets up an I/O buffer to pass to the strategy routine 98.Fa strat . 99.Fn writedisklabel 100may elect to do a machine-dependent conversion of the native disk label 101structure 102.Po 103using the buffer pointed at by 104.Fa clp 105.Pc , 106to store the disk label onto the medium in a format complying with 107architectural constraints. 108.Fn writedisklabel 109returns 0 on success and 110.Dv EINVAL 111if the disk label specifies invalid or inconvertible values. 112Otherwise, any error condition reported by the device strategy routine 113in the buffer's 114.Dq Va b_error 115field is returned. 116.Pp 117.Fn setdisklabel 118checks a proposed new disk label passed in 119.Fa nlp 120for some amount of basic sanity. 121This includes a check on attempts to 122change the location, or reduce the size, of an existing disk partition 123that is currently in use by the system. 124The current disposition of the disk partitions is made available through 125.Fa olp 126and 127.Fa openmask , 128which provide, respectively, the existing disk label and a bit mask 129identifying the partitions that are currently in use. 130Failure to pass on 131.Dq basic sanity , 132results in a 133.Dv EINVAL 134return value, while a vetoed update of the partition layout is signaled by a 135.Dv EBUSY 136return value. 137Otherwise, 0 is returned. 138.Pp 139.Fn bounds_check_with_label 140is used to check whether a device transfer described by 141.Fa bp 142to the device identified by 143.Fa dev , 144is properly contained within a disk partition of the disk with label 145.Fa lp . 146If this check fails, 147.Fn bounds_check_with_label 148sets the buffer's 149.Dq Va b_error 150field to 151.Dv EINVAL , 152sets the 153.Dv B_ERROR 154flag in 155.Dq Va b_flags , 156and returns -1. 157If the argument 158.Fa wlabel 159is zero, and the transfer is a write operation, a check is done if the transfer 160would overwrite 161.Pq a portion of 162the disklabel area on the medium. 163If that is the case, 164.Dv EROFS 165is set in 166.Dq Va b_error , 167the 168.Dv B_ERROR 169flag is set in 170.Dq Va b_flags , 171and -1 is returned. 172Note that 173.Fa wlabel 174should be set to a non-zero value if the intended operation is expected to 175install or update the disk label. 176Programs that intend to do so using the raw device interface should notify 177the driver by using a 178.Dv DIOCWLABEL 179ioctl function. 180.Sh SEE ALSO 181.Xr disklabel 5 , 182.Xr disklabel 8 183