1.\" $NetBSD: disklabel.9,v 1.4 1997/11/11 10:07:02 mrg 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 Dec 26, 1996 38.Dt DISKLABEL 9 39.Os NetBSD 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. These routines are classified as machine- or 59architecture-dependent because of restrictions imposed by the machine 60architecture and boot-strapping code on the location of the label, or because 61co-operation with other operating systems requires specialized conversion 62code. 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. In particular, the field 77.Dq d_secsize , 78if non-zero, is used by 79.Fn readdisklabel 80to get an appropriately sized buffer to pass to the device strategy routine. 81Unspecified fields in 82.Fa lp 83should be set to zero. 84If the medium does not contain a native disklabel that can be read in directly, 85.Fn readdisklabel 86may resort to constructing a label from other machine-dependent information 87using the provided buffer passed in the 88.Fa clp 89argument. 90If a disk label can not be found or constructed, a string containing 91an approximated description of the failure mode is returned. 92Otherwise the 93.Dv NULL 94string is returned. 95.Pp 96.Fn writedisklabel 97stores disk label information contained in the disk label structure given by 98.Fa lp 99on the device identified by 100.Fa dev . 101Like 102.Fn readdisklabel , 103it acquires and sets up an I/O buffer to pass to the strategy routine 104.Fa strat . 105.Fn writedisklabel 106may elect to do a machine-dependent conversion of the native disk label 107structure 108.Po 109using the buffer pointed at by 110.Fa clp 111.Pc , 112to store the disk label onto the medium in a format complying with 113architectural contraints. 114.Fn writedisklabel 115returns 0 on success and 116.Dv EINVAL 117if the disk label specifies invalid or unconvertable values. 118Otherwise, any error condition reported by the device strategy routine 119in the buffer's 120.Dq Va b_error 121field is returned. 122.Pp 123.Fn setdisklabel 124checks a proposed new disk label passed in 125.Fa nlp 126for some amount of basic sanity. This includes a check on attempts to 127change the location, or reduce the size, of an existing disk partition 128that is currently in use by the system. 129The current disposition of the disk partitions is made available through 130.Fa olp 131and 132.Fa openmask , 133which provide, respectively, the existing disk label and a bit mask 134identifying the partitions that are currently in use. 135Failure to pass on 136.Dq basic sanity , 137results in a 138.Dv EINVAL 139return value, while a vetoed update of the partition layout is signaled by a 140.Dv EBUSY 141return value. Otherwise, 0 is returned. 142.Pp 143.Fn bounds_check_with_label 144is used to check whether a device transfer described by 145.Fa bp 146to the device identified by 147.Fa dev , 148is properly contained within a disk partition of the disk with label 149.Fa lp . 150If this check fails, 151.Fn bounds_check_with_label 152sets the buffer's 153.Dq Va b_error 154field to 155.Dv EINVAL , 156sets the 157.Dv B_ERROR 158flag in 159.Dq Va b_flags , 160and returns -1. If the argument 161.Fa wlabel 162is zero, and the transfer is a write operation, a check is done if the transfer 163would overwrite 164.Pq a portion of 165the disklabel area on the medium. If that is the case, 166.Dv EROFS 167is set in 168.Dq Va b_error , 169the 170.Dv B_ERROR 171flag is set in 172.Dq Va b_flags , 173and -1 is returned. 174Note that 175.Fa wlabel 176should be set to a non-zero value if the intended operation is expected to 177install or update the disk label. Programs that intend to do so using the 178raw device interface should notify the driver by using a 179.Dv DIOCWLABEL 180ioctl function. 181.Pp 182.Sh SEE ALSO 183.Xr disklabel 5 , 184.Xr disklabel 8 . 185