Welcome to NYCU CSIT Mirror site

Alignment: libfdisk Reference Manual

Alignment

Alignment — functions to align partitions and work with disk topology and geometry

Types and Values

Description

The libfdisk aligns the end of the partitions to make it possible to align the next partition to the "grain" (see fdisk_get_grain_size()). The grain is usually 1MiB (or more for devices where optimal I/O is greater than 1MiB).

It means that the library does not align strictly to physical sector size (or minimal or optimal I/O), but it uses greater granularity. It makes partition tables more portable. If you copy disk layout from 512-sector to 4K-sector device, all partitions are still aligned to physical sectors.

This unified concept also makes partition tables more user friendly, all tables look same, LBA of the first partition is 2048 sectors everywhere, etc.

It's recommended to not change any alignment or device properties. All is initialized by default by fdisk_assign_device().

Note that terminology used by libfdisk is:

  • device properties: I/O limits (topology), geometry, sector size, ...

  • alignment: first, last LBA, grain, ...

The alignment setting may be modified by disk label driver.

Functions

fdisk_align_lba ()

fdisk_sector_t
fdisk_align_lba (struct fdisk_context *cxt,
                 fdisk_sector_t lba,
                 int direction);

This function aligns lba to the "grain" (see fdisk_get_grain_size()). If the device uses alignment offset then the result is moved according the offset to be on the physical boundary.

Parameters

cxt

context

 

lba

address to align

 

direction

FDISK_ALIGN_{UP,DOWN,NEAREST}

 

Returns

alignment LBA.


fdisk_align_lba_in_range ()

fdisk_sector_t
fdisk_align_lba_in_range (struct fdisk_context *cxt,
                          fdisk_sector_t lba,
                          fdisk_sector_t start,
                          fdisk_sector_t stop);

Align lba , the result has to be between start and stop

Parameters

cxt

context

 

lba

LBA

 

start

range start

 

stop

range stop

 

Returns

aligned LBA


fdisk_has_user_device_properties ()

int
fdisk_has_user_device_properties (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

1 if user specified any properties


fdisk_lba_is_phy_aligned ()

int
fdisk_lba_is_phy_aligned (struct fdisk_context *cxt,
                          fdisk_sector_t lba);

Check if the lba is aligned to physical sector boundary.

Parameters

cxt

context

 

lba

LBA to check

 

Returns

1 if aligned.


fdisk_override_geometry ()

int
fdisk_override_geometry (struct fdisk_context *cxt,
                         unsigned int cylinders,
                         unsigned int heads,
                         unsigned int sectors);

Overrides auto-discovery. The function fdisk_reset_device_properties() restores the original setting.

The difference between fdisk_override_geometry() and fdisk_save_user_geometry() is that saved user geometry is persistent setting and it's applied always when device is assigned to the context or device properties are reset.

Parameters

cxt

fdisk context

 

cylinders

user specified cylinders

 

heads

user specified heads

 

sectors

user specified sectors

 

Returns

0 on success, < 0 on error.


fdisk_reset_alignment ()

int
fdisk_reset_alignment (struct fdisk_context *cxt);

Resets alignment setting to the default and label specific values. This function does not change device properties (I/O limits, geometry etc.).

Parameters

cxt

fdisk context

 

Returns

0 on success, < 0 in case of error.


fdisk_reset_device_properties ()

int
fdisk_reset_device_properties (struct fdisk_context *cxt);

Resets and discovery topology (I/O limits), geometry, re-read the first rector on the device if necessary and apply user device setting (geometry and sector size), then initialize alignment according to label driver (see fdisk_reset_alignment()).

You don't have to use this function by default, fdisk_assign_device() is smart enough to initialize all necessary setting.

Parameters

cxt

context

 

Returns

0 on success, <0 on error.


fdisk_save_user_geometry ()

int
fdisk_save_user_geometry (struct fdisk_context *cxt,
                          unsigned int cylinders,
                          unsigned int heads,
                          unsigned int sectors);

Save user defined geometry to use it for partitioning.

The user properties are applied by fdisk_assign_device() or fdisk_reset_device_properties().

Parameters

cxt

context

 

cylinders

C

 

heads

H

 

sectors

S

 

Returns

<0 on error, 0 on success.


fdisk_save_user_grain ()

int
fdisk_save_user_grain (struct fdisk_context *cxt,
                       unsigned long  grain);

Save user define grain size. The size is used to align partitions.

The default is 1MiB (or optimal I/O size if greater than 1MiB). It's strongly recommended to use the default.

The smallest possible granularity for partitioning is physical sector size (or minimal I/O size; the bigger number win). If the user's grain size is too small then the smallest possible granularity is used. It means fdisk_save_user_grain(cxt, 512) forces libfdisk to use grain as small as possible.

The setting is applied by fdisk_assign_device() or fdisk_reset_device_properties().

Parameters

cxt

context

 

grain

size in bytes (>= 512, multiple of 512)

 

Returns

<0 on error, 0 on success.


fdisk_save_user_sector_size ()

int
fdisk_save_user_sector_size (struct fdisk_context *cxt,
                             unsigned int phy,
                             unsigned int log);

Save user defined sector sizes to use it for partitioning.

The user properties are applied by fdisk_assign_device() or fdisk_reset_device_properties().

Parameters

cxt

context

 

phy

physical sector size

 

log

logical sector size

 

Returns

<0 on error, 0 on success.

Types and Values

FDISK_ALIGN_DOWN

#define FDISK_ALIGN_DOWN 2

FDISK_ALIGN_NEAREST

#define FDISK_ALIGN_NEAREST 3

FDISK_ALIGN_UP

#define FDISK_ALIGN_UP		1

fdisk_sector_t

typedef uint64_t fdisk_sector_t;

LBA addresses type