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