Annotation of src/sbin/gpt/gpt.8, Revision 1.27
1.27 ! jnemeth 1: .\" $NetBSD: gpt.8,v 1.26 2013/12/09 09:22:44 wiz Exp $
1.2 wiz 2: .\"
1.1 christos 3: .\" Copyright (c) 2002 Marcel Moolenaar
4: .\" All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\"
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\"
16: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26: .\"
27: .\" $FreeBSD: src/sbin/gpt/gpt.8,v 1.17 2006/06/22 22:22:32 marcel Exp $
28: .\"
1.25 jnemeth 29: .Dd December 9, 2013
1.4 joerg 30: .Dt GPT 8
1.1 christos 31: .Os
32: .Sh NAME
33: .Nm gpt
1.2 wiz 34: .Nd GUID partition table maintenance utility
1.1 christos 35: .Sh SYNOPSIS
36: .Nm
37: .Op Ar general_options
38: .Ar command
39: .Op Ar command_options
40: .Ar device ...
41: .Sh DESCRIPTION
42: The
43: .Nm
44: utility provides the necessary functionality to manipulate GUID partition
1.14 jnemeth 45: tables
46: .Pq GPTs ,
47: but see
1.1 christos 48: .Sx BUGS
49: below for how and where functionality is missing.
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
1.19 jnemeth 71: .Fl p Ar partitions
1.1 christos 72: option allows the user to change the number of partitions the GPT can
1.13 jnemeth 73: accommodate.
1.1 christos 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 ====
1.19 jnemeth 97: .It Nm Ic add Oo Fl a Ar alignment Oc Oo Fl b Ar blocknr Oc \
1.23 jnemeth 98: Oo Fl i Ar index Oc Oo Fl l Ar label Oc Oo Fl s Ar size Oc \
1.5 joerg 99: Oo Fl t Ar type Oc Ar device ...
1.1 christos 100: The
101: .Ic add
102: command allows the user to add a new partition to an existing table.
103: By default, it will create a UFS partition covering the first available block
104: of an unused disk space.
105: The command-specific options can be used to control this behaviour.
106: .Pp
107: The
1.15 jnemeth 108: .Fl a Ar alignment
109: option allows the user to specify an alignment for the start and size.
110: The alignment may have a suffix to indicate its magnitude.
111: .Nm
112: will attempt to align the partition.
113: .Pp
114: The
1.19 jnemeth 115: .Fl b Ar blocknr
1.1 christos 116: option allows the user to specify the starting (beginning) sector number of
117: the partition.
118: The minimum sector number is 1, but has to fall inside an unused region of
119: disk space that is covered by the GPT.
120: .Pp
121: The
122: .Fl i Ar index
123: option allows the user to specify which (free) entry in the GPT table is to
124: be used for the new partition.
125: By default, the first free entry is selected.
126: .Pp
127: The
1.15 jnemeth 128: .Fl l Ar label
129: option allows the user to specify a label for the partition.
130: .Pp
131: The
1.23 jnemeth 132: .Fl s Ar size
133: option allows the user to specify the size of the partition.
134: If there is no suffix, or the suffix is
135: .Sq s
136: or
137: .Sq S
138: then size is in sectors, otherwise size is in bytes which must be
139: a multiple of the device's sector size.
140: The minimum size is 1 sector.
1.1 christos 141: .Pp
142: The
143: .Fl t Ar type
144: option allows the user to specify the partition type.
145: The type is given as an UUID, but
146: .Nm
147: accepts
1.2 wiz 148: .Cm efi , swap , ufs , hfs , linux ,
1.6 schnoebe 149: .Cm raid , lfs , ccd , cgd , bios ,
150: .Cm ffs ,
1.1 christos 151: and
152: .Cm windows
153: as aliases for the most commonly used partition types.
1.27 ! jnemeth 154: .\" ==== backup ====
! 155: .It Nm Ic backup Ar device ...
! 156: The
! 157: .Ic backup
! 158: command dumps the MBR or (PMBR) and GPT partition tables to standard
! 159: output in a format to be used by the
! 160: .Ic restore
! 161: command.
! 162: The format is a plist.
! 163: It should not be modified.
1.7 jym 164: .\" ==== biosboot ====
165: .It Nm Ic biosboot Oo Fl c Ar bootcode Oc Oo Fl i Ar index Oc Ar device ...
166: The
167: .Ic biosboot
168: command allows the user to configure the partition that contains the
169: primary bootstrap program, used during
170: .Xr boot 8 .
171: .Pp
172: The
173: .Fl c
174: option allows the user to specify the filename that
175: .Nm
176: should read the bootcode from.
177: The default is to read from
1.10 drochner 178: .Pa /usr/mdec/gptmbr.bin .
1.7 jym 179: .Pp
180: The
181: .Fl i
182: option selects the partition that should contain the primary
183: bootstrap code, as installed via
184: .Xr installboot 8 .
1.1 christos 185: .\" ==== create ====
186: .It Nm Ic create Oo Fl fp Oc Ar device ...
187: The
188: .Ic create
189: command allows the user to create a new (empty) GPT.
190: By default, one cannot create a GPT when the device contains a MBR,
191: however this can be overridden with the
192: .Fl f
193: option.
194: If the
195: .Fl f
196: option is specified, an existing MBR is destroyed and any partitions
197: described by the MBR are lost.
198: .Pp
199: The
200: .Fl p
201: option tells
202: .Nm
203: to create only the primary table and not the backup table.
204: This option is only useful for debugging and should not be used otherwise.
205: .\" ==== destroy ====
206: .It Nm Ic destroy Oo Fl r Oc Ar device ...
207: The
208: .Ic destroy
209: command allows the user to destroy an existing, possibly not empty GPT.
210: .Pp
211: The
212: .Fl r
213: option instructs
214: .Nm
215: to destroy the table in a way that it can be recovered.
216: .\" ==== label ====
1.5 joerg 217: .It Nm Ic label Oo Fl a Oc Ao Fl f Ar file | Fl l Ar label Ac Ar device ...
1.19 jnemeth 218: .It Nm Ic label Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \
219: Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc \
1.5 joerg 220: Ao Fl f Ar file | Fl l Ar label Ac Ar device ...
1.1 christos 221: The
222: .Ic label
223: command allows the user to label any partitions that match the selection.
224: At least one of the following selection options must be specified.
225: .Pp
226: The
227: .Fl a
228: option specifies that all partitions should be labeled.
229: It is mutually exclusive with all other selection options.
230: .Pp
231: The
1.19 jnemeth 232: .Fl b Ar blocknr
1.1 christos 233: option selects the partition that starts at the given block number.
234: .Pp
235: The
236: .Fl i Ar index
237: option selects the partition with the given partition number.
238: .Pp
239: The
1.19 jnemeth 240: .Fl s Ar sectors
1.1 christos 241: option selects all partitions that have the given size.
1.14 jnemeth 242: This can cause multiple partitions to be labeled.
1.1 christos 243: .Pp
244: The
245: .Fl t Ar type
246: option selects all partitions that have the given type.
247: The type is given as an UUID or by the aliases that the
248: .Ic add
249: command accepts.
1.14 jnemeth 250: This can cause multiple partitions to be labeled.
1.1 christos 251: .Pp
252: The
253: .Fl f Ar file
254: or
255: .Fl l Ar label
256: options specify the new label to be assigned to the selected partitions.
257: The
258: .Fl f Ar file
259: option is used to read the label from the specified file.
260: Only the first line is read from the file and the trailing newline
261: character is stripped.
262: If the file name is the dash or minus sign
263: .Pq Fl ,
264: the label is read from
265: the standard input.
266: The
267: .Fl l Ar label
268: option is used to specify the label in the command line.
269: The label is assumed to be encoded in UTF-8.
270: .\" ==== migrate ====
271: .It Nm Ic migrate Oo Fl fs Oc Ar device ...
272: The
273: .Ic migrate
274: command allows the user to migrate an MBR-based disk partitioning into a
275: GPT-based partitioning.
276: By default, the MBR is not migrated when it contains partitions of an unknown
277: type.
278: This can be overridden with the
279: .Fl f
280: option.
281: Specifying the
282: .Fl f
283: option will cause unknown partitions to be ignored and any data in it
284: to be lost.
285: .Pp
286: The
287: .Fl s
288: option prevents migrating
289: .Bx
290: disk labels into GPT partitions by creating
291: the GPT equivalent of a slice.
1.14 jnemeth 292: Note that the
293: .Fl s
294: option isn't applicable to
295: .Nx
296: partitions.
297: .Pp
298: The
299: .Ic migrate
300: command requires space at the beginning and the end of the device outside
301: any partitions to store the GPTs.
302: Space is required for the GPT header
303: .Pq which takes one sector
304: and the GPT partition table.
305: See the
306: .Fl p
307: option
308: for the size of the GPT partition table.
309: By default, just about all devices have a minimum of 62 sectors free at the
310: beginning of the device, but don't have any free space at the end.
311: For the default GPT partition table size on a 512 byte sector size device,
312: 33 sectors at the end of the device would need to be freed.
1.8 wiz 313: .\" ==== recover ====
314: .It Nm Ic recover Ar device ...
315: The
316: .Ic recover
317: command tries to restore the GPT partition label from the backup
318: near the end of the disk.
319: It is very useful in case the primary label was deleted.
1.1 christos 320: .\" ==== remove ====
321: .It Nm Ic remove Oo Fl a Oc Ar device ...
1.19 jnemeth 322: .It Nm Ic remove Oo Fl b Ar blocknr Oc Oo Fl i Ar index Oc \
323: Oo Fl s Ar sectors Oc Oo Fl t Ar type Oc Ar device ...
1.1 christos 324: The
325: .Ic remove
326: command allows the user to remove any and all partitions that match the
327: selection.
328: It uses the same selection options as the
329: .Ic label
330: command.
331: See above for a description of these options.
332: Partitions are removed by clearing the partition type.
333: No other information is changed.
1.17 jnemeth 334: .\" ==== resize ====
335: .It Nm Ic resize Fl i Ar index Oo Fl a Ar alignment Oc \
1.23 jnemeth 336: Oo Fl s Ar size Oc Ar device ...
1.17 jnemeth 337: The
338: .Ic resize
339: command allows the user to resize a partition.
1.18 wiz 340: The partition may be shrunk and if there is sufficient free space
1.17 jnemeth 341: immediately after it then it may be expanded.
342: The
343: .Fl s
344: option allows the new size to be specified, otherwise the partition will
345: be increased to the maximum available size.
1.23 jnemeth 346: If there is no suffix, or the suffix is
347: .Sq s
348: or
349: .Sq S
350: then size is in sectors, otherwise size is in bytes which must be
351: a multiple of the device's sector size.
352: The minimum size is 1 sector.
1.17 jnemeth 353: If the
354: .Fl a
355: option is specified then the size will be adjusted to be a multiple of
356: alignment if possible.
1.25 jnemeth 357: .\" ==== set ====
358: .It Nm Ic set Fl a Ar attribute Fl i Ar index Ar device ...
359: The
360: .Ic set
361: command sets various partition attributes.
362: The
363: .Fl a
1.26 wiz 364: option specifies which attributes to set and may be specified more than once.
1.25 jnemeth 365: The
366: .Fl i
367: option specifies which entry to update.
368: The possible attributes are
369: .Do biosboot Dc ,
370: .Do bootme Dc ,
371: .Do bootonce Dc , and
372: .Do bootfailed Dc .
373: The biosboot flag is used to indicate which partition should be booted
374: by legacy BIOS boot code.
375: See the
376: .Ic biosboot
377: command for more information.
378: The other three attributes are for compatibility with
379: .Fx
380: and are not currently used by any
381: .Nx
382: code.
383: They may be used by
384: .Nx
385: code in the future.
1.1 christos 386: .\" ==== show ====
1.21 jnemeth 387: .It Nm Ic show Oo Fl glu Oc Oo Fl i Ar index Oc Ar device ...
1.1 christos 388: The
389: .Ic show
390: command displays the current partitioning on the listed devices and gives
391: an overall view of the disk contents.
392: With the
1.21 jnemeth 393: .Fl g
394: option the GPT partition GUID will be displayed instead of the GPT partition
395: type.
396: With the
1.1 christos 397: .Fl l
398: option the GPT partition label will be displayed instead of the GPT partition
399: type.
400: With the
401: .Fl u
402: option the GPT partition type is displayed as an UUID instead of in a
403: user friendly form.
1.21 jnemeth 404: With the
405: .Fl i
406: option, all the details of a particular GPT partition will be displayed.
1.24 jnemeth 407: The format of this display is subject to change.
1.21 jnemeth 408: None of the options have any effect on non-GPT partitions.
409: The order of precedence for the options are:
410: .Fl i ,
411: .Fl l ,
412: .Fl g ,
413: .Fl u .
1.25 jnemeth 414: .\" ==== unset ====
415: .It Nm Ic unset Fl a Ar attribute Fl i Ar index Ar device ...
416: The
417: .Ic unset
418: command unsets various partition attributes.
419: The
420: .Fl a
1.26 wiz 421: option specifies which attributes to unset and may be specified more than once.
1.25 jnemeth 422: The
423: .Fl i
424: option specifies which entry to update.
425: The possible attributes are
426: .Do biosboot Dc ,
427: .Do bootme Dc ,
428: .Do bootonce Dc , and
429: .Do bootfailed Dc .
430: The biosboot flag is used to indicate which partition should be booted
431: by legacy BIOS boot code.
432: See the
433: .Ic biosboot
434: command for more information.
435: The other three attributes are for compatibility with
436: .Fx
437: and are not currently used by any
438: .Nx
439: code.
440: They may be used by
441: .Nx
442: code in the future.
1.1 christos 443: .El
1.9 wiz 444: .Sh EXAMPLES
445: .Bd -literal
446: nas# gpt show wd3
447: start size index contents
448: 0 1 PMBR
449: 1 3907029167
450: nas# gpt create wd3
451: nas# gpt show wd3
452: start size index contents
453: 0 1 PMBR
454: 1 1 Pri GPT header
455: 2 32 Pri GPT table
456: 34 3907029101
457: 3907029135 32 Sec GPT table
458: 3907029167 1 Sec GPT header
459: nas# gpt add -s 10486224 -t swap -i 1 wd3
460: Partition added, use:
461: dkctl rwd3d addwedge dk<N> 34 10486224 <type>
462: to create a wedge for it
463: nas# gpt label -i 1 -l swap_1 wd3
464: parition 1 on rwd3d labeled swap_1
465: nas# gpt show wd3
466: start size index contents
467: 0 1 PMBR
468: 1 1 Pri GPT header
469: 2 32 Pri GPT table
470: 34 10486224 1 GPT part - NetBSD swap
471: 10486258 3896542877
472: 3907029135 32 Sec GPT table
473: 3907029167 1 Sec GPT header
1.14 jnemeth 474: nas# gpt show -l wd3
475: start size index contents
476: 0 1 PMBR
477: 1 1 Pri GPT header
478: 2 32 Pri GPT table
479: 34 10486224 1 GPT part - "swap_1"
480: 10486258 3896542877
481: 3907029135 32 Sec GPT table
482: 3907029167 1 Sec GPT header
1.9 wiz 483: nas#
484: .Ed
1.1 christos 485: .Sh SEE ALSO
1.7 jym 486: .Xr boot 8 ,
1.1 christos 487: .Xr fdisk 8 ,
1.7 jym 488: .Xr installboot 8 ,
1.1 christos 489: .Xr mount 8 ,
490: .Xr newfs 8 ,
491: .Xr swapon 8
492: .Sh HISTORY
493: The
494: .Nm
495: utility appeared in
496: .Fx 5.0
497: for ia64.
498: .Sh BUGS
499: The development of the
500: .Nm
501: utility is still work in progress.
502: Many necessary features are missing or partially implemented.
503: In practice this means that the manual page, supposed to describe these
504: features, is farther removed from being complete or useful.
505: As such, missing functionality is not even documented as missing.
506: However, it is believed that the currently present functionality is reliable
507: and stable enough that this tool can be used without bullet-proof footware if
508: one thinks one does not make mistakes.
509: .Pp
510: It is expected that the basic usage model does not change, but it is
511: possible that future versions will not be compatible in the strictest sense
512: of the word.
513: For example, the
1.19 jnemeth 514: .Fl p Ar partitions
1.1 christos 515: option may be changed to a command option rather than a generic option.
516: There are only two commands that use it so there is a chance that the natural
517: tendency for people is to use it as a command option.
518: Also, options primarily intended for diagnostic or debug purposes may be
519: removed in future versions.
520: .Pp
521: Another possibility is that the current usage model is accompanied by
522: other interfaces to make the tool usable as a back-end.
523: This all depends on demand and thus feedback.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to gpt.8 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / sbin / gpt