377 lines
10 KiB
Groff
377 lines
10 KiB
Groff
.\" 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 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 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 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.
|