| .\" Copyright (c) 2002 Marcel Moolenaar |
| .\" All rights reserved. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
| .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
| .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
| .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
| .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
| .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| .\" |
| .\" $FreeBSD$ |
| .\" |
| .Dd February 5, 2008 |
| .Os |
| .Dt GPT 8 |
| .Sh NAME |
| .Nm gpt |
| .Nd "GUID partition table maintenance utility" |
| .Sh SYNOPSIS |
| .Nm |
| .Op Ar general_options |
| .Ar command |
| .Op Ar command_options |
| .Ar device ... |
| .Sh DESCRIPTION |
| The |
| .Nm |
| utility provides the necessary functionality to manipulate GUID partition |
| tables (GPTs), but see |
| .Sx BUGS |
| below for how and where functionality is missing. |
| The basic usage model of the |
| .Nm |
| tool follows that of the |
| .Xr cvs 1 |
| tool. |
| The general options are described in the following paragraph. |
| The remaining paragraphs describe the individual commands with their options. |
| Here we conclude by mentioning that a |
| .Ar device |
| is either a special file |
| corresponding to a disk-like device or a regular file. |
| The command is applied to each |
| .Ar device |
| listed on the command line. |
| .Ss General Options |
| The general options allow the user to change default settings or otherwise |
| change the behaviour that is applicable to all commands. |
| Not all commands use all default settings, so some general options may not |
| have an effect on all commands. |
| .Pp |
| The |
| .Fl p Ar count |
| option allows the user to change the number of partitions the GPT can |
| accomodate. |
| This is used whenever a new GPT is created. |
| By default, the |
| .Nm |
| utility will create space for 128 partitions (or 32 sectors of 512 bytes). |
| .Pp |
| The |
| .Fl r |
| option causes the |
| .Nm |
| utility to open the device for reading only. |
| Currently this option is primarily useful for the |
| .Ic show |
| command, but the intent |
| is to use it to implement dry-run behaviour. |
| .Pp |
| The |
| .Fl S |
| option causes the |
| .Nm |
| utility to open the device for writing in shared mode. The |
| default is to open in exclusive (O_EXCL) mode. |
| .Pp |
| The |
| .Fl v |
| option controls the verbosity level. |
| The level increases with every occurrence of this option. |
| There is no formalized definition of the different levels yet. |
| .Ss Commands |
| .Bl -tag -width indent |
| .\" ==== add ==== |
| .It Xo |
| .Nm |
| .Ic add |
| .Op Fl b Ar number |
| .Op Fl i Ar index |
| .Op Fl s Ar count |
| .Op Fl t Ar type |
| .Ar device ... |
| .Xc |
| The |
| .Ic add |
| command allows the user to add a new partition to an existing table. |
| By default, it will create a UFS partition covering the first available block |
| of an unused disk space. |
| The command-specific options can be used to control this behaviour. |
| .Pp |
| The |
| .Fl b Ar number |
| option allows the user to specify the starting (beginning) sector number of |
| the partition. |
| The minimum sector number is 1, but has to fall inside an unused region of |
| disk space that is covered by the GPT. |
| .Pp |
| The |
| .Fl i Ar index |
| option allows the user to specify which (free) entry in the GPT table is to |
| be used for the new partition. |
| By default, the first free entry is selected. |
| .Pp |
| The |
| .Fl s Ar count |
| option allows the user to specify the size of the partition in sectors. |
| The minimum size is 1. |
| .Pp |
| The |
| .Fl t Ar type |
| option allows the user to specify the partition type. |
| The type is given as an UUID, but |
| .Nm |
| accepts |
| .Cm boot , efi , swap , ufs , zfs , hfs , linux |
| and |
| .Cm windows |
| as aliases for the most commonly used partition types. |
| .\" ==== boot ==== |
| .It Xo |
| .Nm |
| .Ic boot |
| .Op Fl b Ar pmbr |
| .Op Fl g Ar gptboot |
| .Op Fl i Ar index |
| .Op Fl s Ar count |
| .Ar device ... |
| .Xc |
| The |
| .Ic boot |
| command allows the user to make a GPT labeled disk bootable via the BIOS |
| bootstrap on i386 and amd64 machines. |
| By default, |
| the |
| .Pa /boot/pmbr |
| boot loader is installed into the PMBR and the |
| .Pa /boot/gptboot |
| boot loader is installed into the first boot partition. |
| If no boot partition exists and there is available space, |
| a boot partition will be created. |
| .Pp |
| The |
| .Fl b Ar pmbr |
| option allows the user to specify an alternate path for the PMBR boot loader. |
| .Pp |
| The |
| .Fl g Ar gptboot |
| option allows the user to specify an alternate path for the GPT boot loader |
| that is installed into the boot partition. |
| .Pp |
| The |
| .Fl i Ar index |
| option allows the user to specify which (valid) entry in the GPT table is to |
| be selected for booting. |
| .Pp |
| The |
| .Fl s Ar count |
| option allows the user to specify the size in sectors of the boot partition |
| if one does not already exist. |
| A boot partition must be at least 16 kilobytes. |
| By default, |
| a size of 64 kilobytes is used. |
| Note that the PMBR boot loader will load the entire boot partition into |
| memory. |
| As a result, the boot partition may not exceed 545 kilobytes. |
| .\" ==== create ==== |
| .It Nm Ic create Oo Fl fp Oc Ar device ... |
| The |
| .Ic create |
| command allows the user to create a new (empty) GPT. |
| By default, one cannot create a GPT when the device contains a MBR, |
| however this can be overridden with the |
| .Fl f |
| option. |
| If the |
| .Fl f |
| option is specified, an existing MBR is destroyed and any partitions |
| described by the MBR are lost. |
| .Pp |
| The |
| .Fl p |
| option tells |
| .Nm |
| to create only the primary table and not the backup table. |
| This option is only useful for debugging and should not be used otherwise. |
| .\" ==== destroy ==== |
| .It Nm Ic destroy Oo Fl r Oc Ar device ... |
| The |
| .Ic destroy |
| command allows the user to destroy an existing, possibly not empty GPT. |
| .Pp |
| The |
| .Fl r |
| option instructs |
| .Nm |
| to destroy the table in a way that it can be recovered. |
| .\" ==== label ==== |
| .It Xo |
| .Nm |
| .Ic label |
| .Op Fl a |
| .Aq Fl f Ar file | Fl l Ar label |
| .Ar device ... |
| .Xc |
| .It Xo |
| .Nm |
| .Ic label |
| .Op Fl b Ar number |
| .Op Fl i Ar index |
| .Op Fl s Ar count |
| .Op Fl t Ar type |
| .Aq Fl f Ar file | Fl l Ar label |
| .Ar device ... |
| .Xc |
| The |
| .Ic label |
| command allows the user to label any partitions that match the selection. |
| At least one of the following selection options must be specified. |
| .Pp |
| The |
| .Fl a |
| option specifies that all partitions should be labeled. |
| It is mutually exclusive with all other selection options. |
| .Pp |
| The |
| .Fl b Ar number |
| option selects the partition that starts at the given block number. |
| .Pp |
| The |
| .Fl i Ar index |
| option selects the partition with the given partition number. |
| .Pp |
| The |
| .Fl s Ar count |
| option selects all partitions that have the given size. |
| This can cause multiple partitions to be removed. |
| .Pp |
| The |
| .Fl t Ar type |
| option selects all partitions that have the given type. |
| The type is given as an UUID or by the aliases that the |
| .Ic add |
| command accepts. |
| This can cause multiple partitions to be removed. |
| .Pp |
| The |
| .Fl f Ar file |
| or |
| .Fl l Ar label |
| options specify the new label to be assigned to the selected partitions. |
| The |
| .Fl f Ar file |
| option is used to read the label from the specified file. |
| Only the first line is read from the file and the trailing newline |
| character is stripped. |
| If the file name is the dash or minus sign |
| .Pq Fl , |
| the label is read from |
| the standard input. |
| The |
| .Fl l Ar label |
| option is used to specify the label in the command line. |
| The label is assumed to be encoded in UTF-8. |
| .\" ==== migrate ==== |
| .It Nm Ic migrate Oo Fl fs Oc Ar device ... |
| The |
| .Ic migrate |
| command allows the user to migrate an MBR-based disk partitioning into a |
| GPT-based partitioning. |
| By default, the MBR is not migrated when it contains partitions of an unknown |
| type. |
| This can be overridden with the |
| .Fl f |
| option. |
| Specifying the |
| .Fl f |
| option will cause unknown partitions to be ignored and any data in it |
| to be lost. |
| .Pp |
| The |
| .Fl s |
| option prevents migrating |
| .Bx |
| disk labels into GPT partitions by creating |
| the GPT equivalent of a slice. |
| .\" ==== remove ==== |
| .It Nm Ic remove Oo Fl a Oc Ar device ... |
| .It Xo |
| .Nm |
| .Ic remove |
| .Op Fl b Ar number |
| .Op Fl i Ar index |
| .Op Fl s Ar count |
| .Op Fl t Ar type |
| .Ar device ... |
| .Xc |
| The |
| .Ic remove |
| command allows the user to remove any and all partitions that match the |
| selection. |
| It uses the same selection options as the |
| .Ic label |
| command. |
| See above for a description of these options. |
| Partitions are removed by clearing the partition type. |
| No other information is changed. |
| .\" ==== show ==== |
| .It Nm Ic show Oo Fl lu Oc Ar device ... |
| The |
| .Ic show |
| command displays the current partitioning on the listed devices and gives |
| an overall view of the disk contents. |
| With the |
| .Fl l |
| option the GPT partition label will be displayed instead of the GPT partition |
| type. |
| The option has no effect on non-GPT partitions. |
| With the |
| .Fl u |
| option the GPT partition type is displayed as an UUID instead of in a |
| user friendly form. |
| The |
| .Fl l |
| option takes precedence over the |
| .Fl u |
| option. |
| .El |
| .Sh SEE ALSO |
| .Xr fdisk 8 , |
| .Xr mount 8 , |
| .Xr newfs 8 , |
| .Xr swapon 8 |
| .Sh HISTORY |
| The |
| .Nm |
| utility appeared in |
| .Fx 5.0 |
| for ia64. |
| .Sh BUGS |
| The development of the |
| .Nm |
| utility is still work in progress. |
| Many necessary features are missing or partially implemented. |
| In practice this means that the manual page, supposed to describe these |
| features, is farther removed from being complete or useful. |
| As such, missing functionality is not even documented as missing. |
| However, it is believed that the currently present functionality is reliable |
| and stable enough that this tool can be used without bullet-proof footware if |
| one thinks one does not make mistakes. |
| .Pp |
| It is expected that the basic usage model does not change, but it is |
| possible that future versions will not be compatible in the strictest sense |
| of the word. |
| For example, the |
| .Fl p Ar count |
| option may be changed to a command option rather than a generic option. |
| There are only two commands that use it so there is a chance that the natural |
| tendency for people is to use it as a command option. |
| Also, options primarily intended for diagnostic or debug purposes may be |
| removed in future versions. |
| .Pp |
| Another possibility is that the current usage model is accompanied by |
| other interfaces to make the tool usable as a back-end. |
| This all depends on demand and thus feedback. |