README

   1 GPT fdisk (aka gdisk, cgdisk, and sgdisk) and FixParts
   2 by Roderick W. Smith, rodsmith@rodsbooks.com
   3
   4 Introduction
   5 ------------
   6
   7 This package includes the source code for four related disk partitioning
   8 programs:
   9
  10 - gdisk -- This program is modeled after Linux fdisk, but it operates on
  11   GUID Partition Table (GPT) disks rather than the Master Boot Record (MBR)
  12   disks that fdisk modifies. As such, gdisk is an interactive text-mode
  13   tool for manipulating partitions, but it does nothing to the contents of
  14   those partitions (usually filesystems, but sometimes swap space or other
  15   data).
  16
  17 - cgdisk -- This program is modeled after Linux cfdisk, but it operates on
  18   GPT disks rather than the MBR disks that cfdisk modifies. As such, cgdisk
  19   is a curses-based text-mode tool for manipulating partitions, which is to
  20   say that it uses an interface that relies on arrow keys and a dynamic
  21   display rather than the command letters and a scrolling display like
  22   gdisk uses.
  23
  24 - sgdisk -- This program is conceptually similar to the Linux sfdisk and
  25   FreeBSD gpt programs, but its operational details differ. It enables
  26   manipulation of GPT disks using command-line options, so it's suitable
  27   for use in scripts or by experts to perform specific tasks that might
  28   take several commands in gdisk to accomplish.
  29
  30 - fixparts -- This program, unlike the preceding three, operates on MBR
  31   disks. It's intended to fix certain problems that can be created by
  32   various utilities. Specifically, it can fix mis-sized extended partitions
  33   and primary partitions located in the middle of extended partitions. It
  34   also enables changing primary vs. logical partition status (within limits
  35   of what's legal in the MBR scheme) and making a few other minor changes.
  36   It does NOT support creating new partitions; for that, you should use
  37   fdisk, parted, or some other tool.
  38
  39 More details about the abilities of these tools follows.
  40
  41 All four programs rely on the same set of underlying code base; they differ
  42 only in their control interfaces (defined in gdisk.cc, cgdisk.cc,
  43 sgdisk.cc, and fixparts.cc, respectively) and in which support code they
  44 use.
  45
  46 GPT fdisk (gdisk, cgdisk, and sgdisk) Details
  47 ---------------------------------------------
  48
  49 The gdisk program is intended as a (somewhat) fdisk-workalike program for
  50 GPT-partitioned disks, cgdisk is similarly a workalike for fdisk, and
  51 sgdisk provides most of gdisk's functionality in a more script-friendly
  52 program. Although libparted and programs that use it (GNU Parted, gparted,
  53 etc.) provide the ability to handle GPT disks, they have certain
  54 limitations that gdisk overcomes. Specific advantages of gdisk, cgdisk, and
  55 sgdisk include:
  56
  57 * The ability to convert MBR-partitioned disks in-place to GPT format,
  58   without losing data
  59
  60 * The ability to convert BSD disklabels in-place to create GPT
  61   partitions, without losing data
  62
  63 * The ability to convert from GPT format to MBR format without data loss
  64   (gdisk and sgdisk only)
  65
  66 * More flexible specification of filesystem type code GUIDs, which
  67   GNU Parted tends to corrupt
  68
  69 * Clear identification of the number of unallocated sectors on a
  70   disk
  71
  72 * A user interface that's familiar to long-time users of Linux
  73   fdisk and cfdisk (gdisk and cgdisk only)
  74
  75 * The MBR boot loader code is left alone
  76
  77 * The ability to create a hybrid MBR, which permits GPT-unaware OSes to
  78   access up to three GPT partitions on the disk (gdisk and sgdisk only)
  79
  80 Of course, GPT fdisk isn't without its limitations. Most notably, it lacks
  81 the filesystem awareness and filesystem-related features of GNU Parted. You
  82 can't resize a partition's filesystem or create a partition with a
  83 filesystem already in place with gdisk, for instance. There's no GUI
  84 version of gdisk.
  85
  86 The GPT fdisk package provides three program files: the interactive
  87 text-mode gdisk, the curses-based interactive cgdisk, and the
  88 command-line-driven sgdisk. The first two are intended for use in manually
  89 partitioning disks or changing partitioning details; sgdisk is intended for
  90 use in scripts to help automate tasks such as disk cloning or preparing
  91 multiple disks for Linux installation.
  92
  93 FixParts Details
  94 ----------------
  95
  96 This program's creation was motivated by cries for help I've seen in online
  97 forums from users who have found their partition tables to be corrupted by
  98 various buggy partitioning tools. Although most OSes can handle the
  99 afflicted disks fine, libparted-based tools (GParted, parted, most Linux
 100 installers, etc.) tend to flake out when presented with these disks.
 101 Typically, the symptom is a disk that appears to hold no partitions;
 102 however, sometimes the libparted tool presents partitions other than those
 103 that the OS sees.
 104
 105 I've observed four causes of these symptoms, three of which FixParts can
 106 correct:
 107
 108 * Old GPT data -- If a disk is used as a GPT disk and then re-used as an
 109   MBR disk, the GPT data may be incompletely erased. This happens if the
 110   disk is repartitioned with fdisk or the Microsoft Windows installer, for
 111   instance. (Tools based on libparted correctly remove the old GPT data
 112   when converting from GPT to MBR format.) FixParts checks for this problem
 113   when it starts and offers to correct it. If you opt to erase the GPT
 114   data, this erasure occurs immediately, unlike other changes the program
 115   makes.
 116
 117 * Mis-sized extended partitions -- Some tools create an extended partition
 118   that's too large, typically ending after the last sector of the disk.
 119   FixParts automatically corrects this problem (if you use the 'w' option
 120   to save the partition table).
 121
 122 * Primary partitions inside an extended partition -- Some utilities create
 123   or move primary partitions to within the range covered by the extended
 124   partition. FixParts can usually correct this problem by turning the
 125   primary partition into a logical partition or by changing one or more
 126   other logical partitions into primaries. Such corrections aren't always
 127   possible, though, at least not without deleting or resizing other
 128   partitions.
 129
 130 * Leftover RAID data -- If a disk is used in a RAID array and then re-used
 131   as a non-RAID disk, some utilities can become confused and fail to see
 132   the disk. FixParts can NOT correct this problem. You must destroy the old
 133   RAID data, or possibly remove the dmraid package from the system, to fix
 134   this problem.
 135
 136 When run, FixParts presents an fdisk-like interface, enabling you to adjust
 137 partition types (primary, logical, or omitted), change type codes, change
 138 the bootable flag, and so on. Although you can delete a partition (by
 139 omitting it), you can't create new partitions with the program. If you're
 140 used to partitioning disks, particularly with Linux fdisk, two unusual
 141 features of FixParts require elaboration:
 142
 143 * No extended partitions -- Internally, FixParts reads the partition table
 144   and discards data on any extended partition(s) it finds. When you save
 145   the partition table, the program generates a new extended partition. This
 146   design means that the program automatically corrects many problems
 147   related to the extended partition. It also means that you'll see no
 148   evidence of extended partitions in the FixParts user interface, although
 149   it keeps track of the requirements and prevents you from creating illegal
 150   layouts, such as a primary between two logicals.
 151
 152 * Partition numbering -- In most Linux tools, partitions 1-4 are primaries
 153   and partitions 5 and up are logicals. Although a legal partition table
 154   loaded into FixParts will initially conform to this convention, some
 155   types of damaged table might not, and various changes you make can also
 156   cause deviations. When FixParts writes the partition table, its numbering
 157   will be altered to conform to the standard MBR conventions, but you
 158   should use the explicit labeling of partitions as primary or logical
 159   rather than the partition numbers to determine a partition's status.
 160
 161 Installing
 162 ----------
 163
 164 To compile GPT fdisk, you must have appropriate development tools
 165 installed, most notably the GNU Compiler Collection (GCC) and its g++
 166 compiler for C++. (Under Windows, Microsoft Visual C++ 2008 can also be
 167 used.) In addition, note these requirements:
 168
 169 * On Linux, FreeBSD, and OS X, libuuid must be installed. This is the
 170   standard for Linux and OS X, although you may need to install a package
 171   called uuid-dev or something similar to get the headers. On FreeBSD, the
 172   e2fsprogs-libuuid port must be installed.
 173
 174 * The ICU library (http://site.icu-project.org), which provides support for
 175   Unicode partition names, is recommended on all
 176   platforms except Windows. This library is normally installed in Linux and
 177   OS X, but you may need to install the development headers (libicu-dev or
 178   something similar in Linux; or the libicu36-dev Fink package in OS X). To
 179   compile without ICU support, you must modify the Makefile: Remove the
 180   "-D USE_UTF16" part from the CXXFLAGS line and remove references to
 181   -licuio, -licuuc, -licudata, and -licucore (details vary between
 182   platforms) from the compilation options. Suitable lines are present, but
 183   commented out, in the Makefile, Makefile.mac, and Makefile.bsd files.
 184
 185 * The cgdisk program requires the ncurses library and its development files
 186   (headers). Most Linux distributions install ncurses by default, but you
 187   may need to install a package called libncurses5-dev, ncurses-devel, or
 188   something similar to obtain the header files. These files were installed
 189   already on my Mac OS X development system; however, they may have been
 190   installed as dependencies of other programs I've installed. If you're
 191   having problems installing ncurses, you can compile gdisk and/or sgdisk
 192   without cgdisk by specifying only the targets you want to compile to
 193   make.
 194
 195 * The sgdisk program requires the popt library and its development files
 196   (headers). Most Linux distributions install popt by default, but you may
 197   need to install a package called popt-dev, popt-devel, or something
 198   similar to obtain the header files. Mac OS users can find a version of
 199   popt for Mac OS from Darwin Ports (http://popt.darwinports.com) or Fink
 200   (http://www.finkproject.org); however, you'll first need to install
 201   DarwinPorts or Fink (instructions exist on the relevant projects' pages).
 202   Alternatively, you can compile gdisk and/or cgdisk alone, without sgdisk;
 203   gdisk doesn't require popt.
 204
 205 When all the necessary development tools and libraries are installed, you
 206 can uncompress the package and type "make" at the command prompt in the
 207 resulting directory. (You may need to type "make -f Makefile.mac" on Mac OS
 208 X, "make -f Makefile.freebsd" on FreeBSD, or "make -f Makefile.mingw" to
 209 compile using MinGW for Windows.) You may also need to add header (include)
 210 directories or library directories by setting the CXXFLAGS environment
 211 variable or by editing the Makefile. The result should be program files
 212 called gdisk, sgdisk, and fixparts. Typing "make gdisk", "make cgdisk",
 213 "make sgdisk", or "make fixparts" will compile only the requested programs.
 214 You can use these programs in place or copy the files to a suitable
 215 directory, such as /usr/local/sbin. You can copy the man pages (gdisk.8,
 216 cgdisk.8, sgdisk.8, and fixparts.8) to /usr/local/man/man8 to make them
 217 available.
 218
 219 Caveats
 220 -------
 221
 222 THIS SOFTWARE IS BETA SOFTWARE! IF IT WIPES OUT YOUR HARD DISK OR EATS YOUR
 223 CAT, DON'T BLAME ME! To date, I've tested the software on several USB flash
 224 drives, physical hard disks, and virtual disks in the QEMU and VirtualBox
 225 environments. Many others have now used the software on their computers, as
 226 well. I believe all data-corruption bugs to be squashed, but I know full well
 227 that the odds of my missing something are high. This is particularly true for
 228 large (over-2TiB) drives; my only direct testing with such disks is with
 229 virtual QEMU and VirtualBox disks. I've received user reports of success with
 230 RAID arrays over 2TiB in size, though.
 231
 232 My main development platform is a system running the 64-bit version of
 233 Gentoo Linux (previously Ubuntu 8.04). I've also tested on several other
 234 32- and 64-bit Linux distributions, Intel-based Mac OS X 10.5 and 10.6,
 235 64-bit FreeBSD 7.1, and Windows 7.
 236
 237 Redistribution
 238 --------------
 239
 240 This program is licensed under terms of the GNU GPL (see the file COPYING).
 241
 242 Acknowledgements
 243 ----------------
 244
 245 This code is mostly my own; however, I've used three functions from two
 246 other GPLed programs:
 247
 248 - The code used to generate CRCs is taken from the efone program by
 249   Krzysztof Dabrowski and ElysiuM deeZine. (See the crc32.h and
 250   crc32.cc source code files.)
 251
 252 - A function to find the disk size is taken from Linux fdisk by A. V. Le
 253   Blanc. This code has subsequently been heavily modified.
 254
 255 Additional code contributors include:
 256
 257 - Yves Blusseau (1otnwmz02@sneakemail.com)
 258
 259 - David Hubbard (david.c.hubbard@gmail.com)
 260
 261 - Justin Maggard (justin.maggard@netgear.com)
 262
 263 - Dwight Schauer (dschauer@ti.com)
 264
 265 - Florian Zumbiehl (florz@florz.de)
 266
 267 - Guillaume Delacour (contributed the gdisk_test.sh script)