Add HISTORY sections in most sbin/ manual pages.
[dragonfly.git] / sbin / fdisk / fdisk.8
blob1f970270345d5b1701e851f7d468d2be1324c0de
1 .\" $FreeBSD: src/sbin/i386/fdisk/fdisk.8,v 1.17.2.11 2002/04/25 16:25:12 trhodes Exp $
2 .\"
3 .Dd September 29, 2016
4 .Dt FDISK 8
5 .Os
6 .Sh NAME
7 .Nm fdisk
8 .Nd PC slice table (MBR) maintenance program
9 .Sh SYNOPSIS
10 .Nm
11 .Op Fl BCEIaistu
12 .Op Fl b Ar bootcode
13 .Op Fl p Ar diskimage
14 .Op Fl 1234
15 .Op Ar disk
16 .Nm
17 .Fl f Ar configfile
18 .Op Fl itv
19 .Op Ar disk
20 .Sh PROLOGUE
21 In order for the BIOS to boot the kernel,
22 certain conventions must be adhered to.
23 Sector 0 of the disk must contain an MBR, which contain boot code,
24 a slice table,
25 and a magic number.
26 BIOS slices can be used to break the disk up into several pieces.
27 .Dx
28 slices are called partitions under DOS
29 .Dq ( partition
30 has another meaning under
31 .Dx ,
32 see
33 .Xr disklabel 8 ) .
34 .Dx
35 supports 30 MBR slices, s1-s4 will be DOS primary partitions,
36 s5-s30 will be DOS partitions in extended DOS partitions.
37 The BIOS brings in sector 0 and verifies the magic number.
38 The sector
39 0 boot code then searches the slice table to determine which
40 slice is marked
41 .Em active .
42 This boot code then brings in the bootstrap from the
43 .Em active
44 slice and, if marked bootable, runs it.
45 Under DOS,
46 you can have one or more slices with one
47 .Em active .
48 The DOS
49 .Nm
50 program can be used to divide space on the disk into slices and set one
51 .Em active .
52 .Sh DESCRIPTION
53 The
54 .Dx
55 program,
56 .Nm ,
57 serves a similar purpose to the DOS program.
58 The first form is used to
59 display slice information or to interactively edit the slice table.
60 The second is used to write a slice table using a
61 .Ar configfile
62 and is designed to be used by other scripts/programs.
63 .Pp
64 Options are:
65 .Bl -tag -width indent
66 .It Fl a
67 Change the active slice only.
68 Ignored if
69 .Fl f
70 is given.
71 .It Fl b Ar bootcode
72 Get the boot code from the file
73 .Ar bootcode .
74 Default is
75 .Pa /boot/mbr .
76 .It Fl p Ar diskimage
77 The disk image is specified as a normal file instead of as a device,
78 which is useful when building emulated disks for vmware, bochs, etc.\&
79 .It Fl B
80 Reinitialize the boot code contained in sector 0 of the disk.
81 Ignored if
82 .Fl f
83 is given.
84 .It Fl C
85 Set CHS fields to wrapped values.
86 Normally the CHS fields for a slice are set to all 1's if they
87 would otherwise wrap.
88 This typically causes BIOSes to properly detect
89 that the disk should be put in Large mode.
90 This option may be needed on very old PCs.
91 .It Fl E
92 Use TRIM to erase the device/partition before creating the file system.
93 The underlying device must have the TRIM sysctl enabled.
94 Only devices that support TRIM will have such a sysctl option
95 .Va ( kern.cam.da.X.trim_enabled ) .
96 For use with the
97 .Fl I
99 .Fl u
100 option.
101 .It Fl f Ar configfile
102 Set slice values using the file
103 .Ar configfile .
105 .Ar configfile
106 always modifies existing slices, unless
107 .Fl i
108 is also given, in which case all existing slices are deleted (marked
110 .Dq unused )
111 before the
112 .Ar configfile
113 is read.
115 .Ar configfile
116 can be
117 .Sq - ,
118 in which case
119 .Ar stdin
120 is read.
122 .Sx CONFIGURATION FILE ,
123 below, for file syntax.
125 .Em WARNING :
126 when
127 .Fl f
128 is used, you are not asked if you really want to write the slices
129 table (as you are in the interactive mode).
130 Use with caution!
131 .It Fl i
132 Initialize sector 0 of the disk.
133 This implies
134 .Fl u ,
135 unless
136 .Fl f
137 is given.
138 .It Fl I
139 Initialize the contents of sector 0
140 for one
142 slice covering the entire disk.
143 .It Fl s
144 Print a summary of all slices on the disk and exit.
145 All other options will be ignored.
146 .It Fl t
147 Test mode; do not write slice values.
148 Generally used with the
149 .Fl f
150 option to see what would be written to the slice table.
151 Implies
152 .Fl v .
153 .It Fl u
154 Is used for updating (editing) sector 0 of the disk.
155 Ignored if
156 .Fl f
157 is given.
158 .It Fl v
159 Be verbose.
160 When
161 .Fl f
162 is used,
164 prints out the slice table that is written to the disk.
165 .It Fl 1234
166 Operate on a single fdisk entry only.
167 Ignored if
168 .Fl f
169 is given.
172 The final disk name can be provided as a
173 .Sq bare
174 disk name only, e.g.\&
175 .Pa da0 ,
176 or as a fully qualified device node under
177 .Pa /dev .
178 If omitted, the disks
179 .Pa ad0 ,
180 .Pa da0
182 .Pa vkd0
183 are searched in that order, until one is found to respond.
185 When called without options,
187 prints the sector 0 slice table.
188 An example follows:
189 .Bd -literal
190         ******* Working on device /dev/ad0 *******
191         parameters extracted from in-core disklabel are:
192         cylinders=769 heads=15 sectors/track=33 (495 blks/cyl)
194         parameters to be used for BIOS calculations are:
195         cylinders=769 heads=15 sectors/track=33 (495 blks/cyl)
197         Warning: BIOS sector numbering starts with sector 1
198         Information from DOS bootblock is:
199         The data for partition 1 is:
200         sysid 165,(DragonFly/FreeBSD/NetBSD/386BSD)
201             start 495, size 380160 (185 Meg), flag 0
202                 beg: cyl 1/ sector 1/ head 0;
203                 end: cyl 768/ sector 33/ head 14
204         The data for partition 2 is:
205         sysid 164,(unknown)
206             start 378180, size 2475 (1 Meg), flag 0
207                 beg: cyl 764/ sector 1/ head 0;
208                 end: cyl 768/ sector 33/ head 14
209         The data for partition 3 is:
210         <UNUSED>
211         The data for partition 4 is:
212         sysid 99,(ISC UNIX, other System V/386, GNU HURD or Mach)
213             start 380656, size 224234 (109 Meg), flag 80
214                 beg: cyl 769/ sector 2/ head 0;
215                 end: cyl 197/ sector 33/ head 14
218 The disk is divided into three slices that happen to fill the disk.
219 The second slice overlaps the end of the first.
220 (Used for debugging purposes.)
221 .Bl -tag -width "cyl, sector and head"
222 .It Em "sysid"
223 is used to label the slice.
225 reserves the
226 magic number 165 decimal (A5 in hex).
227 .It Em start No and Em size
228 fields provide the start address
229 and size of a slice in sectors.
230 .It Em "flag 80"
231 specifies that this is the active slice.
232 .It Em cyl , sector No and Em head
233 fields are used to specify the beginning and end addresses of the slice.
234 .It Em Note :
235 these numbers are calculated using BIOS's understanding of the disk geometry
236 and saved in the bootblock.
240 .Fl i
242 .Fl u
243 flags are used to indicate that the slice data is to be updated.
244 Unless the
245 .Fl f
246 option is also given,
248 will enter a conversational mode.
249 In this mode, no changes will be written to disk unless you explicitly tell
253 .Nm Fdisk
254 will display each slice and ask whether you want to edit it.
255 If you say yes,
257 will step through each field, show you the old value,
258 and ask you for a new one.
259 When you are done with the slice,
261 will display it and ask you whether it is correct.
262 .Nm Fdisk
263 will then proceed to the next entry.
265 Getting the
266 .Em cyl , sector ,
268 .Em head
269 fields correct is tricky, so by default,
270 they will be calculated for you;
271 you can specify them if you choose to though.
273 After all the slices are processed,
274 you are given the option to change the
275 .Em active
276 slice.
277 Finally, when all the new data for sector 0 has been accumulated,
278 you are asked to confirm whether you really want to rewrite it.
280 The difference between the
281 .Fl u
283 .Fl i
284 flags is that
286 .Fl u
287 flag just edits (updates) the fields as they appear on the disk,
288 while the
289 .Fl i
290 flag is used to
291 .Dq initialize
292 sector 0;
293 it will set up the last BIOS slice to use the whole disk for
295 and make it active.
296 .Sh NOTES
297 The automatic calculation of starting cylinder etc.\& uses
298 a set of figures that represent what the BIOS thinks the
299 geometry of the drive is.
300 These figures are taken from the in-core disklabel by default,
303 initially gives you an opportunity to change them.
304 This allows you to create a bootblock that can work with drives
305 that use geometry translation under the BIOS.
307 If you hand craft your disk layout,
308 please make sure that the
310 slice starts on a cylinder boundary.
311 A number of decisions made later may assume this.
312 (This might not be necessary later.)
314 Editing an existing slice will most likely result in the loss of
315 all data in that slice.
317 You should run
319 interactively once or twice to see how it works.
320 This is completely safe as long as you answer the last question
321 in the negative.
322 There are subtleties that
324 detects that are not fully explained in this manual page.
325 .Sh CONFIGURATION FILE
326 When the
327 .Fl f
328 option is given, a disk's slice table can be written using values
329 from a
330 .Ar configfile .
331 The syntax of this file is very simple;
332 each line is either a comment or a specification, as follows:
333 .Bl -tag -width Ds
334 .It Xo
335 .Ic #
336 .Ar comment ...
338 Lines beginning with a
339 .Sq #
340 are comments and are ignored.
341 .It Xo
342 .Ic g
343 .Ar spec1
344 .Ar spec2
345 .Ar spec3
347 Set the BIOS geometry used in slice calculations.
348 There must be
349 three values specified, with a letter preceding each number:
350 .Bl -tag -width Ds
351 .Sm off
352 .It Cm c Ar num
353 .Sm on
354 Set the number of cylinders to
355 .Ar num .
356 .Sm off
357 .It Cm h Ar num
358 .Sm on
359 Set the number of heads to
360 .Ar num .
361 .Sm off
362 .It Cm s Ar num
363 .Sm on
364 Set the number of sectors/track to
365 .Ar num .
368 These specs can occur in any order, as the leading letter determines
369 which value is which; however, all three must be specified.
371 This line must occur before any lines that specify slice
372 information.
374 It is an error if the following is not true:
375 .Bd -literal -offset indent
376 1 \(<= number of cylinders
377 1 \(<= number of heads \(<= 256
378 1 \(<= number of sectors/track < 64
381 The number of cylinders should be less than or equal to 1024, but this
382 is not enforced, although a warning will be printed.
383 Note that a bootable
385 slice (the
386 .Dq Pa /
387 file system) must lie completely within the
388 first 1024 cylinders, if
389 .Dq packet
390 mode isn't used, see
391 .Xr boot0cfg 8 ;
392 if this is not true, booting may fail.
393 Non-bootable slices do not have this restriction.
395 Example (all of these are equivalent), for a disk with 1019 cylinders,
396 39 heads, and 63 sectors:
397 .Bd -literal -offset indent
398 g       c1019   h39     s63
399 g       h39     c1019   s63
400 g       s63     h39     c1019
402 .It Xo
403 .Ic p
404 .Ar slice
405 .Ar type
406 .Ar start
407 .Ar length
409 Set the slice given by
410 .Ar slice
411 (1-4) to type
412 .Ar type ,
413 starting at sector
414 .Ar start
416 .Ar length
417 sectors.
419 Only those slices explicitly mentioned by these lines are modified;
420 any slice not referenced by a
421 .Cm p
422 line will not be modified.
423 However, if an invalid slice table is present, or the
424 .Fl i
425 option is specified, all existing slice entries will be cleared
426 (marked as unused), and these
427 .Cm p
428 lines will have to be used to
429 explicitly set slice information.
430 If multiple slices need to be
431 set, multiple
432 .Cm p
433 lines must be specified; one for each slice.
435 These slice lines must occur after any geometry specification lines,
436 if one is present.
439 .Ar type
440 is 165 for
442 slices.
443 Specifying a slice type of zero is
444 the same as clearing the slice and marking it as unused; however,
445 dummy values (such as
446 .Sq 0 )
447 must still be specified for
448 .Ar start
450 .Ar length .
452 Note: the start offset will be rounded upwards to a head boundary if
453 necessary, and the end offset will be rounded downwards to a cylinder
454 boundary if necessary.
456 Example: to clear slice 4 and mark it as unused:
457 .Bd -literal -offset indent
458 p       4       0       0       0
461 Example: to set slice 1 to a
463 slice, starting at sector 1
464 for 2503871 sectors (note: these numbers will be rounded upwards and
465 downwards to correspond to head and cylinder boundaries):
466 .Bd -literal -offset indent
467 p       1       165     1       2503871
469 .It Xo
470 .Ic a
471 .Ar slice
473 Make
474 .Ar slice
475 the active slice.
476 Can occur anywhere in the config file, but only
477 one must be present.
478 If no
479 .Cm a
480 line is present, all slices of the disk are made inactive.
482 Example: to make slice 1 the active slice:
483 .Bd -literal -offset indent
484 a       1
487 .Sh FILES
488 .Bl -tag -width /boot/mbr -compact
489 .It Pa /boot/mbr
490 The default boot code
492 .Sh COMPATIBILITY
493 Due to the use of 32 bit to store the number of sectors in the MBR,
495 can at most use 2^32 - 1 sectors.
496 For the prevalent sector size of 512B this means a maximum of 2TB.
497 Larger disks should be partitioned using
498 .Xr gpt 8 .
500 The MBR that
502 manipulates, is used by many different OSs, but the exact requirements seems to differ,
503 it can be a hassle to get multiple OSs to recognize the same MBR.
504 Some OSs will require that slices are located at cylinder boundaries.
505 .Sh SEE ALSO
506 .Xr boot0cfg 8 ,
507 .Xr disklabel 8 ,
508 .Xr gpt 8 ,
509 .Xr newfs 8
510 .Sh HISTORY
511 A version of
513 first appeared in the Mach Operating System.
514 It was subsequently ported to
515 .Bx 386 .
516 .Sh AUTHORS
517 .An -nosplit
519 for Mach Operating System was written by
520 .An Robert Baron Aq Mt rvb@cs.cmu.edu .
521 It was ported to
522 .Bx 386
524 .An Julian Elischer Aq Mt julian@tfs.com .
525 .Sh BUGS
526 Only slices s1-s4
527 .Pq primary DOS partitions
528 can be changed by
529 .Nm ,
530 s5-s30
531 .Pq slices in extended DOS partitions
532 can't be changed by
533 .Nm .
535 The default boot code will not necessarily handle all slice types
536 correctly, in particular those introduced since MS-DOS 6.x.
538 The entire program should be made more user-friendly.
540 Most users new to
542 do not understand the difference between
543 .Ar slice
545 .Ar partition
546 causing difficulty to adjust.
548 You cannot use this command to completely dedicate a disk to
549 .Dx .
551 .Xr disklabel 8
552 command must be used for this.