1.\" $NetBSD: gpt.8,v 1.28 2013/12/19 07:49:50 wiz Exp $ 2.\" 3.\" Copyright (c) 2002 Marcel Moolenaar 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 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.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.\" $FreeBSD: src/sbin/gpt/gpt.8,v 1.17 2006/06/22 22:22:32 marcel Exp $ 28.\" 29.Dd December 19, 2013 30.Dt GPT 8 31.Os 32.Sh NAME 33.Nm gpt 34.Nd GUID partition table maintenance utility 35.Sh SYNOPSIS 36.Nm 37.Op Ar general_options 38.Ar command 39.Op Ar command_options 40.Ar device ... 41.Sh DESCRIPTION 42The 43.Nm 44utility provides the necessary functionality to manipulate GUID partition 45tables 46.Pq GPTs , 47but see 48.Sx BUGS 49below for how and where functionality is missing. 50The basic usage model of the 51.Nm 52tool follows that of the 53.Xr cvs 1 54tool. 55The general options are described in the following paragraph. 56The remaining paragraphs describe the individual commands with their options. 57Here we conclude by mentioning that a 58.Ar device 59is either a special file 60corresponding to a disk-like device or a regular file. 61The command is applied to each 62.Ar device 63listed on the command line. 64.Ss General Options 65The general options allow the user to change default settings or otherwise 66change the behaviour that is applicable to all commands. 67Not all commands use all default settings, so some general options may not 68have an effect on all commands. 69.Pp 70The 71.Fl p Ar partitions 72option allows the user to change the number of partitions the GPT can 73accommodate. 74This is used whenever a new GPT is created. 75By default, the 76.Nm 77utility will create space for 128 partitions (or 32 sectors of 512 bytes). 78.Pp 79The 80.Fl r 81option causes the 82.Nm 83utility to open the device for reading only. 84Currently this option is primarily useful for the 85.Ic show 86command, but the intent 87is to use it to implement dry-run behaviour. 88.Pp 89The 90.Fl v 91option controls the verbosity level. 92The level increases with every occurrence of this option. 93There is no formalized definition of the different levels yet. 94.Ss Commands 95.Bl -tag -width indent 96.\" ==== add ==== 97.It Nm Ic add Oo Fl a Ar alignment Oc Oo Fl b Ar blocknr Oc \ 98Oo Fl i Ar index Oc Oo Fl l Ar label Oc Oo Fl s Ar size Oc \ 99Oo Fl t Ar type Oc Ar device ... 100The 101.Ic add 102command allows the user to add a new partition to an existing table. 103By default, it will create a UFS partition covering the first available block 104of an unused disk space. 105The command-specific options can be used to control this behaviour. 106.Pp 107The 108.Fl a Ar alignment 109option allows the user to specify an alignment for the start and size. 110The alignment may have a suffix to indicate its magnitude. 111.Nm 112will attempt to align the partition. 113.Pp 114The 115.Fl b Ar blocknr 116option allows the user to specify the starting (beginning) sector number of 117the partition. 118The minimum sector number is 1, but has to fall inside an unused region of 119disk space that is covered by the GPT. 120.Pp 121The 122.Fl i Ar index 123option allows the user to specify which (free) entry in the GPT table is to 124be used for the new partition. 125By default, the first free entry is selected. 126.Pp 127The 128.Fl l Ar label 129option allows the user to specify a label for the partition. 130.Pp 131The 132.Fl s Ar size 133option allows the user to specify the size of the partition. 134If there is no suffix, or the suffix is 135.Sq s 136or 137.Sq S 138then size is in sectors, otherwise size is in bytes which must be 139a multiple of the device's sector size. 140The minimum size is 1 sector. 141.Pp 142The 143.Fl t Ar type 144option allows the user to specify the partition type. 145The type is given as an UUID, but 146.Nm 147accepts 148.Cm efi , swap , ufs , hfs , linux , 149.Cm raid , lfs , ccd , cgd , bios , 150.Cm ffs , 151and 152.Cm windows 153as aliases for the most commonly used partition types. 154.\" ==== backup ==== 155.It Nm Ic backup Ar device ... 156The 157.Ic backup 158command dumps the MBR or (PMBR) and GPT partition tables to standard 159output in a format to be used by the 160.Ic restore 161command. 162The format is a plist. 163It should not be modified. 164.\" ==== biosboot ==== 165.It Nm Ic biosboot Oo Fl c Ar bootcode Oc Oo Fl i Ar index Oc Ar device ... 166The 167.Ic biosboot 168command allows the user to configure the partition that contains the 169primary bootstrap program, used during 170.Xr boot 8 . 171.Pp 172The 173.Fl c 174option allows the user to specify the filename that 175.Nm 176should read the bootcode from. 177The default is to read from 178.Pa /usr/mdec/gptmbr.bin . 179.Pp 180The 181.Fl i 182option selects the partition that should contain the primary 183bootstrap code, as installed via 184.Xr installboot 8 . 185.\" ==== create ==== 186.It Nm Ic create Oo Fl fp Oc Ar device ... 187The 188.Ic create 189command allows the user to create a new (empty) GPT. 190By default, one cannot create a GPT when the device contains a MBR, 191however this can be overridden with the 192.Fl f 193option. 194If the 195.Fl f 196option is specified, an existing MBR is destroyed and any partitions 197described by the MBR are lost. 198.Pp 199The 200.Fl p 201option tells 202.Nm 203to create only the primary table and not the backup table. 204This option is only useful for debugging and should not be used otherwise. 205.\" ==== destroy ==== 206.It Nm Ic destroy Oo Fl r Oc Ar device ... 207The 208.Ic destroy 209command allows the user to destroy an existing, possibly not empty GPT. 210.Pp 211The 212.Fl r 213option instructs 214.Nm 215to destroy the table in a way that it can be recovered. 216.\" ==== label ==== 217.It Nm Ic label Oo Fl a Oc Ao Fl f Ar file | Fl l Ar label Ac Ar device ... 218.It Nm Ic label Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 219Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \ 220Ao Fl f Ar file | Fl l Ar label Ac Ar device ... 221The 222.Ic label 223command allows the user to label any partitions that match the selection. 224At least one of the following selection options must be specified. 225.Pp 226The 227.Fl a 228option specifies that all partitions should be labeled. 229It is mutually exclusive with all other selection options. 230.Pp 231The 232.Fl b Ar blocknr 233option selects the partition that starts at the given block number. 234.Pp 235The 236.Fl i Ar index 237option selects the partition with the given partition number. 238.Pp 239The 240.Fl s Ar sectors 241option selects all partitions that have the given size. 242This can cause multiple partitions to be labeled. 243.Pp 244The 245.Fl t Ar type 246option selects all partitions that have the given type. 247The type is given as an UUID or by the aliases that the 248.Ic add 249command accepts. 250This can cause multiple partitions to be labeled. 251.Pp 252The 253.Fl f Ar file 254or 255.Fl l Ar label 256options specify the new label to be assigned to the selected partitions. 257The 258.Fl f Ar file 259option is used to read the label from the specified file. 260Only the first line is read from the file and the trailing newline 261character is stripped. 262If the file name is the dash or minus sign 263.Pq Fl , 264the label is read from 265the standard input. 266The 267.Fl l Ar label 268option is used to specify the label in the command line. 269The label is assumed to be encoded in UTF-8. 270.\" ==== migrate ==== 271.It Nm Ic migrate Oo Fl fs Oc Ar device ... 272The 273.Ic migrate 274command allows the user to migrate an MBR-based disk partitioning into a 275GPT-based partitioning. 276By default, the MBR is not migrated when it contains partitions of an unknown 277type. 278This can be overridden with the 279.Fl f 280option. 281Specifying the 282.Fl f 283option will cause unknown partitions to be ignored and any data in it 284to be lost. 285.Pp 286The 287.Fl s 288option prevents migrating 289.Bx 290disk labels into GPT partitions by creating 291the GPT equivalent of a slice. 292Note that the 293.Fl s 294option isn't applicable to 295.Nx 296partitions. 297.Pp 298The 299.Ic migrate 300command requires space at the beginning and the end of the device outside 301any partitions to store the GPTs. 302Space is required for the GPT header 303.Pq which takes one sector 304and the GPT partition table. 305See the 306.Fl p 307option 308for the size of the GPT partition table. 309By default, just about all devices have a minimum of 62 sectors free at the 310beginning of the device, but don't have any free space at the end. 311For the default GPT partition table size on a 512 byte sector size device, 31233 sectors at the end of the device would need to be freed. 313.\" ==== recover ==== 314.It Nm Ic recover Ar device ... 315The 316.Ic recover 317command tries to restore the GPT partition label from the backup 318near the end of the disk. 319It is very useful in case the primary label was deleted. 320.\" ==== remove ==== 321.It Nm Ic remove Oo Fl a Oc Ar device ... 322.It Nm Ic remove Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \ 323Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc Ar device ... 324The 325.Ic remove 326command allows the user to remove any and all partitions that match the 327selection. 328It uses the same selection options as the 329.Ic label 330command. 331See above for a description of these options. 332Partitions are removed by clearing the partition type. 333No other information is changed. 334.\" ==== resize ==== 335.It Nm Ic resize Fl i Ar index Oo Fl a Ar alignment Oc \ 336Oo Fl s Ar size Oc Ar device ... 337The 338.Ic resize 339command allows the user to resize a partition. 340The partition may be shrunk and if there is sufficient free space 341immediately after it then it may be expanded. 342The 343.Fl s 344option allows the new size to be specified, otherwise the partition will 345be increased to the maximum available size. 346If there is no suffix, or the suffix is 347.Sq s 348or 349.Sq S 350then size is in sectors, otherwise size is in bytes which must be 351a multiple of the device's sector size. 352The minimum size is 1 sector. 353If the 354.Fl a 355option is specified then the size will be adjusted to be a multiple of 356alignment if possible. 357.\" ==== set ==== 358.It Nm Ic set Fl a Ar attribute Fl i Ar index Ar device ... 359The 360.Ic set 361command sets various partition attributes. 362The 363.Fl a 364option specifies which attributes to set and may be specified more than once. 365The 366.Fl i 367option specifies which entry to update. 368The possible attributes are 369.Do biosboot Dc , 370.Do bootme Dc , 371.Do bootonce Dc , and 372.Do bootfailed Dc . 373The biosboot flag is used to indicate which partition should be booted 374by legacy BIOS boot code. 375See the 376.Ic biosboot 377command for more information. 378The other three attributes are for compatibility with 379.Fx 380and are not currently used by any 381.Nx 382code. 383They may be used by 384.Nx 385code in the future. 386.\" ==== show ==== 387.It Nm Ic show Oo Fl glu Oc Oo Fl i Ar index Oc Ar device ... 388The 389.Ic show 390command displays the current partitioning on the listed devices and gives 391an overall view of the disk contents. 392With the 393.Fl g 394option the GPT partition GUID will be displayed instead of the GPT partition 395type. 396With the 397.Fl l 398option the GPT partition label will be displayed instead of the GPT partition 399type. 400With the 401.Fl u 402option the GPT partition type is displayed as an UUID instead of in a 403user friendly form. 404With the 405.Fl i 406option, all the details of a particular GPT partition will be displayed. 407The format of this display is subject to change. 408None of the options have any effect on non-GPT partitions. 409The order of precedence for the options are: 410.Fl i , 411.Fl l , 412.Fl g , 413.Fl u . 414.\" ==== unset ==== 415.It Nm Ic unset Fl a Ar attribute Fl i Ar index Ar device ... 416The 417.Ic unset 418command unsets various partition attributes. 419The 420.Fl a 421option specifies which attributes to unset and may be specified more than once. 422The 423.Fl i 424option specifies which entry to update. 425The possible attributes are 426.Do biosboot Dc , 427.Do bootme Dc , 428.Do bootonce Dc , and 429.Do bootfailed Dc . 430The biosboot flag is used to indicate which partition should be booted 431by legacy BIOS boot code. 432See the 433.Ic biosboot 434command for more information. 435The other three attributes are for compatibility with 436.Fx 437and are not currently used by any 438.Nx 439code. 440They may be used by 441.Nx 442code in the future. 443.El 444.Sh EXAMPLES 445.Bd -literal 446nas# gpt show wd3 447 start size index contents 448 0 1 PMBR 449 1 3907029167 450nas# gpt create wd3 451nas# gpt show wd3 452 start size index contents 453 0 1 PMBR 454 1 1 Pri GPT header 455 2 32 Pri GPT table 456 34 3907029101 457 3907029135 32 Sec GPT table 458 3907029167 1 Sec GPT header 459nas# gpt add -s 10486224 -t swap -i 1 wd3 460Partition added, use: 461 dkctl rwd3d addwedge dk<N> 34 10486224 <type> 462to create a wedge for it 463nas# gpt label -i 1 -l swap_1 wd3 464parition 1 on rwd3d labeled swap_1 465nas# gpt show wd3 466 start size index contents 467 0 1 PMBR 468 1 1 Pri GPT header 469 2 32 Pri GPT table 470 34 10486224 1 GPT part - NetBSD swap 471 10486258 3896542877 472 3907029135 32 Sec GPT table 473 3907029167 1 Sec GPT header 474nas# gpt show -l wd3 475 start size index contents 476 0 1 PMBR 477 1 1 Pri GPT header 478 2 32 Pri GPT table 479 34 10486224 1 GPT part - "swap_1" 480 10486258 3896542877 481 3907029135 32 Sec GPT table 482 3907029167 1 Sec GPT header 483nas# 484.Ed 485.Sh SEE ALSO 486.Xr boot 8 , 487.Xr fdisk 8 , 488.Xr installboot 8 , 489.Xr mount 8 , 490.Xr newfs 8 , 491.Xr swapon 8 492.Sh HISTORY 493The 494.Nm 495utility appeared in 496.Fx 5.0 497for ia64. 498.Sh BUGS 499The development of the 500.Nm 501utility is still work in progress. 502Many necessary features are missing or partially implemented. 503In practice this means that the manual page, supposed to describe these 504features, is farther removed from being complete or useful. 505As such, missing functionality is not even documented as missing. 506However, it is believed that the currently present functionality is reliable 507and stable enough that this tool can be used without bullet-proof footware if 508one thinks one does not make mistakes. 509.Pp 510It is expected that the basic usage model does not change, but it is 511possible that future versions will not be compatible in the strictest sense 512of the word. 513For example, the 514.Fl p Ar partitions 515option may be changed to a command option rather than a generic option. 516There are only two commands that use it so there is a chance that the natural 517tendency for people is to use it as a command option. 518Also, options primarily intended for diagnostic or debug purposes may be 519removed in future versions. 520.Pp 521Another possibility is that the current usage model is accompanied by 522other interfaces to make the tool usable as a back-end. 523This all depends on demand and thus feedback. 524