fdisk: bloody revolution in the man page

Signed-off-by: Karel Zak <kzak@redhat.com>

1 files changed, 169 insertions, 164 deletions

diff --git a/fdisks/fdisk.8 b/fdisks/fdisk.8
index a75558476..74e034284 100644
--- a/fdisks/fdisk.8
+++ b/fdisks/fdisk.8
@@ -1,188 +1,47 @@
 .\" Copyright 1992, 1993 Rickard E. Faith (faith@cs.unc.edu)
 .\" Copyright 1998 Andries E. Brouwer (aeb@cwi.nl)
 .\" Copyright 2012 Davidlohr Bueso <dave@gnu.org>
+.\" Copyright (C) 2013 Karel Zak <kzak@redhat.com>
 .\" May be distributed under the GNU General Public License
-.TH FDISK 8 "June 2012" "util-linux" "System Administration"
+.TH FDISK 8 "September 2013" "util-linux" "System Administration"
 
 .SH NAME
 fdisk \- manipulate disk partition table
 
 .SH SYNOPSIS
 .B fdisk
-.RB [ \-uc ]
-.RB [ \-b
-.IR sectorsize ]
-.RB [ \-C
-.IR cylinders ]
-.RB [ \-H
-.IR heads ]
-.RB [ \-S
-.IR sectors ]
+.RB [ options ]
 .I device
 .sp
 .B fdisk \-l
-.RB [ \-u ]
 .RI [ device ...]
-.sp
-.B fdisk \-s
-.IR partition ...
-.sp
-.B fdisk \-v
-.sp
-.B fdisk \-h
 
 .SH DESCRIPTION
 .B fdisk
-(in the first form of invocation)
-is a menu-driven program for creation and manipulation of
-partition tables.
-It understands DOS-type partition tables and BSD- or SUN-type disklabels.
-
-.B fdisk
-does not understand GUID partition tables (GPTs) and it is not designed
-for large partitions.  In these cases, use the more advanced GNU
-.BR parted (8).
+is a dialog-driven program for creation and manipulation of partition tables.
+It understands GPT, MBR, SUN, SGI and BSD partition tables.
 
-.B fdisk
-does not use DOS-compatible mode and cylinders as display unit
-by default anymore.
-The old deprecated DOS behavior can be enabled with
-the '-c=dos -u=cylinders' command-line options.
-
-Hard disks can be divided into one or more logical disks called
+The block devices can be divided into one or more logical disks called
 .IR partitions .
 This division is recorded in the
 .IR "partition table" ,
