NAME
Sys::Export::GPT - Implementation of GUID Partition Table
SYNOPSIS
use Sys::Export::GPT;
my $gpt= Sys::Export::GPT->new(
partitions => [
{ type => $esp_guid, start_lba => 42, end_lba => 12345 },
{ type => $grub_guid, start_lba => 12346, end_lba => 13579, data => \$grub_core },
],
);
$gpt->write_to_file($fh);DESCRIPTION
This module writes a GUID Partition Table (GPT) into a file handle. It is intended mainly for writing disk images, not installing GPT onto an actual disk, but could be used for that purpose. The defaults of this module deviate a bit from what a normal 'fdisk' would write; the default partition alignment is 4KiB rather than 1MiB, and it sizes the partition table to hold only as many partition entries as you supply rather than reserving space for the standard 128 entries. Beware that the layout of GPT is dependent on the device's reported block size, and that GPT's backup header should be located in the final block of the device which depends on the device size.
When writing to a file, the file size is used if it is larger than the described data, but if the file is too small the file is enlarged to exactly as many blocks as required.
CONSTRUCTORS
new
my $gpt= Sys::Export::GPT->new(%attrs);ATTRIBUTES
block_size
Size of disk blocks reported to BIOS by your drive. The default is 512, which is what almost all removable media will report. Note that if a drive reports 4K to BIOS, the partition tables need to use 4K LBA addresses instead of 512 LBA addresses, which this module will handle for you.
device_size
If set, this must be a multiple of block_size. It can be used to choose defaults for backup_header_lba, backup_table_lba, and last_block. If not set, you need to set values for all those other attributes.
entry_size
Default is 128 bytes, which is standard. You can set it to a larger power of 2 if you want to make room for longer partition text labels, but this is uncommon and BIOS support may vary.
guid
Hex notation GUID; unique identifier for this disk. It will be chosen randomly (and using weak rand() calls unless /dev/random exists) if you don't set it before calling "write_to_file".
partitions
Arrayref of Partition objects. Hashrefs in the array will be coerced to Partition objects. Undefined elements of the array are encoded as unused partition entries. Set the length of the partitions array to determine how many overall entries get written. (GPT normally has 128 entries, but permits fewer)
Partition objects will have their block_size set to match the "block_size" of this object. (If you modify the array afterward, you need to set block_size on them yourself, or write to the "block_size" attribute again)
partition_align
Power of 2 in bytes. When automatically choosing partition locations during "choose_missing_geometry", this aligns the start_lba to a byte boundary.
entry_table_lba
LBA of the partition entries table. This will default to 2.
backup_header_lba
LBA of a backup of the GPT header
backup_table_lba
LBA of a backup of the partition entries table.
first_block
Declares to other partitioning tools the first usable block for allocating a partition. This will default to the first block after the partition entries table.
last_block
Declares to other partitioning tools the last usable block for allocating a partition. This will default to the last block before the backup partition entries table.
choose_missing_geometry
$gpt->choose_missing_geometry($device_size_in_bytes);This calculates default values for the attributes entry_table_lba, backup_header_lba, backup_table_lba, first_block, last_block, and chooses the start_lba of any partition that didn't have one yet (aligned to partition_align).
If the space required by your partitions and GPT structures is larger than $device_size_in_bytes, this will choose block addresses beyond $device_size_in_bytes under the assumption that we are writing a file that can be enlarged. If you are writing to an actual block device of fixed size, you can check whether backup_header_lba is the last block of the device before calling write_to_file.
This makes the assumption that partitions are in ascending order, and does not check for overlaps. It does check if they exceed first_block or last_block.
write_to_file
$gpt->write_to_file($fh);Writes the complete GPT structure to the given filehandle, including:
- Protective MBR (LBA 0, but excluding first 446 bytes of boot loader)
- Primary GPT header (LBA 1)
- Partition entry array (LBA 2+)
- Any partition with defined ->data
- Backup partition entry array (end of disk)
- Backup GPT header (last LBA)VERSION
version 0.005
AUTHOR
Michael Conrad <mike@nrdvana.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Michael Conrad.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.