sbin/disklabel/disklabel.8

   1 .\"     $NetBSD: disklabel.8,v 1.61 2007/01/27 19:20:28 perry Exp $
   2 .\"
   3 .\" Copyright (c) 1987, 1988, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Symmetric Computer Systems.
   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. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)disklabel.8 8.2 (Berkeley) 4/19/94
  34 .\"
  35 .Dd November 28, 2009
  36 .Dt DISKLABEL 8
  37 .Os
  38 .Sh NAME
  39 .Nm disklabel
  40 .Nd read and write disk pack label
  41 .Sh SYNOPSIS
  42 .\" disklabel: read label
  43 .Nm
  44 .Op Fl ACDFrtv
  45 .Ar disk
  46 .\" disklabel -e: read/modify/write using $EDITOR
  47 .Nm
  48 .Fl e
  49 .Op Fl CDFIrv
  50 .Ar disk
  51 .\" disklabel -i: read/modify/write using builtin commands
  52 .Nm
  53 .Fl i
  54 .Op Fl DFIrv
  55 .Ar disk
  56 .\" disklabel -R: write from edited output
  57 .Nm
  58 .Fl R
  59 .Op Fl DFrv
  60 .Ar disk Ar protofile
  61 .\" disklabel -w: write from disctab entry
  62 .Nm
  63 .Fl w
  64 .Op Fl DFrv
  65 .Op Fl f Ar disktab
  66 .Ar disk Ar disktype
  67 .Oo Ar packid Oc
  68 .\" disklabel -NW: disallow/allow writes to the label sector
  69 .Nm
  70 .Op Fl NW
  71 .Ar disk
  72 .\" disklabel -l: list all know file system types
  73 .Nm
  74 .Fl l
  75 .Sh DESCRIPTION
  76 .Nm
  77 can be used to install, examine, or modify the label on a disk drive or pack.
  78 When writing the label, it can be used to change the drive identification,
  79 the disk partitions on the drive, or to replace a damaged label.
  80 .Pp
  81 The
  82 .Fl e , i , l , R , w , N ,
  83 and
  84 .Fl W
  85 options determine the basic operation.
  86 If none are specified the label
  87 is displayed.
  88 .Bl -tag -width flag
  89 .It Fl e
  90 Edit the existing label (using
  91 .Ev EDITOR )
  92 and write it back to the disk.
  93 If
  94 .Ev EDITOR
  95 is undefined, then
  96 .Xr vi 1
  97 is used.
  98 .It Fl i
  99 Interactively update the existing label and write it back to the disk.
 100 .It Fl l
 101 Show all known file system types (those that can be specified along a
 102 partition within the label) and exit.
 103 .It Fl R
 104 Write (restore) a label by reading it from
 105 .Ar protofile .
 106 The file should be in the same format as the default output.
 107 .It Fl w
 108 Write a standard label for the specified
 109 .Ar disktype .
 110 See
 111 .Xr disktab 5 .
 112 .It Fl N
 113 Disallow writes to the disk sector that contains the label.
 114 This is the default state.
 115 .It Fl W
 116 Allow writes to the disk sector that contains the label.
 117 This state may not persist if no programs have the disk open.
 118 .El
 119 .Pp
 120 The majority of the rest of the options affect more than one form of the
 121 command:
 122 .Bl -tag -width flag
 123 .It Fl A
 124 Read all labels from the disk, including ones deleted with
 125 .Nm
 126 .Fl D .
 127 Implies
 128 .Fl r .
 129 .It Fl C
 130 Output the partition offset and size values in
 131 .Aq cylinder/head/sector
 132 format.
 133 Note this format is always accepted on input with either the
 134 .Fl e
 135 or
 136 .Fl R
 137 flags.
 138 .It Fl D
 139 Delete all existing labels (by 1's complementing the magic number) before
 140 writing any labels to their default location.
 141 Implies
 142 .Fl r .
 143 If
 144 .Fl D
 145 is specified without a request to write the label, then existing labels are
 146 just deleted.
 147 .It Fl F
 148 Treat
 149 .Ar disk
 150 as a regular file.
 151 This suppresses all
 152 .Xr ioctl 2
 153 calls, and is the default if
 154 .Ar disk
 155 is a regular file.
 156 .Ar disk
 157 is always opened using
 158 .Xr opendisk 3
 159 even if
 160 .Fl F
 161 is specified.
 162 Implies
 163 .Fl r .
 164 .It Fl I
 165 If a label cannot be read from
 166 .Ar disk
 167 request the default one from the kernel.
 168 Implies
 169 .Fl r .
 170 .It Fl f Ar disktab
 171 Specify the name of a file to use instead of
 172 .Pa /etc/disktab .
 173 .It Fl r
 174 Read/write the disk directly rather than using
 175 .Xr ioctl 2
 176 requests on the kernel.
 177 When writing a label, the kernel will be told about the label before the
 178 label is written and asked to write afterwards.
 179 This is the historic behaviour and can be supressed by specifying
 180 .Fl F .
 181 .It Fl t
 182 Format the output as a
 183 .Xr disktab 5
 184 entry.
 185 .It Fl v
 186 Be verbose about the operations being done, in particular the disk sectors
 187 being read and written.
 188 Specifying
 189 .Fl v
 190 more than once will increase the verbosity.
 191 .El
 192 .Pp
 193 On systems that expect to have disks with MBR partitions (see
 194 .Xr fdisk 8 )
 195 .Nm
 196 will find, and update if requested, labels in the first 8k of type 169
 197 .Pq Nx
 198 MBR labels and within the first 8k of the physical disk.
 199 On other systems
 200 .Nm
 201 will only look at the start of the disk.
 202 The offset at which the labels are written is also system dependent.
 203 .Pp
 204 .Nm
 205 will detect byteswapped labels, but currently cannot display them.
 206 .Pp
 207 Previous versions of
 208 .Nm
 209 could update the bootstrap code on some architectures.
 210 This functionality has been subsumed by
 211 .Xr installboot 8 .
 212 .Sh EXIT STATUS
 213 The exit status of
 214 .Nm
 215 is set to indicate any errors or warnings.
 216 The values used are:
 217 .Bl -tag -width indent
 218 .It 0
 219 The
 220 .Nm
 221 utility has completed successfully.
 222 .It 1
 223 A fatal error has occurred, such as unknown options passed on the
 224 command line, or writing the disklabel failed.
 225 .It 4
 226 An I/O error of some sort occurred.
 227 .It 101..n
 228 One or more warnings occured while reading the disklabel.
 229 Subtract 100 to get the number of warnings detected.
 230 .El
 231 .Sh FILES
 232 .Bl -tag -width /etc/disktab -compact
 233 .It Pa /etc/disktab
 234 .El
 235 .Sh EXAMPLES
 236 .Dl Ic disklabel sd0
 237 .Pp
 238 Display the in-core label for sd0 as obtained via
 239 .Pa /dev/rsd0c .
 240 .Pp
 241 .Dl Ic disklabel -i -r sd0
 242 .Pp
 243 Read the on-disk label for sd0, edit it using the built-in interactive editor and reinstall in-core as well
 244 as on-disk.
 245 .Pp
 246 .Dl Ic disklabel -i -I sd0
 247 .Pp
 248 As previous, but don't fail if there was no label on the disk yet;
 249 provide some default values instead.
 250 .Pp
 251 .Dl Ic disklabel -e -I sd0
 252 .Pp
 253 As previous, only edit using $EDITOR
 254 .Pp
 255 .Dl Ic disklabel -w -r /dev/rsd0c sd2212 foo
 256 .Pp
 257 Create a label for sd0 based on information for
 258 .Dq sd2212
 259 found in
 260 .Pa /etc/disktab ,
 261 using
 262 .Pa foo
 263 as the disk pack label.
 264 If you do not have an entry for your disk in
 265 .Pa /etc/disktab ,
 266 you can use this style to put
 267 an initial label onto a new disk.
 268 Then dump the label to a file (using
 269 .Ic disklabel sd0 \*[Gt] protofile ) ,
 270 editing the file, and replacing the label with
 271 .Ic disklabel -R sd0 protofile .
 272 .Pp
 273 .Dl Ic disklabel -R sd0 mylabel
 274 .Pp
 275 Restore the on-disk and in-core label for sd0 from information in
 276 .Pa mylabel .
 277 .Sh DIAGNOSTICS
 278 The kernel device drivers will not allow the size of a disk partition
 279 to be decreased or the offset of a partition to be changed while it is open.
 280 Some device drivers create a label containing only a single large partition
 281 if a disk is unlabeled; thus, the label must be written to the
 282 .Dq a
 283 partition of the disk while it is open.
 284 This sometimes requires the desired label to be set in two steps,
 285 the first one creating at least one other partition,
 286 and the second setting the label on the new partition
 287 while shrinking the
 288 .Dq a
 289 partition.
 290 .Sh SEE ALSO
 291 .Xr opendisk 3 ,
 292 .Xr disklabel 5 ,
 293 .Xr disktab 5 ,
 294 .Xr dkctl 8 ,
 295 .Xr fdisk 8 ,
 296 .Xr installboot 8 ,
 297 .Xr mbrlabel 8 ,
 298 .Xr mscdlabel 8
 299 .Sh BUGS
 300 If the disk partition is not specified in the disk name
 301 (i.e.,
 302 .Ar xy0
 303 instead of
 304 .Ar /dev/rxy0c ) ,
 305 .Nm
 306 will construct the full pathname of the disk and use the
 307 .Dq d
 308 partition on i386, hpcmips, or arc, and the
 309 .Dq c
 310 partition on all others.
 311 .Pp
 312 On the sparc, sparc64, sun2, and sun3
 313 .Nx
 314 systems, the size of each partition must be a multiple of the number
 315 of sectors per cylinder (i.e., each partition must be an integer
 316 number of cylinders), or the boot ROMs will declare the label
 317 invalid and fail to boot the system.
 318 .Pp
 319 In addition, the
 320 .Fl r
 321 option should never be used on a sparc, sparc64, sun2, or sun3 system
 322 boot disk - the
 323 .Nx
 324 kernel translates the
 325 .Nx
 326 disk label into a SunOS compatible format (which is required by the
 327 boot PROMs) when it writes the label.
 328 Using the
 329 .Fl r
 330 flag causes
 331 .Nm
 332 to write directly to disk, and bypass the format translation.
 333 This will result in a disk label that the PROMs will not recognize,
 334 and that therefore cannot be booted from.