A cgdisk Walkthrough

by Rod Smith, rodsmith@rodsbooks.com

Last Web page update: 9/10/2011, referencing GPT fdisk version 0.8.0

I'm a technical writer and consultant specializing in Linux technologies. This Web page, and the associated software, is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find GPT fdisk or this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!

Donate $1.00 Donate $2.50 Donate $5.00 Donate $10.00 Donate $20.00 Donate another value
Donate with PayPal
Donate with PayPal
Donate with PayPal
Donate with PayPal
Donate with PayPal
Donate with PayPal

Note: This page is part of the documentation for my GPT fdisk program.

Windows Information

I do not provide a Windows binary of cgdisk. In theory, one can be built with the help of the Ncurses for Windows library; however, I have never tested this combination and so I can't guarantee that it will work. I have built and tested cgdisk under Linux, FreeBSD, and Mac OS X 10.6.

GPT fdisk consists of three programs:

A fourth tool, FixParts, is part of the GPT fdisk source package but is different enough that it's often distributed separately. This page documents use of the cgdisk tool. Separate pages provide similar documentation for gdisk and sgdisk, A gdisk Walkthrough and An sgdisk Walkthrough.

The GPT fdisk package includes a man page that documents the cgdisk program in the usual way. If you want to read up on all its options, please refer to that document. This page takes a different approach: It walks you through some common operations, explaining each one.

This walkthrough uses as a starting point the partitioning of a 7.5 GiB USB flash drive so that it contains three partitions: One FAT partition for data exchange among multiple OSes, one ext3fs partition for use by Linux alone, and one HFS+ partition for use by OS X. This scenario is admittedly somewhat artificial, since most people don't use USB flash drives in this way; but this is similar to what you might do when setting up a hard disk for use by multiple OSes, or perhaps even one OS.

You must launch cgdisk with administrative privileges on all platforms except when editing disk image files or, on some systems, removable disks. Under Linux, FreeBSD, or OS X, this is done by logging in as the root user, using su to acquire root privileges, or using the sudo utility to launch cgdisk. Under Windows, you can right-click the Command Prompt program and select the "Run as Administrator" option, then use the resulting window to run cgdisk.

You launch cgdisk in much the same way as cfdisk, although cgdisk supports no command-line arguments except for the device specification. This varies from one OS to another:

The starting point for this walkthrough is a drive with a single FAT partition in an MBR partition table. This starting point illustrates what happens when you start cgdisk on a disk with an existing MBR partition table:

# cgdisk /dev/sdc
Warning! Non-GPT or damaged disk detected! This program will attempt to
convert to GPT form or repair damage to GPT data structures, but may not
succeed. Use gdisk or another disk repair tool if you have a damaged GPT
disk.





                         Press any key to continue....

This example demonstrates the warning message that cgdisk displays when it encounters a non-GPT disk or a disk with damaged GPT data structures. In this case, this warning is normal, but if you were launching the program on a healthy GPT disk, you should not see this warning. Like other GPT fdisk programs, cgdisk automatically converts MBR or BSD disks to GPT form, but it warns you of this fact by displaying the preceding warning. A second warning appeared on the disk I used for testing:

Warning! Problems found on disk! Use the Verify function to learn more.
Using gdisk or some other program may be necessary to repair the problems.







                         Press any key to continue....

This particular warning appeared because the existing partition was too big—it overlapped with the backup GPT data structures at the end of the disk. If you want to completely erase the partitions on the disk (as in this walkthrough), this isn't a problem; but if you see such a message on an existing GPT disk, you should heed the warning and investigate the problem before proceeding. The Repairing GPT Disks page describes some common GPT repair scenarios.

Once you've cleared the warnings, the main cgdisk menu appears:

                                  cgdisk 0.8.0

                              Disk Drive: /dev/sdc
                            Size: 15654912, 7.5 GiB

Part. #     Size        Partition Type            Partition Name
----------------------------------------------------------------
   1        7.5 GiB     Microsoft basic data      Microsoft basic data






    [ Align  ]  [ Backup ]  [ Delete ]  [  Help  ]  [  Info  ]  [  Load  ]
    [  naMe  ]  [  Quit  ]  [  Type  ]  [ Verify ]  [ Write  ]

                      Change the filesystem type code GUID

The display is broken into three main sections:

