1.\" Copyright (c) 2002 Marcel Moolenaar 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/sbin/gpt/gpt.8,v 1.17 2006/06/22 22:22:32 marcel Exp $ 26.\" $DragonFly: src/sbin/gpt/gpt.8,v 1.4 2007/12/23 15:31:28 swildner Exp $ 27.\" 28.Dd June 22, 2006 29.Os 30.Dt GPT 8 31.Sh NAME 32.Nm gpt 33.Nd "GUID partition table maintenance utility" 34.Sh SYNOPSIS 35.Nm 36.Op Ar general_options 37.Ar command 38.Op Ar command_options 39.Ar device ... 40.Sh DESCRIPTION 41The 42.Nm 43utility provides the necessary functionality to manipulate GUID partition 44tables (GPTs), but see 45.Sx BUGS 46below for how and where functionality is missing. 47The basic usage model of the 48.Nm 49tool follows that of the 50.Xr cvs 1 51tool. 52The general options are described in the following paragraph. 53The remaining paragraphs describe the individual commands with their options. 54Here we conclude by mentioning that a 55.Ar device 56is either a special file 57corresponding to a disk-like device or a regular file. 58The command is applied to each 59.Ar device 60listed on the command line. 61.Ss General Options 62The general options allow the user to change default settings or otherwise 63change the behaviour that is applicable to all commands. 64Not all commands use all default settings, so some general options may not 65have an effect on all commands. 66.Pp 67The 68.Fl p Ar count 69option allows the user to change the number of partitions the GPT can 70accommodate. 71This is used whenever a new GPT is created. 72By default, the 73.Nm 74utility will create space for 128 partitions (or 32 sectors of 512 bytes). 75.Pp 76The 77.Fl r 78option causes the 79.Nm 80utility to open the device for reading only. 81Currently this option is primarily useful for the 82.Ic show 83command, but the intent 84is to use it to implement dry-run behaviour. 85.Pp 86The 87.Fl v 88option controls the verbosity level. 89The level increases with every occurrence of this option. 90There is no formalized definition of the different levels yet. 91.Ss Commands 92.Bl -tag -width indent 93.\" ==== add ==== 94.It Xo 95.Nm 96.Ic add 97.Op Fl b Ar number 98.Op Fl i Ar index 99.Op Fl s Ar count 100.Op Fl t Ar type 101.Ar device ... 102.Xc 103The 104.Ic add 105command allows the user to add a new partition to an existing table. 106By default, it will create a UFS partition covering the first available block 107of an unused disk space. 108The command-specific options can be used to control this behaviour. 109.Pp 110The 111.Fl b Ar number 112option allows the user to specify the starting (beginning) sector number of 113the partition. 114The minimum sector number is 1, but has to fall inside an unused region of 115disk space that is covered by the GPT. 116.Pp 117The 118.Fl i Ar index 119option allows the user to specify which (free) entry in the GPT table is to 120be used for the new partition. 121By default, the first free entry is selected. 122Entries start at index 0 representing partition 0 of the GPT. 123.Pp 124The 125.Fl s Ar count 126option allows the user to specify the size of the partition in sectors. 127The minimum size is 1. 128.Pp 129The 130.Fl t Ar type 131option allows the user to specify the partition type. 132The type is given as an UUID, but 133.Nm 134accepts 135.Cm efi , swap , ufs , hfs , linux , dfly , 136and 137.Cm windows 138as aliases for the most commonly used partition types. 139You may also specify any symbolic name in the system uuids file. 140.\" ==== create ==== 141.It Nm Ic create Oo Fl fp Oc Ar device ... 142The 143.Ic create 144command allows the user to create a new (empty) GPT. 145By default, one cannot create a GPT when the device contains a MBR, 146however this can be overridden with the 147.Fl f 148option. 149If the 150.Fl f 151option is specified, an existing MBR is destroyed and any partitions 152described by the MBR are lost. 153.Pp 154The 155.Fl p 156option tells 157.Nm 158to create only the primary table and not the backup table. 159This option is only useful for debugging and should not be used otherwise. 160.\" ==== destroy ==== 161.It Nm Ic destroy Oo Fl r Oc Ar device ... 162The 163.Ic destroy 164command allows the user to destroy an existing, possibly not empty GPT. 165.Pp 166The 167.Fl r 168option instructs 169.Nm 170to destroy the table in a way that it can be recovered. 171.\" ==== label ==== 172.It Xo 173.Nm 174.Ic label 175.Op Fl a 176.Aq Fl f Ar file | Fl l Ar label 177.Ar device ... 178.Xc 179.It Xo 180.Nm 181.Ic label 182.Op Fl b Ar number 183.Op Fl i Ar index 184.Op Fl s Ar count 185.Op Fl t Ar type 186.Aq Fl f Ar file | Fl l Ar label 187.Ar device ... 188.Xc 189The 190.Ic label 191command allows the user to label any partitions that match the selection. 192At least one of the following selection options must be specified. 193.Pp 194The 195.Fl a 196option specifies that all partitions should be labeled. 197It is mutually exclusive with all other selection options. 198.Pp 199The 200.Fl b Ar number 201option selects the partition that starts at the given block number. 202.Pp 203The 204.Fl i Ar index 205option selects the partition with the given partition number. 206Partition numbers start at 0. 207.Pp 208The 209.Fl s Ar count 210option selects all partitions that have the given size. 211This can cause multiple partitions to be removed. 212.Pp 213The 214.Fl t Ar type 215option selects all partitions that have the given type. 216The type is given as an UUID or by the aliases that the 217.Ic add 218command accepts. 219This can cause multiple partitions to be removed. 220.Pp 221The 222.Fl f Ar file 223or 224.Fl l Ar label 225options specify the new label to be assigned to the selected partitions. 226The 227.Fl f Ar file 228option is used to read the label from the specified file. 229Only the first line is read from the file and the trailing newline 230character is stripped. 231If the file name is the dash or minus sign 232.Pq Fl , 233the label is read from 234the standard input. 235The 236.Fl l Ar label 237option is used to specify the label in the command line. 238The label is assumed to be encoded in UTF-8. 239.\" ==== migrate ==== 240.It Nm Ic migrate Oo Fl fs Oc Ar device ... 241The 242.Ic migrate 243command allows the user to migrate an MBR-based disk partitioning into a 244GPT-based partitioning. 245By default, the MBR is not migrated when it contains partitions of an unknown 246type. 247This can be overridden with the 248.Fl f 249option. 250Specifying the 251.Fl f 252option will cause unknown partitions to be ignored and any data in it 253to be lost. 254.Pp 255The 256.Fl s 257option prevents migrating 258.Bx 259disk labels into GPT partitions by creating 260the GPT equivalent of a slice. 261.\" ==== remove ==== 262.It Nm Ic remove Oo Fl a Oc Ar device ... 263.It Xo 264.Nm 265.Ic remove 266.Op Fl b Ar number 267.Op Fl i Ar index 268.Op Fl s Ar count 269.Op Fl t Ar type 270.Ar device ... 271.Xc 272The 273.Ic remove 274command allows the user to remove any and all partitions that match the 275selection. 276It uses the same selection options as the 277.Ic label 278command. 279See above for a description of these options. 280Partitions are removed by clearing the partition type. 281No other information is changed. 282.\" ==== show ==== 283.It Nm Ic show Oo Fl lu Oc Ar device ... 284The 285.Ic show 286command displays the current partitioning on the listed devices and gives 287an overall view of the disk contents. 288With the 289.Fl l 290option the GPT partition label will be displayed instead of the GPT partition 291type. 292The option has no effect on non-GPT partitions. 293With the 294.Fl u 295option the GPT partition type is displayed as an UUID instead of in a 296user friendly form. 297The 298.Fl l 299option takes precedence over the 300.Fl u 301option. 302.El 303.Sh SEE ALSO 304.Xr fdisk 8 , 305.Xr mount 8 , 306.Xr newfs 8 , 307.Xr swapon 8 308.Sh HISTORY 309The 310.Nm 311utility appeared in 312.Fx 5.0 313for ia64. 314.Sh BUGS 315The development of the 316.Nm 317utility is still work in progress. 318Many necessary features are missing or partially implemented. 319In practice this means that the manual page, supposed to describe these 320features, is farther removed from being complete or useful. 321As such, missing functionality is not even documented as missing. 322However, it is believed that the currently present functionality is reliable 323and stable enough that this tool can be used without bullet-proof footware if 324one thinks one does not make mistakes. 325.Pp 326It is expected that the basic usage model does not change, but it is 327possible that future versions will not be compatible in the strictest sense 328of the word. 329For example, the 330.Fl p Ar count 331option may be changed to a command option rather than a generic option. 332There are only two commands that use it so there is a chance that the natural 333tendency for people is to use it as a command option. 334Also, options primarily intended for diagnostic or debug purposes may be 335removed in future versions. 336.Pp 337Another possibility is that the current usage model is accompanied by 338other interfaces to make the tool usable as a back-end. 339This all depends on demand and thus feedback. 340