1 GPT fdisk (aka gdisk, cgdisk, and sgdisk) and FixParts 2 by Roderick W. Smith, rodsmith (a] 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 GParted. 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++. 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: 170 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. 175 176 * The ICU library (http://site.icu-project.org), which provides support for 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. 188 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 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. 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 211 resulting directory. (You may need to type "make -f Makefile.mac" on Mac OS 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. 222 223 Caveats 224 ------- 225 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 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. 235 236 My main development platform is a system running the 64-bit version of 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. 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 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. 258 259 Additional code contributors include: 260 261 - Yves Blusseau (1otnwmz02 (a] sneakemail.com) 262 263 - David Hubbard (david.c.hubbard (a] gmail.com) 264 265 - Justin Maggard (justin.maggard (a] netgear.com) 266 267 - Dwight Schauer (dschauer (a] ti.com) 268 269 - Florian Zumbiehl (florz (a] florz.de) 270 271 - Guillaume Delacour (contributed the gdisk_test.sh script) 272
