srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 1 | GPT fdisk (aka gdisk, cgdisk, and sgdisk) and FixParts |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 2 | by Roderick W. Smith, rodsmith@rodsbooks.com |
| 3 | |
| 4 | Introduction |
| 5 | ------------ |
| 6 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 7 | This package includes the source code for four related disk partitioning |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 8 | programs: |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 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 | |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 30 | - fixparts -- This program, unlike the preceding three, operates on MBR |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 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. |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 45 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 46 | GPT fdisk (gdisk, cgdisk, and sgdisk) Details |
| 47 | --------------------------------------------- |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 48 | |
| 49 | The gdisk program is intended as a (somewhat) fdisk-workalike program for |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 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: |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 56 | |
| 57 | * The ability to convert MBR-partitioned disks in-place to GPT format, |
| 58 | without losing data |
| 59 | |
srs5694 | 221e087 | 2009-08-29 15:00:31 -0400 | [diff] [blame] | 60 | * The ability to convert BSD disklabels in-place to create GPT |
| 61 | partitions, without losing data |
| 62 | |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 63 | * The ability to convert from GPT format to MBR format without data loss |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 64 | (gdisk and sgdisk only) |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 65 | |
| 66 | * More flexible specification of filesystem type code GUIDs, which |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 67 | GNU Parted tends to corrupt |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 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 |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 73 | fdisk and cfdisk (gdisk and cgdisk only) |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 74 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 75 | * The MBR boot loader code is left alone |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 76 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 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) |
srs5694 | 221e087 | 2009-08-29 15:00:31 -0400 | [diff] [blame] | 79 | |
srs5694 | 3c0af38 | 2010-01-15 19:19:18 -0500 | [diff] [blame] | 80 | Of course, GPT fdisk isn't without its limitations. Most notably, it lacks |
srs5694 | 0741fa2 | 2013-01-09 12:55:40 -0500 | [diff] [blame] | 81 | the filesystem awareness and filesystem-related features of GParted. You |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 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 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 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. |
srs5694 | 3c0af38 | 2010-01-15 19:19:18 -0500 | [diff] [blame] | 92 | |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 108 | * Old GPT data -- If a disk is used as a GPT disk and then re-used as an |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 117 | * Mis-sized extended partitions -- Some tools create an extended partition |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 122 | * Primary partitions inside an extended partition -- Some utilities create |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 130 | * Leftover RAID data -- If a disk is used in a RAID array and then re-used |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 143 | * No extended partitions -- Internally, FixParts reads the partition table |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | 699941e | 2011-03-21 21:33:57 -0400 | [diff] [blame] | 152 | * Partition numbering -- In most Linux tools, partitions 1-4 are primaries |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 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 | |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 161 | Installing |
| 162 | ---------- |
| 163 | |
srs5694 | 3c0af38 | 2010-01-15 19:19:18 -0500 | [diff] [blame] | 164 | To compile GPT fdisk, you must have appropriate development tools |
| 165 | installed, most notably the GNU Compiler Collection (GCC) and its g++ |
Roderick W. Smith | 1eea9b0 | 2013-07-06 22:52:58 -0400 | [diff] [blame] | 166 | compiler for C++. I've also tested compilation with Clang, which seems to |
| 167 | work; however, I've not done extensive testing of the resulting binaries, |
| 168 | beyond checking a few basics. Under Windows, Microsoft Visual C++ 2008 can |
| 169 | be used instead. In addition, note these requirements: |
srs5694 | 6699b01 | 2010-02-04 00:55:30 -0500 | [diff] [blame] | 170 | |
srs5694 | 0741fa2 | 2013-01-09 12:55:40 -0500 | [diff] [blame] | 171 | * On Linux, FreeBSD, OS X, and Solaris, libuuid must be installed. This is |
| 172 | the standard for Linux and OS X, although you may need to install a |
| 173 | package called uuid-dev or something similar to get the headers. On |
| 174 | FreeBSD, the e2fsprogs-libuuid port must be installed. |
srs5694 | 6699b01 | 2010-02-04 00:55:30 -0500 | [diff] [blame] | 175 | |
srs5694 | 00b6d7a | 2011-06-26 22:40:06 -0400 | [diff] [blame] | 176 | * The ICU library (http://site.icu-project.org), which provides support for |
Roderick W. Smith | 84aaff6 | 2014-02-17 16:17:11 -0500 | [diff] [blame] | 177 | Unicode partition names, is optional on all platforms except Windows, on |
| 178 | which it's not supported. Using this library was required to get proper |
| 179 | UTF-16 partition name support in GPT fdisk versions prior to 0.8.9, but |
| 180 | as of that version it should not longer be required. Nonetheless, you can |
| 181 | use it if you're having problems with the new UTF-16 support. This |
| 182 | library is normally installed in Linux and OS X, but you may need to |
| 183 | install the development headers (libicu-dev or something similar in |
| 184 | Linux; or the libicu36-dev Fink package in OS X). To compile with ICU |
| 185 | support, you must modify the Makefile: Look for commented-out lines that |
| 186 | refer to USE_UTF16, -licuuc, -licudata, or -licucore. Uncomment them and |
| 187 | comment out the equivalents that lack these lines. |
srs5694 | 5a60853 | 2011-03-17 13:53:01 -0400 | [diff] [blame] | 188 | |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 189 | * The cgdisk program requires the ncurses library and its development files |
| 190 | (headers). Most Linux distributions install ncurses by default, but you |
| 191 | may need to install a package called libncurses5-dev, ncurses-devel, or |
| 192 | something similar to obtain the header files. These files were installed |
| 193 | already on my Mac OS X development system; however, they may have been |
| 194 | installed as dependencies of other programs I've installed. If you're |
| 195 | having problems installing ncurses, you can compile gdisk and/or sgdisk |
| 196 | without cgdisk by specifying only the targets you want to compile to |
| 197 | make. |
| 198 | |
| 199 | * The sgdisk program requires the popt library and its development files |
| 200 | (headers). Most Linux distributions install popt by default, but you may |
| 201 | need to install a package called popt-dev, popt-devel, or something |
| 202 | similar to obtain the header files. Mac OS users can find a version of |
Aurimas Liutikas | bdbab02 | 2017-03-07 09:50:36 -0800 | [diff] [blame] | 203 | popt for Mac OS from Darwin Ports (http://popt.darwinports.com) or Fink |
| 204 | (http://www.finkproject.org); however, you'll first need to install |
| 205 | DarwinPorts or Fink (instructions exist on the relevant projects' pages). |
| 206 | Alternatively, you can compile gdisk and/or cgdisk alone, without sgdisk; |
| 207 | gdisk doesn't require popt. |
srs5694 | ba00fed | 2010-01-12 18:18:36 -0500 | [diff] [blame] | 208 | |
| 209 | When all the necessary development tools and libraries are installed, you |
| 210 | can uncompress the package and type "make" at the command prompt in the |
srs5694 | 6699b01 | 2010-02-04 00:55:30 -0500 | [diff] [blame] | 211 | resulting directory. (You may need to type "make -f Makefile.mac" on Mac OS |
srs5694 | 0741fa2 | 2013-01-09 12:55:40 -0500 | [diff] [blame] | 212 | X, "make -f Makefile.freebsd" on FreeBSD, "make -f Makefile.solaris" on |
| 213 | Solaris, or "make -f Makefile.mingw" to compile using MinGW for Windows.) |
| 214 | You may also need to add header (include) directories or library |
| 215 | directories by setting the CXXFLAGS environment variable or by editing the |
| 216 | Makefile. The result should be program files called gdisk, cgdisk, sgdisk, |
| 217 | and fixparts. Typing "make gdisk", "make cgdisk", "make sgdisk", or "make |
| 218 | fixparts" will compile only the requested programs. You can use these |
| 219 | programs in place or copy the files to a suitable directory, such as |
| 220 | /usr/local/sbin. You can copy the man pages (gdisk.8, cgdisk.8, sgdisk.8, |
| 221 | and fixparts.8) to /usr/local/man/man8 to make them available. |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 222 | |
| 223 | Caveats |
| 224 | ------- |
| 225 | |
srs5694 | 5d58fe0 | 2010-01-03 20:57:08 -0500 | [diff] [blame] | 226 | THIS SOFTWARE IS BETA SOFTWARE! IF IT WIPES OUT YOUR HARD DISK OR EATS YOUR |
| 227 | CAT, DON'T BLAME ME! To date, I've tested the software on several USB flash |
srs5694 | 00b6d7a | 2011-06-26 22:40:06 -0400 | [diff] [blame] | 228 | drives, physical hard disks, and virtual disks in the QEMU and VirtualBox |
| 229 | environments. Many others have now used the software on their computers, as |
| 230 | well. I believe all data-corruption bugs to be squashed, but I know full well |
| 231 | that the odds of my missing something are high. This is particularly true for |
| 232 | large (over-2TiB) drives; my only direct testing with such disks is with |
| 233 | virtual QEMU and VirtualBox disks. I've received user reports of success with |
| 234 | RAID arrays over 2TiB in size, though. |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 235 | |
| 236 | My main development platform is a system running the 64-bit version of |
srs5694 | 0741fa2 | 2013-01-09 12:55:40 -0500 | [diff] [blame] | 237 | Gentoo Linux. I've also tested on several other 32- and 64-bit Linux |
| 238 | distributions, Intel-based Mac OS X 10.5 and 10.6, 64-bit FreeBSD 7.1, and |
| 239 | Windows 7. |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 240 | |
| 241 | Redistribution |
| 242 | -------------- |
| 243 | |
| 244 | This program is licensed under terms of the GNU GPL (see the file COPYING). |
| 245 | |
| 246 | Acknowledgements |
| 247 | ---------------- |
| 248 | |
| 249 | This code is mostly my own; however, I've used three functions from two |
| 250 | other GPLed programs: |
| 251 | |
| 252 | - The code used to generate CRCs is taken from the efone program by |
| 253 | Krzysztof Dabrowski and ElysiuM deeZine. (See the crc32.h and |
| 254 | crc32.cc source code files.) |
| 255 | |
srs5694 | 9ba5421 | 2010-05-18 23:24:02 -0400 | [diff] [blame] | 256 | - A function to find the disk size is taken from Linux fdisk by A. V. Le |
| 257 | Blanc. This code has subsequently been heavily modified. |
srs5694 | e7b4ff9 | 2009-08-18 13:16:10 -0400 | [diff] [blame] | 258 | |
| 259 | Additional code contributors include: |
| 260 | |
| 261 | - Yves Blusseau (1otnwmz02@sneakemail.com) |
| 262 | |
srs5694 | 7f244ba | 2009-08-18 14:22:12 -0400 | [diff] [blame] | 263 | - David Hubbard (david.c.hubbard@gmail.com) |
srs5694 | bf8950c | 2011-03-12 01:23:12 -0500 | [diff] [blame] | 264 | |
| 265 | - Justin Maggard (justin.maggard@netgear.com) |
| 266 | |
| 267 | - Dwight Schauer (dschauer@ti.com) |
| 268 | |
| 269 | - Florian Zumbiehl (florz@florz.de) |
srs5694 | f502e52 | 2011-09-10 21:23:51 -0400 | [diff] [blame] | 270 | |
| 271 | - Guillaume Delacour (contributed the gdisk_test.sh script) |