sbin/gpt/gpt.8

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