-found in sector 0 of the disk.
+usually found in sector 0 of the disk.
 (In the BSD world one talks about `disk slices' and a `disklabel'.)
 
-Linux needs at least one partition, namely for its root filesystem.
-It can use swap files and/or swap partitions, but the latter are more
-efficient.  So, usually one will want a second Linux partition
-dedicated as swap partition.
-On Intel-compatible hardware, the BIOS that boots the system
-can often only access the first 1024 cylinders of the disk.
-For this reason people with large disks often create a third partition,
-just a few MB large, typically mounted on
-.IR /boot ,
-to store the kernel image and a few auxiliary files needed at boot time,
-so as to make sure that this stuff is accessible to the BIOS.
-There may be reasons of security, ease of administration and backup,
-or testing, to use more than the minimum number of partitions.
-
-.SH DEVICES
-The
-.I device
-is usually /dev/sda, /dev/sdb or so.  A device name refers to the entire disk.
-Old systems without libata (a library used inside the Linux kernel to
-support ATA host controllers and devices) make a difference between IDE and
-SCSI disks.  In such cases the device name will be /dev/hd* (IDE) or /dev/sd*
-(SCSI).
-
-The
-.I partition
-is a device name followed by a partition number.  For example, /dev/sda1
-is the first partition on the first hard disk in the system.
-See also Linux kernel documentation (the Documentation/devices.txt file).
-
-.SH DISK LABELS
-A BSD/SUN-type disklabel can describe 8 partitions,
-the third of which should be a `whole disk' partition.
-Do not start a partition that actually uses its first sector
-(like a swap partition) at cylinder 0, since that will
-destroy the disklabel.
-
-An IRIX/SGI-type disklabel can describe 16 partitions,
-the eleventh of which should be an entire `volume' partition,
-while the ninth should be labeled `volume header'.
-The volume header will also cover the partition table, i.e.,
-it starts at block zero and extends by default over five cylinders.
-The remaining space in the volume header may be used by header
-directory entries.  No partitions may overlap with the volume header.
-Also do not change its type or make some filesystem on it, since
-you will lose the partition table.  Use this type of label only when
-working with Linux on IRIX/SGI machines or IRIX/SGI disks under Linux.
-
-A DOS-type partition table can describe an unlimited number
-of partitions.  In sector 0 there is room for the description
-of 4 partitions (called `primary').  One of these may be an
-extended partition; this is a box holding logical partitions,
-with descriptors found in a linked list of sectors, each
-preceding the corresponding logical partitions.
-The four primary partitions, present or not, get numbers 1-4.
-Logical partitions start numbering from 5.
-
-In a DOS-type partition table the starting offset and the size
-of each partition is stored in two ways: as an absolute number
-of sectors (given in 32 bits), and as a Cylinders/Heads/Sectors
-triple (given in 10+8+6 bits).  The former is OK -- with 512-byte
-sectors this will work up to 2 TB.  The latter has two
-problems.  First, these C/H/S fields can be filled only
-when the number of heads and the number of sectors per track
-are known.  And second, even if we know what these numbers should be,
-the 24 bits that are available do not suffice.
-DOS uses C/H/S only, Windows uses both, Linux never uses C/H/S.
-
-If possible,
+All partitioning is driven by device I/O limits (topology) by default.
 .B fdisk
-will obtain the disk geometry automatically.  This is not
-necessarily the physical disk geometry (indeed, modern disks do not
-really have anything like a physical geometry, certainly not something
-that can be described in simplistic Cylinders/Heads/Sectors form),
-but it is the disk geometry that MS-DOS uses for the partition table.
-
-Usually all goes well by default, and there are no problems if
-Linux is the only system on the disk.  However, if the disk has
-to be shared with other operating systems, it is often a good idea
-to let an fdisk from another operating system make at least one
-partition.  When Linux boots it looks at the partition table, and
-tries to deduce what (fake) geometry is required for good
-cooperation with other systems.
-
-Whenever a partition table is printed out, a consistency check is performed
-on the partition table entries.  This check verifies that the physical and
-logical start and end points are identical, and that each partition starts
-and ends on a cylinder boundary (except for the first partition).
-
-Some versions of MS-DOS create a first partition which does not begin
-on a cylinder boundary, but on sector 2 of the first cylinder.
-Partitions beginning in cylinder 1 cannot begin on a cylinder boundary, but
-this is unlikely to cause difficulty unless you have OS/2 on your machine.
+is able to optimize disk layout for 4K-sector size and use alignment offset on
+modern devices for MBR and GPT. It's always good idea to follow fdisk defaults
+as the default values (e.g. first and last partition sectors) and partition
+sizes specified by +<size>{M,G, ..} notation are always aligned according 
+to the device properties.
 
-A sync() and an ioctl(BLKRRPART) (reread partition table from disk)
-are performed before exiting when the partition table has been updated.
-Long ago it used to be necessary to reboot after the use of \fBfdisk\fR.
-I do not think this is the case anymore -- indeed, rebooting too quickly
-might cause loss of not-yet-written data.  Note that both the kernel
-and the disk hardware may buffer data.
-
-.SH "DOS 6.x WARNING"
-The DOS 6.x FORMAT command looks for some information in the first
-sector of the data area of the partition, and treats this information
-as more reliable than the information in the partition table.  DOS
-FORMAT expects DOS FDISK to clear the first 512 bytes of the data area
-of a partition whenever a size change occurs.  DOS FORMAT will look at
-this extra information even if the /U flag is given -- we consider
-this a bug in DOS FORMAT and DOS FDISK.
-
-The bottom line is that if you use cfdisk or fdisk to change the size of a
-DOS partition table entry, then you must also use
-.B dd
-to zero the first 512 bytes of that partition before using DOS FORMAT to
-format the partition.  For example, if you were using cfdisk to make a DOS
-partition table entry for /dev/sda1, then (after exiting fdisk or cfdisk
-and rebooting Linux so that the partition table information is valid) you
-would use the command "dd if=/dev/zero of=/dev/sda1 bs=512 count=1" to zero
-the first 512 bytes of the partition.
-
-.B BE EXTREMELY CAREFUL
-if you use the
-.B dd
-command, since a small typo can make all of the data on your disk useless.
-
-For best results, you should always use an OS-specific partition table
-program.  For example, you should make DOS partitions with the DOS FDISK
-program and Linux partitions with the Linux fdisk or Linux cfdisk program.
+Note that
+.B partx (1)
+provides rich interface for script to print disk layout,
+.B fdisk
+is mostly designed for humans. The backward compatibility in the fdisk output
+is not guaranteed. The input (commands) should be always backwardly compatible.
 
 .SH OPTIONS
 .TP
@@ -243,16 +102,162 @@ option by a space, the correct form is for example '-u=cylinders'.
 .B \-v
 Display version information and exit.
 
+.SH DEVICES
+The
+.I device
+is usually /dev/sda, /dev/sdb or so.  A device name refers to the entire disk.
+Old systems without libata (a library used inside the Linux kernel to support
+ATA host controllers and devices) make a difference between IDE and SCSI disks.
+In such cases the device name will be /dev/hd* (IDE) or /dev/sd* (SCSI).
+
+The
+.I partition
+is a device name followed by a partition number.  For example, /dev/sda1 is the
+first partition on the first hard disk in the system.  See also Linux kernel
+documentation (the Documentation/devices.txt file).
+
+.SH DISK LABELS
+.B GPT (GUID Partition Table)
+.RS
+GPT is modern standard for the layout of the partition table. GPT uses 64-bits
+logical block addresses, checksums, UUIDs and names for partitions and
+unlimited number of the partitions (although the number of the partition is
+usually restricted to 128 in many partitioning tools).
+
+Note that the first sector is still reserved for a
+.B protective MBR
+in the GPT specification. It prevents MBR-only partitioning tools
+to mis-recognizing and overwriting GPT disks.
+
+GPT is always better choice than MBR especially on modern hardware with UEFI
+boot loader.
+.RE
+
+.B DOS-type (MBR)
+.RS
+partition table can describe an unlimited number of partitions.  In sector 0
+there is room for the description of 4 partitions (called `primary').  One of
+these may be an extended partition; this is a box holding logical partitions,
+with descriptors found in a linked list of sectors, each preceding the
+corresponding logical partitions.  The four primary partitions, present or not,
+get numbers 1-4.  Logical partitions start numbering from 5.
+
+In a DOS-type partition table the starting offset and the size of each
+partition is stored in two ways: as an absolute number of sectors (given in 32
+bits), and as a
+.B Cylinders/Heads/Sectors
+triple (given in 10+8+6 bits).  The former is OK -- with 512-byte sectors this
+will work up to 2 TB.  The latter has two problems.  First, these C/H/S fields
+can be filled only when the number of heads and the number of sectors per track
+are known.  And second, even if we know what these numbers should be, the 24
+bits that are available do not suffice.  DOS uses C/H/S only, Windows uses
+both, Linux never uses C/H/S. The
+.B C/H/S addressing is deprecated
+and may be unssuported in some later fdisk version.
+
+.B Please, read the DOS-mode section if you want DOS compatible partitions.
+.B fdisk
+does not care about cylinders boundary by default.
+.RE
+
+.B BSD/SUN-type
+.RS
+disklabel can describe 8 partitions, the third of which should be a `whole
+disk' partition.  Do not start a partition that actually uses its first sector
+(like a swap partition) at cylinder 0, since that will destroy the disklabel.
+Note that
+.B BSD label
+is usually nested within DOS partition.
+.RE
+
+.B IRIX/SGI-type
+.RS
+disklabel can describe 16 partitions, the eleventh of which should be an entire
+`volume' partition, while the ninth should be labeled `volume header'.  The
+volume header will also cover the partition table, i.e., it starts at block
+zero and extends by default over five cylinders.  The remaining space in the
+volume header may be used by header directory entries.  No partitions may
+overlap with the volume header.  Also do not change its type or make some
+filesystem on it, since you will lose the partition table.  Use this type of
+label only when working with Linux on IRIX/SGI machines or IRIX/SGI disks under
+Linux.
+.RE
+
+A sync() and an ioctl(BLKRRPART) (reread partition table from disk)
+are performed before exiting when the partition table has been updated.
+
+.SH "DOS mode and DOS 6.x WARNING"
+.B Note that all this deprecated. You don't have to care about things like
+.B geomery and cylinders on modern operation systems. If you really want
+.B DOS compatible partitioning then you have to enable DOS-mode and cylinder
+.B units by '-c=dos -u=cylinders' fdisk command line options.
+
+The DOS 6.x FORMAT command looks for some information in the first sector of
+the data area of the partition, and treats this information as more reliable
+than the information in the partition table.  DOS FORMAT expects DOS FDISK to
+clear the first 512 bytes of the data area of a partition whenever a size
+change occurs.  DOS FORMAT will look at this extra information even if the /U
+flag is given -- we consider this a bug in DOS FORMAT and DOS FDISK.
+
+The bottom line is that if you use cfdisk or fdisk to change the size of a DOS
+partition table entry, then you must also use .B dd to zero the first 512 bytes
+of that partition before using DOS FORMAT to format the partition.  For
+example, if you were using cfdisk to make a DOS partition table entry for
+/dev/sda1, then (after exiting fdisk or cfdisk and rebooting Linux so that the
+partition table information is valid) you would use the command "dd
+if=/dev/zero of=/dev/sda1 bs=512 count=1" to zero the first 512 bytes of the
+partition.
+
+.B fdisk
+usually obtain the disk geometry automatically.  This is not necessarily the
+physical disk geometry (indeed, modern disks do not really have anything like a
+physical geometry, certainly not something that can be described in simplistic
+Cylinders/Heads/Sectors form), but it is the disk geometry that MS-DOS uses for
+the partition table.
+
+Usually all goes well by default, and there are no problems if Linux is the
+only system on the disk.  However, if the disk has to be shared with other
+operating systems, it is often a good idea to let an fdisk from another
+operating system make at least one partition.  When Linux boots it looks at the
+partition table, and tries to deduce what (fake) geometry is required for good
+cooperation with other systems.
+
+Whenever a partition table is printed out in DOS mode, a consistency check is
+performed on the partition table entries.  This check verifies that the
+physical and logical start and end points are identical, and that each
+partition starts and ends on a cylinder boundary (except for the first
+partition).
+
+Some versions of MS-DOS create a first partition which does not begin
+on a cylinder boundary, but on sector 2 of the first cylinder.
+Partitions beginning in cylinder 1 cannot begin on a cylinder boundary, but
+this is unlikely to cause difficulty unless you have OS/2 on your machine.
+
+For best results, you should always use an OS-specific partition table
+program.  For example, you should make DOS partitions with the DOS FDISK
+program and Linux partitions with the Linux fdisk or Linux cfdisk program.
+
+.SH AUTHORS
+.MT kzak@redhat.com
+Karel Zak
+.ME
+.br
+.MT dave@gnu.org
+Davidlohr Bueso
+.ME
+.br
+.PP
+The original version was written by
+Andries E. Brouwer, A. V. Le Blanc and others.
+
 .SH ENVIRONMENT
-.IP "Setting FDISK_DEBUG=0xffff enables debug output."
+.IP "Setting LIBFDISK_DEBUG=0xffff enables debug output."
 
 .SH "SEE ALSO"
 .BR cfdisk (8),
 .BR sfdisk (8),
 .BR mkfs (8),
-.BR parted (8),
-.BR partprobe (8),
-.BR kpartx (8)
+.BR partx (8)
 
 .SH AVAILABILITY
 The fdisk command is part of the util-linux package and is available from