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