With the existence of this single partition as (presumably) sufficient identification that this is the disk you want to modify, the Delete command deletes the partition. You can either use the left or right arrow key to select Delete and then press Enter to do the deed, or press the D key on the keyboard. Either way, the partition will be deleted, and in its place, cgdisk displays free space.

At this point you presumably want to begin adding your new partitions. As with cfdisk, you can use New to do this task (this option appears when you select free space in the partition list). cgdisk asks you for four pieces of information:

First sector (40-15654878, default = 40): 
Size in sectors or {KMGTP} (default = 15654839): 2G
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): 0700
Current partition name is ''
Enter new partition name, or  to use the current name:
Shared data

In this example, I've created a partition that begins at sector 40, that's 2 GiB in size, that has a partition type code of 0x0700, and that has a name of Shared data. Most of this information is self-explanatory, but partition type codes require explanation. In GPT, partitions are assigned codes to signify the filesystem or other type of data they contain. These codes are 32-byte GUIDs, which are awkward to remember and enter. Therefore, the GPT fdisk programs, including cgdisk, use a 2-byte (4-character hexadecimal) code for quicker entry. Most of these codes are based on the equivalent MBR codes, but multiplied by 0x0100. Thus, the MBR code 0x07 (for NTFS) becomes the GPT fdisk code 0x0700. If you don't recall the code, you can view a list of codes by typing L at the code entry prompt:

Hex code or GUID (L to show codes, Enter = 8300): L
0700 Microsoft basic data  0c01 Microsoft reserved    2700 Windows RE          
4200 Windows LDM data      4201 Windows LDM metadata  7501 IBM GPFS            
7f00 ChromeOS kernel       7f01 ChromeOS root         7f02 ChromeOS reserved   
8200 Linux swap            8300 Linux filesystem      8301 Linux reserved      
8e00 Linux LVM             a500 FreeBSD disklabel     a501 FreeBSD boot        
a502 FreeBSD swap          a503 FreeBSD UFS           a504 FreeBSD ZFS         
a505 FreeBSD Vinum/RAID    a800 Apple UFS             a901 NetBSD swap         
a902 NetBSD FFS            a903 NetBSD LFS            a904 NetBSD concatenated 
a905 NetBSD encrypted      a906 NetBSD RAID           ab00 Apple boot          
af00 Apple HFS/HFS+        af01 Apple RAID            af02 Apple RAID offline  
af03 Apple label           af04 AppleTV recovery      af05 Apple Core Storage  
be00 Solaris boot          bf00 Solaris root          bf01 Solaris /usr & Mac Z
bf02 Solaris swap          bf03 Solaris backup        bf04 Solaris /var        
bf05 Solaris /home         bf06 Solaris alternate se  bf07 Solaris Reserved 1  
bf08 Solaris Reserved 2    bf09 Solaris Reserved 3    bf0a Solaris Reserved 4  
bf0b Solaris Reserved 5    c001 HP-UX data            c002 HP-UX service       
ef00 EFI System            ef01 MBR partition scheme  ef02 BIOS boot partition 
fd00 Linux RAID

You may find that the software changes your starting sector values. See the "Partitioning Advice" page for details on why this is done.

The partition list is now updated to show the new partition, plus two remaining sections of free space:

                                  cgdisk 0.8.0

                              Disk Drive: /dev/sdc
                            Size: 15654912, 7.5 GiB

Part. #     Size        Partition Type            Partition Name
----------------------------------------------------------------
            3.0 KiB     free space
   1        2.0 GiB     Microsoft basic data      Shared data
            5.5 GiB     free space




    [ Align  ]  [ Backup ]  [  Help  ]  [  Load  ]  [  New   ]  [  Quit  ]
    [ Verify ]  [ Write  ]

                      Create new partition from free space

The small 3 KiB free space area exists because of partition alignment issues. (On hard disks, it's likely to be closer to 1 MiB.) Although it's possible to create a partition in this space, doing so is usually inadvisable. The free space after the new partition is available for use. Selecting each in turn, I'll create two new partitions:

First sector (4194344-15654878, default = 4194344): 
Size in sectors or {KMGTP} (default = 15654839): 3G
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): 
Current partition name is ''
Enter new partition name, or  to use the current name:
Linux data

First sector (10485800-15654878, default = 10485800):
Size in sectors or {KMGTP} (default = 15654839): 
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): af00
Current partition name is ''
Enter new partition name, or  to use the current name:
HFS+ data

