| blob | 19f6b5bed4875280b74164d63353f07960c3bb2b |
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.5 2008/07/27 21:05:10 thomas Exp $
27 .\"
28 .Dd July 27, 2008
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
41 The
42 .Nm
43 utility provides the necessary functionality to manipulate GUID partition
44 tables (GPTs), but see
45 .Sx BUGS
46 below for how and where functionality is missing.
47 GPT partitions are accessed as
48 .Dx
49 disk slices, with same number as GPT partition.
50 The basic usage model of the
51 .Nm
52 tool follows that of the
53 .Xr cvs 1
54 tool.
55 The general options are described in the following paragraph.
56 The remaining paragraphs describe the individual commands with their options.
57 Here we conclude by mentioning that a
58 .Ar device
59 is either a special file
60 corresponding to a disk-like device or a regular file.
61 The command is applied to each
62 .Ar device
63 listed on the command line.
64 .Ss General Options
65 The general options allow the user to change default settings or otherwise
66 change the behaviour that is applicable to all commands.
67 Not all commands use all default settings, so some general options may not
68 have an effect on all commands.
69 .Pp
70 The
71 .Fl p Ar count
72 option allows the user to change the number of partitions the GPT can
73 accommodate.
74 This is used whenever a new GPT is created.
75 By default, the
76 .Nm
77 utility will create space for 128 partitions (or 32 sectors of 512 bytes).
78 .Pp
79 The
80 .Fl r
81 option causes the
82 .Nm
83 utility to open the device for reading only.
84 Currently this option is primarily useful for the
85 .Ic show
86 command, but the intent
87 is to use it to implement dry-run behaviour.
88 .Pp
89 The
90 .Fl v
91 option controls the verbosity level.
92 The level increases with every occurrence of this option.
93 There is no formalized definition of the different levels yet.
94 .Ss Commands
95 .Bl -tag -width indent
96 .\" ==== add ====
97 .It Xo
98 .Nm
99 .Ic add
100 .Op Fl b Ar number
101 .Op Fl i Ar index
102 .Op Fl s Ar count
103 .Op Fl t Ar type
104 .Ar device ...
105 .Xc
106 The
107 .Ic add
108 command allows the user to add a new partition to an existing table,
109 the name of the disk slice for the added partition is printed.
110 By default, it will create a
111 .Cm dfly
112 partition covering the first available block
113 of an unused disk space.
114 The command-specific options can be used to control this behaviour.
115 .Pp
116 The
117 .Fl b Ar number
118 option allows the user to specify the starting (beginning) sector number of
119 the partition.
120 The minimum sector number is 1, but has to fall inside an unused region of
121 disk space that is covered by the GPT.
122 .Pp
123 The
124 .Fl i Ar index
125 option allows the user to specify which (free) entry in the GPT table is to
126 be used for the new partition.
127 By default, the first free entry is selected.
128 Entries start at index 0 representing partition 0 of the GPT.
129 .Pp
130 The
131 .Fl s Ar count
132 option allows the user to specify the size of the partition in sectors.
133 The minimum size is 1.
134 .Pp
135 The
136 .Fl t Ar type
137 option allows the user to specify the partition type.
138 The type is given as an UUID, but
139 .Nm
140 accepts
141 .Cm efi , swap , ufs , hfs , linux , dfly ,
142 and
143 .Cm windows
144 as aliases for the most commonly used partition types.
145 .Cm ufs
146 is a
147 .Fx
148 UFS UUID.
149 .Cm dfly
150 has the alias
151 .Cm dragonfly
152 and is a
153 .Dx
154 .Xr disklabel64 5
155 UUID.
156 You may also specify any symbolic name in the system
157 .Xr uuids 5
158 files.
159 .\" ==== create ====
160 .It Nm Ic create Oo Fl fp Oc Ar device ...
161 The
162 .Ic create
163 command allows the user to create a new (empty) GPT.
164 By default, one cannot create a GPT when the device contains a MBR,
165 however this can be overridden with the
166 .Fl f
167 option.
168 If the
169 .Fl f
170 option is specified, an existing MBR is destroyed and any partitions
171 described by the MBR are lost.
172 .Pp
173 The
174 .Fl p
175 option tells
176 .Nm
177 to create only the primary table and not the backup table.
178 This option is only useful for debugging and should not be used otherwise.
179 .\" ==== destroy ====
180 .It Nm Ic destroy Oo Fl r Oc Ar device ...
181 The
182 .Ic destroy
183 command allows the user to destroy an existing, possibly not empty GPT.
184 .Pp
185 The
186 .Fl r
187 option instructs
188 .Nm
189 to destroy the table in a way that it can be recovered.
190 .\" ==== label ====
191 .It Xo
192 .Nm
193 .Ic label
194 .Op Fl a
195 .Aq Fl f Ar file | Fl l Ar label
196 .Ar device ...
197 .Xc
198 .It Xo
199 .Nm
200 .Ic label
201 .Op Fl b Ar number
202 .Op Fl i Ar index
203 .Op Fl s Ar count
204 .Op Fl t Ar type
205 .Aq Fl f Ar file | Fl l Ar label
206 .Ar device ...
207 .Xc
208 The
209 .Ic label
210 command allows the user to label any partitions that match the selection.
211 At least one of the following selection options must be specified.
212 .Pp
213 The
214 .Fl a
215 option specifies that all partitions should be labeled.
216 It is mutually exclusive with all other selection options.
217 .Pp
218 The
219 .Fl b Ar number
220 option selects the partition that starts at the given block number.
221 .Pp
222 The
223 .Fl i Ar index
224 option selects the partition with the given partition number.
225 Partition numbers start at 0.
226 .Pp
227 The
228 .Fl s Ar count
229 option selects all partitions that have the given size.
230 This can cause multiple partitions to be removed.
231 .Pp
232 The
233 .Fl t Ar type
234 option selects all partitions that have the given type.
235 The type is given as an UUID or by the aliases that the
236 .Ic add
237 command accepts.
238 This can cause multiple partitions to be removed.
239 .Pp
240 The
241 .Fl f Ar file
242 or
243 .Fl l Ar label
244 options specify the new label to be assigned to the selected partitions.
245 The
246 .Fl f Ar file
247 option is used to read the label from the specified file.
248 Only the first line is read from the file and the trailing newline
249 character is stripped.
250 If the file name is the dash or minus sign
251 .Pq Fl ,
252 the label is read from
253 the standard input.
254 The
255 .Fl l Ar label
256 option is used to specify the label in the command line.
257 The label is assumed to be encoded in UTF-8.
258 .\" ==== migrate ====
259 .It Nm Ic migrate Oo Fl fs Oc Ar device ...
260 The
261 .Ic migrate
262 command allows the user to migrate an MBR-based disk partitioning into a
263 GPT-based partitioning.
264 By default, the MBR is not migrated when it contains partitions of an unknown
265 type.
266 This can be overridden with the
267 .Fl f
268 option.
269 Specifying the
270 .Fl f
271 option will cause unknown partitions to be ignored and any data in it
272 to be lost.
273 .Pp
274 The
275 .Fl s
276 option prevents migrating
277 .Bx
278 disk labels into GPT partitions by creating
279 the GPT equivalent of a slice.
280 .\" ==== remove ====
281 .It Nm Ic remove Oo Fl a Oc Ar device ...
282 .It Xo
283 .Nm
284 .Ic remove
285 .Op Fl b Ar number
286 .Op Fl i Ar index
287 .Op Fl s Ar count
288 .Op Fl t Ar type
289 .Ar device ...
290 .Xc
291 The
292 .Ic remove
293 command allows the user to remove any and all partitions that match the
294 selection.
295 It uses the same selection options as the
296 .Ic label
297 command.
298 See above for a description of these options.
299 Partitions are removed by clearing the partition type.
300 No other information is changed.
301 .\" ==== show ====
302 .It Nm Ic show Oo Fl lu Oc Ar device ...
303 The
304 .Ic show
305 command displays the current partitioning on the listed devices and gives
306 an overall view of the disk contents.
307 With the
308 .Fl l
309 option the GPT partition label will be displayed instead of the GPT partition
310 type.
311 The option has no effect on non-GPT partitions.
312 With the
313 .Fl u
314 option the GPT partition type is displayed as an UUID instead of in a
315 user friendly form.
316 The
317 .Fl l
318 option takes precedence over the
319 .Fl u
320 option.
321 .El
322 .Sh FILES
323 .Bl -tag -width ".Pa /etc/defaults/uuids"
324 .It Pa /etc/defaults/uuids
325 A list of UUIDs
326 and their symbolic names provided by the OS vendor.
327 .It Pa /etc/uuids
328 A list of UUIDs
329 and their symbolic names provided by the system administrator.
330 .El
331 .Sh EXAMPLES
332 To install an empty GPT on
333 .Pa ad6 :
334 .Pp
335 .Dl "gpt create ad6"
336 .Pp
337 GPT partitions are defined in number of sectors, the sector size is usually 512B,
338 which is assumed in the examples below, it can be found using:
339 .Pp
340 .Dl "gpt -v show ad6"
341 .Pp
342 To add a dummy GPT partition 0:
343 .Pp
344 .Dl "gpt add -i0 -s1 ad6"
345 .Pp
346 You might want to do this to not use slice 0 for data;
347 when GPT is not used on a disk, slice 0 is the compatibility slice,
348 which is used for
349 .Dq dangerously dedicated
350 disks.
351 For GPT slice 0 has no special meaning, it is just the first slice on the disk.
352 .Pp
353 To add a GPT partition of size approx. 100GB:
354 .Pp
355 .Dl "gpt add -s200000000 ad6"
356 .Pp
357 This will be GPT partition 1 as it is the first one free,
358 it will be accessible as
359 .Pa ad6s1 ,
360 which is also printed by the command.
361 The type will be
362 .Dq DragonFly Label64 ,
363 it will have to be set up by
364 .Xr disklabel64 8 .
365 .Pp
366 To add GPT partition 5 with type
367 .Dq DragonFly HAMMER
368 using the remaining free space:
369 .Bd -literal -offset indent
370 gpt add -i5 -t "DragonFly HAMMER" ad6
371 .Ed
372 .Pp
373 To print the contents of the GPT:
374 .Pp
375 .Dl "gpt show ad6"
376 .Sh COMPATIBILITY
377 The GPT that
378 .Nm
379 manipulates is part of the EFI standard and is supported by many OSs.
380 GPT uses 64 bits to store number of sectors, this supports very large disks.
381 With the prevalent sector size of 512B this is 8 billion TB.
382 .Sh SEE ALSO
383 .Xr uuid 3 ,
384 .Xr disklabel64 5 ,
385 .Xr uuids 5 ,
386 .Xr disklabel 8 ,
387 .Xr disklabel64 8 ,
388 .Xr fdisk 8 ,
389 .Xr mount 8 ,
390 .Xr newfs 8 ,
391 .Xr newfs_hammer 8 ,
392 .Xr swapon 8
393 .Sh HISTORY
394 The
395 .Nm
396 utility appeared in
397 .Fx 5.0
398 for ia64.
399 It was imported to
400 .Dx 1.9 .
401 .Sh BUGS
402 The development of the
403 .Nm
404 utility is still work in progress.
405 Many necessary features are missing or partially implemented.
406 In practice this means that the manual page, supposed to describe these
407 features, is farther removed from being complete or useful.
408 As such, missing functionality is not even documented as missing.
409 However, it is believed that the currently present functionality is reliable
410 and stable enough that this tool can be used without bullet-proof footware if
411 one thinks one does not make mistakes.
412 .Pp
413 It is expected that the basic usage model does not change, but it is
414 possible that future versions will not be compatible in the strictest sense
415 of the word.
416 For example, the
417 .Fl p Ar count
418 option may be changed to a command option rather than a generic option.
419 There are only two commands that use it so there is a chance that the natural
420 tendency for people is to use it as a command option.
421 Also, options primarily intended for diagnostic or debug purposes may be
422 removed in future versions.
423 .Pp
424 Another possibility is that the current usage model is accompanied by
425 other interfaces to make the tool usable as a back-end.
426 This all depends on demand and thus feedback.
427 .Pp
428 The
429 .Ic migrate
430 command doesn't support
431 .Dx
432 partition types.
433 .Pp
434 .Dx
435 doesn't support booting from GPT partitions.