1.\" Copyright (c) 1987, 1988, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Symmetric Computer Systems. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd January 23, 2025 32.Dt BSDLABEL 8 33.Os 34.Sh NAME 35.Nm bsdlabel 36.Nd read and write BSD label 37.Sh SYNOPSIS 38.Nm 39.Op Fl A 40.Ar disk | Fl f Ar file 41.Nm 42.Fl w 43.Op Fl \&An 44.Op Fl B Op Fl b Ar boot 45.Op Fl m Ar machine 46.Ar disk | Fl f Ar file 47.Op Ar type 48.Nm 49.Fl e 50.Op Fl \&An 51.Op Fl B Op Fl b Ar boot 52.Op Fl m Ar machine 53.Ar disk | Fl f Ar file 54.Nm 55.Fl R 56.Op Fl \&An 57.Op Fl B Op Fl b Ar boot 58.Op Fl m Ar machine 59.Op Fl f 60.Ar disk | Fl f Ar file 61.Ar protofile 62.Sh DEPRECATION NOTICE 63.Nm 64is deprecated and is not available in 65.Fx 15.0 66or later. 67Use 68.Xr gpart 8 69instead 70.Po 71with the 72.Cm BSD 73partitioning scheme 74.Pc , 75or install the 76.Pa freebsd-bsdlabel 77port or package. 78.Sh DESCRIPTION 79The 80.Nm 81utility 82installs, examines or modifies the 83.Bx 84label on a disk partition, or on a file containing a partition image. 85In addition, 86.Nm 87can install bootstrap code. 88.Ss Disk Device Name 89When specifying the device (i.e., when the 90.Fl f 91option is not used), 92the 93.Pa /dev/ 94path prefix may be omitted; 95the 96.Nm 97utility will automatically prepend it. 98.Ss General Options 99The 100.Fl A 101option enables processing of the historical parts of the 102.Bx 103label. 104If the option is not given, suitable values are set for these fields. 105.Pp 106The 107.Fl f 108option tells 109.Nm 110that the program will operate on a file instead of a disk partition. 111.Pp 112The 113.Fl n 114option stops the 115.Nm 116program right before the disk would have been modified, and displays 117the result instead of writing it. 118.Pp 119The 120.Fl m Ar machine 121argument forces 122.Nm 123to use a layout suitable for a different architecture. 124Current valid values are 125.Cm i386 126and 127.Cm amd64 . 128If this option is omitted, 129.Nm 130will use a layout suitable for the current machine. 131.Ss Reading the Disk Label 132To examine the label on a disk drive, use the form 133.Pp 134.Nm 135.Op Fl A 136.Op Fl m Ar machine 137.Ar disk 138.Pp 139.Ar disk 140represents the disk in question, and may be in the form 141.Pa da0 142or 143.Pa /dev/da0 . 144It will display the partition layout. 145.Ss Writing a Standard Label 146To write a standard label, use the form 147.Pp 148.Nm 149.Fl w 150.Op Fl \&An 151.Op Fl m Ar machine 152.Ar disk 153.Op Ar type 154.Pp 155If the drive 156.Ar type 157is specified, the entry of that name in the 158.Xr disktab 5 159file is used; otherwise, or if the type is specified as 'auto', a default 160layout is used. 161.Ss Editing an Existing Disk Label 162To edit an existing disk label, use the form 163.Pp 164.Nm 165.Fl e 166.Op Fl \&An 167.Op Fl m Ar machine 168.Ar disk 169.Pp 170This command opens the disk label in the default editor, and when the editor 171exits, the label is validated and if OK written to disk. 172.Ss Restoring a Disk Label From a File 173To restore a disk label from a file, use the form 174.Pp 175.Nm 176.Fl R 177.Op Fl \&An 178.Op Fl m Ar machine 179.Ar disk protofile 180.Pp 181The 182.Nm 183utility 184is capable of restoring a disk label that was previously saved in a file in 185.Tn ASCII 186format. 187The prototype file used to create the label should be in the same format as that 188produced when reading or editing a label. 189Comments are delimited by 190.Ql # 191and newline. 192.Ss Installing Bootstraps 193If the 194.Fl B 195option is specified, bootstrap code will be read from the file 196.Pa /boot/boot 197and written to the disk. 198The 199.Fl b Ar boot 200option allows a different file to be used. 201.Sh FILES 202.Bl -tag -width ".Pa /etc/disktab" -compact 203.It Pa /boot/boot 204Default boot image. 205.It Pa /etc/disktab 206Disk description file. 207.El 208.Sh SAVED FILE FORMAT 209The 210.Nm 211utility 212uses an 213.Tn ASCII 214version of the label when examining, editing, or restoring a disk 215label. 216The format is: 217.Bd -literal -offset 4n 218 2198 partitions: 220# size offset fstype [fsize bsize bps/cpg] 221 a: 81920 16 4.2BSD 2048 16384 5128 222 b: 1091994 81936 swap 223 c: 1173930 0 unused 0 0 # "raw" part, don't edit 224.Ed 225.Pp 226If the 227.Fl A 228option is specified, the format is: 229.Bd -literal -offset 4n 230# /dev/da1c: 231type: SCSI 232disk: da0s1 233label: 234flags: 235bytes/sector: 512 236sectors/track: 51 237tracks/cylinder: 19 238sectors/cylinder: 969 239cylinders: 1211 240sectors/unit: 1173930 241rpm: 3600 242interleave: 1 243trackskew: 0 244cylinderskew: 0 245headswitch: 0 # milliseconds 246track-to-track seek: 0 # milliseconds 247drivedata: 0 248 2498 partitions: 250# size offset fstype [fsize bsize bps/cpg] 251 a: 81920 16 4.2BSD 1024 8192 16 252 b: 160000 81936 swap 253 c: 1173930 0 unused 0 0 # "raw" part, don't edit 254.Ed 255.Pp 256Lines starting with a 257.Ql # 258mark are comments. 259.Pp 260The partition table can have up to 8 entries. 261It contains the following information: 262.Bl -tag -width indent 263.It Ar # 264The partition identifier is a single letter in the range 265.Ql a 266to 267.Ql h . 268By convention, partition 269.Ql c 270is reserved to describe the entire disk. 271.It Ar size 272The size of the partition in sectors, 273.Cm K 274(kilobytes - 1024), 275.Cm M 276(megabytes - 1024*1024), 277.Cm G 278(gigabytes - 1024*1024*1024), 279.Cm % 280(percentage of free space 281.Em after 282removing any fixed-size partitions other than partition 283.Ql c ) , 284or 285.Cm * 286(all remaining free space 287.Em after 288fixed-size and percentage partitions). 289For partition 290.Ql c , 291a size of 292.Cm * 293indicates the entire disk. 294Lowercase versions of suffixes 295.Cm K , M , 296and 297.Cm G 298are allowed. 299Size and suffix should be specified without any spaces between them. 300.Pp 301Example: 2097152, 1G, 1024M and 1048576K are all the same size 302(assuming 512-byte sectors). 303.It Ar offset 304The offset of the start of the partition from the beginning of the 305drive in sectors, or 306.Cm * 307to have 308.Nm 309calculate the correct offset to use (the end of the previous partition plus 310one, ignoring partition 311.Ql c ) . 312For partition 313.Ql c , 314.Cm * 315will be interpreted as an offset of 0. 316The first partition should start at offset 16, because the first 16 sectors are 317reserved for metadata. 318.It Ar fstype 319Describes the purpose of the partition. 320The above example shows all currently used partition types. 321For 322.Tn UFS 323file systems and 324.Xr ccd 4 325partitions, use type 326.Cm 4.2BSD . 327Other common types are 328.Cm swap 329and 330.Cm unused . 331By convention, partition 332.Ql c 333represents the entire slice and should be of type 334.Cm unused , 335though 336.Nm 337does not enforce this convention. 338The 339.Nm 340utility 341also knows about a number of other partition types, 342none of which are in current use. 343(See the definitions starting with 344.Dv FS_UNUSED 345in 346.In sys/disklabel.h 347for more details.) 348.It Ar fsize 349For 350.Cm 4.2BSD 351file systems only, the fragment size; see 352.Xr newfs 8 . 353.It Ar bsize 354For 355.Cm 4.2BSD 356file systems only, the block size; see 357.Xr newfs 8 . 358.It Ar bps/cpg 359For 360.Cm 4.2BSD 361file systems, the number of cylinders in a cylinder group; see 362.Xr newfs 8 . 363.El 364.Sh EXAMPLES 365Display the label for the first slice of the 366.Pa da0 367disk, as obtained via 368.Pa /dev/da0s1 : 369.Pp 370.Dl "bsdlabel da0s1" 371.Pp 372Save the in-core label for 373.Pa da0s1 374into the file 375.Pa savedlabel . 376This file can be used with the 377.Fl R 378option to restore the label at a later date: 379.Pp 380.Dl "bsdlabel da0s1 > savedlabel" 381.Pp 382Create a label for 383.Pa da0s1 : 384.Pp 385.Dl "bsdlabel -w /dev/da0s1" 386.Pp 387Read the label for 388.Pa da0s1 , 389edit it, and install the result: 390.Pp 391.Dl "bsdlabel -e da0s1" 392.Pp 393Read the on-disk label for 394.Pa da0s1 , 395edit it, and display what the new label would be (in sectors). 396It does 397.Em not 398install the new label either in-core or on-disk: 399.Pp 400.Dl "bsdlabel -e -n da0s1" 401.Pp 402Write a default label on 403.Pa da0s1 . 404Use another 405.Nm Fl e 406command to edit the 407partitioning and file system information: 408.Pp 409.Dl "bsdlabel -w da0s1" 410.Pp 411Restore the on-disk and in-core label for 412.Pa da0s1 413from information in 414.Pa savedlabel : 415.Pp 416.Dl "bsdlabel -R da0s1 savedlabel" 417.Pp 418Display what the label would be for 419.Pa da0s1 420using the partition layout in 421.Pa label_layout . 422This is useful for determining how much space would be allotted for various 423partitions with a labeling scheme using 424.Cm % Ns -based 425or 426.Cm * 427partition sizes: 428.Pp 429.Dl "bsdlabel -R -n da0s1 label_layout" 430.Pp 431Install a new bootstrap on 432.Pa da0s1 . 433The boot code comes from 434.Pa /boot/boot : 435.Pp 436.Dl "bsdlabel -B da0s1" 437.Pp 438Install a new label and bootstrap. 439The bootstrap code comes from the file 440.Pa newboot 441in the current working directory: 442.Pp 443.Dl "bsdlabel -w -B -b newboot /dev/da0s1" 444.Pp 445Completely wipe any prior information on the disk, creating a new bootable 446disk with a 447.Tn DOS 448partition table containing one slice, covering the whole disk. 449Initialize the label on this slice, 450then edit it. 451The 452.Xr dd 1 453commands are optional, but may be necessary for some 454.Tn BIOS Ns es 455to properly 456recognize the disk: 457.Bd -literal -offset indent 458dd if=/dev/zero of=/dev/da0 bs=512 count=32 459gpart create -s MBR da0 460gpart add -t freebsd da0 461gpart set -a active -i 1 da0 462gpart bootcode -b /boot/mbr da0 463dd if=/dev/zero of=/dev/da0s1 bs=512 count=32 464bsdlabel -w -B da0s1 465bsdlabel -e da0s1 466.Ed 467.Pp 468This is an example disk label that uses some of the new partition size types 469such as 470.Cm % , M , G , 471and 472.Cm * , 473which could be used as a source file for 474.Dq Li "bsdlabel -R ada0s1 new_label_file" : 475.Bd -literal -offset 4n 476# /dev/ada0s1: 477 4788 partitions: 479# size offset fstype [fsize bsize bps/cpg] 480 a: 400M 16 4.2BSD 4096 16384 75 # (Cyl. 0 - 812*) 481 b: 1G * swap 482 c: * * unused 483 e: 204800 * 4.2BSD 484 f: 5g * 4.2BSD 485 g: * * 4.2BSD 486.Ed 487.Sh DIAGNOSTICS 488The kernel device drivers will not allow the size of a disk partition 489to be decreased or the offset of a partition to be changed while it is open. 490.Sh COMPATIBILITY 491Due to the use of an 492.Vt uint32_t 493to store the number of sectors, 494.Bx 495labels are restricted to a maximum of 2^32-1 sectors. 496This usually means 2TB of disk space. 497Larger disks should be partitioned using another method such as 498.Xr gpart 8 . 499.Pp 500The various 501.Bx Ns s 502all use slightly different versions of 503.Bx 504labels and 505are not generally compatible. 506.Sh SEE ALSO 507.Xr ccd 4 , 508.Xr geom 4 , 509.Xr md 4 , 510.Xr disktab 5 , 511.Xr boot0cfg 8 , 512.Xr gpart 8 , 513.Xr newfs 8 514.Sh HISTORY 515The 516.Nm disklabel 517utility appeared in 518.Bx 4.3 Tahoe . 519.Sh BUGS 520.\" PR276517 521The disklabel scheme supports up to 20 partitions, but 522.Nm 523supports only 8 partitions. 524