share/man/man9/disklabel.9

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