1.\" $NetBSD: disklabel.9,v 1.2 1997/04/11 05:14:20 mikel 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 REGENTS OR CONTRIBUTORS BE 29.\" 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 Dec 26, 1996 38.Dt DISKLABEL 9 39.Os NetBSD 40.Sh NAME 41.Nm disklabel 42.Nd disk label management routines 43.Sh SYNOPSIS 44.Ft char * 45.Fn readdisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp" 46.Ft int 47.Fn writedisklabel "dev_t dev" "void (*strat)(struct buf *)" "struct disklabel *lp" "struct cpu_disklabel *clp" 48.Ft int 49.Fn setdisklabel "struct disklabel *olp" "struct disklabel *nlp" "u_long openmask" "struct cpu_disklabel *clp" 50.Ft int 51.Fn bounds_check_with_label "struct buf *bp" "struct disklabel *lp" "int wlabel" 52.Sh DESCRIPTION 53This collection of routines provides a disklabel management interface to 54kernel device drivers. These routines are classified as machine- or 55architecture-dependent because of restrictions imposed by the machine 56architecture and boot-strapping code on the location of the label, or because 57co-operation with other operating systems requires specialized conversion 58code. 59.Pp 60.Fn readdisklabel 61attempts to read a disklabel from the device identified by 62.Fa dev , 63using the device strategy routine passed in 64.Fa strat . 65Note that a buffer structure is required to pass to the strategy routine; 66it needs to be acquired and parametrized for the intended I/O operation, 67and disposed of when the operation has completed. 68Some fields in the in the disklabel passed in 69.Fa lp 70may be pre-initialized by the caller in order to meet device driver 71requirements for the I/O operation initiated to get to the disklabel data 72on the medium. In particular, the field 73.Dq d_secsize , 74if non-zero, is used by 75.Fn readdisklabel 76to get an appropriately sized buffer to pass to the device strategy routine. 77Unspecified fields in 78.Fa lp 79should be set to zero. 80If the medium does not contain a native disklabel that can be read in directly, 81.Fn readdisklabel 82may resort to constructing a label from other machine-dependent information 83using the provided buffer passed in the 84.Fa clp 85argument. 86If a disk label can not be found or constructed, a string containing 87an approximated description of the failure mode is returned. 88Otherwise the 89.Dv NULL 90string is returned. 91.Pp 92.Fn writedisklabel 93stores disk label information contained in the disk label structure given by 94.Fa lp 95on the device identified by 96.Fa dev . 97Like 98.Fn readdisklabel , 99it acquires and sets up an I/O buffer to pass to the strategy routine 100.Fa strat . 101.Fn writedisklabel 102may elect to do a machine-dependent conversion of the native disk label 103structure 104.Po 105using the buffer pointed at by 106.Fa clp 107.Pc , 108to store the disk label onto the medium in a format complying with 109architectural contraints. 110.Fn writedisklabel 111returns 0 on success and 112.Dv EINVAL 113if the disk label specifies invalid or unconvertable values. 114Otherwise, any error condition reported by the device strategy routine 115in the buffer's 116.Dq Va b_error 117field is returned. 118.Pp 119.Fn setdisklabel 120checks a proposed new disk label passed in 121.Fa nlp 122for some amount of basic sanity. This includes a check on attempts to 123change the location, or reduce the size, of an existing disk partition 124that is currently in use by the system. 125The current disposition of the disk partitions is made available through 126.Fa olp 127and 128.Fa openmask , 129which provide, respectively, the existing disk label and a bit mask 130identifying the partitions that are currently in use. 131Failure to pass on 132.Dq basic sanity , 133results in a 134.Dv EINVAL 135return value, while a vetoed update of the partition layout is signaled by a 136.Dv EBUSY 137return value. Otherwise, 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. If the argument 157.Fa wlabel 158is zero, and the transfer is a write operation, a check is done if the transfer 159would overwrite 160.Pq a portion of 161the disklabel area on the medium. If that is the case, 162.Dv EROFS 163is set in 164.Dq Va b_error , 165the 166.Dv B_ERROR 167flag is set in 168.Dq Va b_flags , 169and -1 is returned. 170Note that 171.Fa wlabel 172should be set to a non-zero value if the intended operation is expected to 173install or update the disk label. Programs that intend to do so using the 174raw device interface should notify the driver by using a 175.Dv DIOCWLABEL 176ioctl function. 177.Pp 178.Sh SEE ALSO 179.Xr disklabel 5 , 180.Xr disklabel 8 . 181