The second partition, which will hold a Linux ext3 filesystem, receives the new (as of GPT fdisk 0.7.2) 0x8300 type code. Prior to June of 2011, no official Linux filesystem GUID type code existed; Linux partitions typically took the same code as Windows partitions. This can cause problems, though, because Windows sees the Linux partitions as unformatted Windows partitions, and offers to format them—something you don't want to do! The new 0x8300 type code (or 0FC63DAF-8483-4772-8E79-3D69D8477DE4) avoids that problem, so I recommend you use it on Linux partitions. For the final partition, I used the default partition size rather than enter a value explicitly; and I gave it a 0xaf00 type code, which flags it with the GUID for Mac OS X data.

The final result looks like this:

                                  cgdisk 0.8.0

                              Disk Drive: /dev/sdc
                            Size: 15654912, 7.5 GiB

Part. #     Size        Partition Type            Partition Name
----------------------------------------------------------------
            3.0 KiB     free space
   1        2.0 GiB     Microsoft basic data      Shared data
   2        3.0 GiB     Linux filesystem          Linux data
   3        2.5 GiB     Apple HFS/HFS+            HFS+ data





    [ Align  ]  [ Backup ]  [ Delete ]  [  Help  ]  [  Info  ]  [  Load  ]
    [  naMe  ]  [  Quit  ]  [  Type  ]  [ Verify ]  [ Write  ]

                      Change the filesystem type code GUID

Before saving your changes, you may want to verify that there are no glaring problems with the GPT data structures. You can do this with the Verify command, which produces a report like this:

No problems found. 6 free sectors (3.0 KiB) available in 1
segments, the largest of which is 6 (3.0 KiB) in size

In this case, only the one small chunk of free space at the start of the disk is available for allocation and no problems were found. If cgdisk found problems, such as overlapping partitions or mismatched main and backup partition tables, it would report them here. Of course, cgdisk includes safeguards to ensure that you can't create such problems yourself. The Verify option's sanity checks are intended to help you spot problems that might result from data corruption.

If problems had been detected, you might be able to correct them using various options on the gdisk recovery & transformation menu. Because cgdisk is intended to be a user-friendly tool for less technically-inclined users rather than a thorough data-repair tool, cgdisk omits the repair and other advanced options of gdisk. The "Repairing GPT Disks" page describes use of gdisk's recovery options in more detail.

With the partitions defined and verified, use Write to write the partition table to disk. (Up until now, the changes have existed only in memory.) The program asks for verification:

  Are you sure you want to write the partition table to disk? (yes or no): 

              Warning!! This may destroy data on your disk!

You must type yes or no to this prompt. Single-letter responses and other variants won't be accepted. The main menu will reappear when the operation finishes.

Note for FreeBSD users: A limitation of the FreeBSD version of cgdisk is that it can't ordinarily write to a disk if any partitions from that disk are mounted. If you want to change your boot disk, you'll need to do so from an emergency system or type sysctl kern.geom.debugflags=16 prior to launching cgdisk.

Additional options include the following:

Some of these options are meaningful, and available, only when you've selected a partition (rather than free space) in the partition display.

Once you're done making changes, you can select Quit to exit from cgdisk. Be sure to use Write to save your changes first, though, unless of course you want to abandon them!

You're now back at your shell prompt. Because cgdisk doesn't create filesystems, you'll need to do that at your shell prompt. In the case of the 3-partition disk in this example, you can create two filesystems in Linux:

# mkdosfs /dev/sdc1
# mkfs -t ext3 /dev/sdc2

These commands work just as they would on MBR partitions. The example disk's third partition, which is intended for use in Mac OS X, may be better formatted in that OS than in Linux, although a Linux tool for doing the job, newfs_hfs or mkfs.hfsplus, is available.

Caution: If cgdisk reports that the kernel is still using the old partition table, do not try to create filesystems on or otherwise use your new partitions until you've rebooted! Your new filesystem may be written to the wrong partition (possibly one with valuable data) or written to a location on the disk where you won't be able to find it.

Go on to "An sgdisk Walkthrough"

Return to "GPT fdisk" main page


If you have problems with or comments about this web page, please e-mail me at rodsmith@rodsbooks.com. Thanks.

Return to my main web page.