Welcome to NYCU CSIT Mirror site

Context: libfdisk Reference Manual

Context

Context — stores info about device, labels etc.

Functions

int fdisk_assign_device ()
int fdisk_assign_device_by_fd ()
int fdisk_deassign_device ()
int fdisk_reassign_device ()
int fdisk_device_is_used ()
int fdisk_enable_bootbits_protection ()
int fdisk_enable_details ()
int fdisk_enable_listonly ()
int fdisk_enable_wipe ()
int fdisk_disable_dialogs ()
unsigned long fdisk_get_alignment_offset ()
const char * fdisk_get_collision ()
int fdisk_get_devfd ()
const char * fdisk_get_devmodel ()
const char * fdisk_get_devname ()
dev_t fdisk_get_devno ()
int fdisk_get_disklabel_item ()
fdisk_sector_t fdisk_get_first_lba ()
fdisk_sector_t fdisk_get_geom_cylinders ()
unsigned int fdisk_get_geom_heads ()
fdisk_sector_t fdisk_get_geom_sectors ()
unsigned long fdisk_get_grain_size ()
fdisk_sector_t fdisk_get_last_lba ()
unsigned long fdisk_get_minimal_iosize ()
fdisk_sector_t fdisk_get_nsectors ()
unsigned long fdisk_get_optimal_iosize ()
struct fdisk_context * fdisk_get_parent ()
unsigned long fdisk_get_physector_size ()
unsigned long fdisk_get_sector_size ()
int fdisk_get_size_unit ()
const char * fdisk_get_unit ()
unsigned int fdisk_get_units_per_sector ()
int fdisk_has_dialogs ()
int fdisk_has_label ()
int fdisk_has_protected_bootbits ()
int fdisk_has_wipe ()
int fdisk_is_details ()
int fdisk_is_labeltype ()
int fdisk_is_listonly ()
int fdisk_is_ptcollision ()
int fdisk_is_readonly ()
int fdisk_is_regfile ()
struct fdisk_context * fdisk_new_context ()
struct fdisk_context * fdisk_new_nested_context ()
void fdisk_ref_context ()
int fdisk_reread_changes ()
int fdisk_reread_partition_table ()
fdisk_sector_t fdisk_set_first_lba ()
fdisk_sector_t fdisk_set_last_lba ()
int fdisk_set_size_unit ()
int fdisk_set_unit ()
void fdisk_unref_context ()
int fdisk_use_cylinders ()

Types and Values

struct fdisk_context
#define FDISK_PLURAL
#define FDISK_SINGULAR

Description

The library distinguish between three types of partitioning objects.

on-disk label data

  • disk label specific

  • probed and read by disklabel drivers when assign device to the context or when switch to another disk label type

  • only fdisk_write_disklabel() modify on-disk data

in-memory label data

  • generic data and disklabel specific data stored in struct fdisk_label

  • all partitioning operations are based on in-memory data only

struct fdisk_partition

  • provides abstraction to present partitions to users

  • fdisk_partition is possible to gather to fdisk_table container

  • used as unified template for new partitions

  • used (with fdisk_table) in fdisk scripts

  • the struct fdisk_partition is always completely independent object and any change to the object has no effect to in-memory (or on-disk) label data

Don't forget to inform kernel about changes by fdisk_reread_partition_table() or more smart fdisk_reread_changes().

Functions

fdisk_assign_device ()

int
fdisk_assign_device (struct fdisk_context *cxt,
                     const char *fname,
                     int readonly);

Open the device, discovery topology, geometry, detect disklabel, check for collisions and switch the current label driver to reflect the probing result.

If in standard mode (!= non-listonly mode) then also detects for collisions. The result is accessible by fdisk_get_collision() and fdisk_is_ptcollision(). The collision (e.g. old obsolete PT) may be removed by fdisk_enable_wipe(). Note that new PT and old PT may be on different locations.

Note that this function resets all generic setting in context.

If the cxt is nested context (necessary for example to edit BSD or PMBR) then the device is assigned to the parental context and necessary properties are copied to the cxt . The change is propagated in child->parent direction only. It's impossible to use a different device for primary and nested contexts.

Parameters

cxt

context

 

fname

path to the device to be handled

 

readonly

how to open the device

 

Returns

0 on success, < 0 on error.


fdisk_assign_device_by_fd ()

int
fdisk_assign_device_by_fd (struct fdisk_context *cxt,
                           int fd,
                           const char *fname,
                           int readonly);

Like fdisk_assign_device(), but caller is responsible to open and close the device. The library only fsync() the device on fdisk_deassign_device().

The device has to be open O_RDWR on readonly =0.

Parameters

cxt

context

 

fd

device file descriptor

 

fname

path to the device (used for dialogs, debugging, partition names, ...)

 

readonly

how to use the device

 

Returns

0 on success, < 0 on error.

Since: 2.35


fdisk_deassign_device ()

int
fdisk_deassign_device (struct fdisk_context *cxt,
                       int nosync);

Call fsync(), close() and than sync(), but for read-only handler close the device only. If the cxt is nested context then the request is redirected to the parent.

Parameters

cxt

context

 

nosync

disable sync() after close().

 

Returns

0 on success, < 0 on error.


fdisk_reassign_device ()

int
fdisk_reassign_device (struct fdisk_context *cxt);

This function is "hard reset" of the context and it does not write anything to the device. All in-memory changes associated with the context will be lost. It's recommended to use this function after some fatal problem when the context (and label specific driver) is in an undefined state.

Parameters

cxt

context

 

Returns

0 on success, < 0 on error.


fdisk_device_is_used ()

int
fdisk_device_is_used (struct fdisk_context *cxt);

The function returns always 0 if the device has not been opened by fdisk_assign_device() or if open read-only.

Parameters

cxt

context

 

Returns

1 if the device assigned to the context is used by system, or 0.


fdisk_enable_bootbits_protection ()

int
fdisk_enable_bootbits_protection (struct fdisk_context *cxt,
                                  int enable);

The library zeroizes all the first sector when create a new disk label by default. This function can be used to control this behavior. For now it's supported for MBR and GPT.

Parameters

cxt

fdisk context

 

enable

1 or 0

 

Returns

0 on success, < 0 on error.


fdisk_enable_details ()

int
fdisk_enable_details (struct fdisk_context *cxt,
                      int enable);

Enables or disables "details" display mode. This function has effect to fdisk_partition_to_string() function.

Parameters

cxt

context

 

enable

true/false

 

Returns

0 on success, < 0 on error.


fdisk_enable_listonly ()

int
fdisk_enable_listonly (struct fdisk_context *cxt,
                       int enable);

Just list partition only, don't care about another details, mistakes, ...

Parameters

cxt

context

 

enable

true/false

 

Returns

0 on success, < 0 on error.


fdisk_enable_wipe ()

int
fdisk_enable_wipe (struct fdisk_context *cxt,
                   int enable);

The library removes all PT/filesystem/RAID signatures before it writes partition table. The probing area where it looks for signatures is from the begin of the disk. The device is wiped by libblkid.

See also fdisk_wipe_partition().

Parameters

cxt

fdisk context

 

enable

1 or 0

 

Returns

0 on success, < 0 on error.


fdisk_disable_dialogs ()

int
fdisk_disable_dialogs (struct fdisk_context *cxt,
                       int disable);

The library uses dialog driven partitioning by default.

Parameters

cxt

fdisk context

 

disable

1 or 0

 

Returns

0 on success, < 0 on error.

Since: 2.31


fdisk_get_alignment_offset ()

unsigned long
fdisk_get_alignment_offset (struct fdisk_context *cxt);

The alignment offset is offset between logical and physical sectors. For backward compatibility the first logical sector on 4K disks does no have to start on the same place like physical sectors.

Parameters

cxt

context

 

Returns

alignment offset in bytes


fdisk_get_collision ()

const char *
fdisk_get_collision (struct fdisk_context *cxt);

Parameters

cxt

fdisk context

 

Returns

name of the filesystem or RAID detected on the device or NULL.


fdisk_get_devfd ()

int
fdisk_get_devfd (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

device file descriptor.


fdisk_get_devmodel ()

const char *
fdisk_get_devmodel (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

device model string or NULL.

Since: 2.33


fdisk_get_devname ()

const char *
fdisk_get_devname (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

device name.


fdisk_get_devno ()

dev_t
fdisk_get_devno (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

device number or zero for non-block devices

Since: 2.33


fdisk_get_disklabel_item ()

int
fdisk_get_disklabel_item (struct fdisk_context *cxt,
                          int id,
                          struct fdisk_labelitem *item);

Note that id is always in range 0..N. It's fine to use the function in loop until it returns error or 2, the result in item should be ignored when function returns 1. Don't forget to use fdisk_reset_labelitem() or fdisk_unref_labelitem().

Parameters

cxt

fdisk context

 

id

item ID (FDISK_LABELITEM_* or *_LABELITEM_*)

 

item

specifies and returns the item

 

Returns

0 on success, < 0 on error, 1 on unsupported item, 2 id out of range


fdisk_get_first_lba ()

fdisk_sector_t
fdisk_get_first_lba (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

first possible LBA on disk for data partitions.


fdisk_get_geom_cylinders ()

fdisk_sector_t
fdisk_get_geom_cylinders (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

number of geometry cylinders


fdisk_get_geom_heads ()

unsigned int
fdisk_get_geom_heads (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

number of geometry heads.


fdisk_get_geom_sectors ()

fdisk_sector_t
fdisk_get_geom_sectors (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

number of geometry sectors.


fdisk_get_grain_size ()

unsigned long
fdisk_get_grain_size (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

grain in bytes used to align partitions (usually 1MiB)


fdisk_get_last_lba ()

fdisk_sector_t
fdisk_get_last_lba (struct fdisk_context *cxt);

Note that the device has to be already assigned.

Parameters

cxt

fdisk context

 

Returns

last possible LBA on device


fdisk_get_minimal_iosize ()

unsigned long
fdisk_get_minimal_iosize (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

minimal I/O size in bytes


fdisk_get_nsectors ()

fdisk_sector_t
fdisk_get_nsectors (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

size of the device in logical sectors.


fdisk_get_optimal_iosize ()

unsigned long
fdisk_get_optimal_iosize (struct fdisk_context *cxt);

The optimal I/O is optional and does not have to be provided by device, anyway libfdisk never returns zero. If the optimal I/O size is not provided then libfdisk returns minimal I/O size or sector size.

Parameters

cxt

context

 

Returns

optimal I/O size in bytes.


fdisk_get_parent ()

struct fdisk_context *
fdisk_get_parent (struct fdisk_context *cxt);

Parameters

cxt

nested fdisk context

 

Returns

pointer to parental context, or NULL


fdisk_get_physector_size ()

unsigned long
fdisk_get_physector_size (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

physical sector size in bytes


fdisk_get_sector_size ()

unsigned long
fdisk_get_sector_size (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

logical sector size in bytes


fdisk_get_size_unit ()

int
fdisk_get_size_unit (struct fdisk_context *cxt);

Gets unit for SIZE output field (see fdisk_partition_to_string()).

Parameters

cxt

fdisk context

 

Returns

unit


fdisk_get_unit ()

const char *
fdisk_get_unit (struct fdisk_context *cxt,
                int n);

Parameters

cxt

context

 

n

FDISK_PLURAL or FDISK_SINGULAR

 

Returns

unit name.


fdisk_get_units_per_sector ()

unsigned int
fdisk_get_units_per_sector (struct fdisk_context *cxt);

This is necessary only for brain dead situations when we use "cylinders";

Parameters

cxt

context

 

Returns

number of "units" per sector, default is 1 if display unit is sector.


fdisk_has_dialogs ()

int
fdisk_has_dialogs (struct fdisk_context *cxt);

See fdisk_disable_dialogs()

Parameters

cxt

fdisk context

 

Returns

1 if dialog driven partitioning enabled (default), or 0.

Since: 2.31


fdisk_has_label ()

int
fdisk_has_label (struct fdisk_context *cxt);

Parameters

cxt

fdisk context

 

Returns

return 1 if there is label on the device.


fdisk_has_protected_bootbits ()

int
fdisk_has_protected_bootbits (struct fdisk_context *cxt);

Parameters

cxt

fdisk context

 

Returns

return 1 if boot bits protection enabled.


fdisk_has_wipe ()

int
fdisk_has_wipe (struct fdisk_context *cxt);

Returns the current wipe setting. See fdisk_enable_wipe().

Parameters

cxt

fdisk context

 

Returns

0 on success, < 0 on error.


fdisk_is_details ()

int
fdisk_is_details (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

1 if details are enabled


fdisk_is_labeltype ()

int
fdisk_is_labeltype (struct fdisk_context *cxt,
                    enum fdisk_labeltype id);

See also fdisk_is_label() macro in libfdisk.h.

Parameters

cxt

fdisk context

 

id

FDISK_DISKLABEL_*

 

Returns

return 1 if the current label is id


fdisk_is_listonly ()

int
fdisk_is_listonly (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

1 if list-only mode enabled


fdisk_is_ptcollision ()

int
fdisk_is_ptcollision (struct fdisk_context *cxt);

The collision detected by libblkid (usually another partition table). Note that libfdisk does not support all partitions tables, so fdisk_has_label() may return false, but fdisk_is_ptcollision() may return true.

Parameters

cxt

fdisk context

 

Returns

0 or 1

Since: 2.30


fdisk_is_readonly ()

int
fdisk_is_readonly (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

1 if device open readonly


fdisk_is_regfile ()

int
fdisk_is_regfile (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

1 if open file descriptor is regular file rather than a block device.

Since: 2.30


fdisk_new_context ()

struct fdisk_context *
fdisk_new_context (void);

Returns

newly allocated libfdisk handler


fdisk_new_nested_context ()

struct fdisk_context *
fdisk_new_nested_context (struct fdisk_context *parent,
                          const char *name);

Create a new nested fdisk context for nested disk labels (e.g. BSD or PMBR). The function also probes for the nested label on the device if device is already assigned to parent.

The new context is initialized according to parent and both context shares some settings and file descriptor to the device. The child propagate some changes (like fdisk_assign_device()) to parent, but it does not work vice-versa. The behavior is undefined if you assign another device to parent.

Parameters

parent

parental context

 

name

optional label name (e.g. "bsd")

 

Returns

new context for nested partition table.


fdisk_ref_context ()

void
fdisk_ref_context (struct fdisk_context *cxt);

Increments reference counter.

Parameters

cxt

context pointer

 

fdisk_reread_changes ()

int
fdisk_reread_changes (struct fdisk_context *cxt,
                      struct fdisk_table *org);

Like fdisk_reread_partition_table() but don't forces kernel re-read all partition table. The BLKPG_* ioctls are used for individual partitions. The advantage is that unmodified partitions maybe mounted.

The function behaves like fdisk_reread_partition_table() on systems where are no available BLKPG_* ioctls.

Parameters

cxt

context

 

org

original layout (on disk)

 

Returns

<0 on error, or 0.


fdisk_reread_partition_table ()

int
fdisk_reread_partition_table (struct fdisk_context *cxt);

Force *kernel* to re-read partition table on block devices.

Parameters

cxt

context

 

Returns

0 on success, < 0 in case of error.


fdisk_set_first_lba ()

fdisk_sector_t
fdisk_set_first_lba (struct fdisk_context *cxt,
                     fdisk_sector_t lba);

It's strongly recommended to use the default library setting. The first LBA is always reset by fdisk_assign_device(), fdisk_override_geometry() and fdisk_reset_alignment(). This is very low level function and library does not check if your setting makes any sense.

This function is necessary only when you want to work with very unusual partition tables like GPT protective MBR or hybrid partition tables on bootable media where the first partition may start on very crazy offsets.

Note that this function changes only runtime information. It does not update any range in on-disk partition table. For example GPT Header contains First and Last usable LBA fields. These fields are not updated by this function. Be careful.

Parameters

cxt

fdisk context

 

lba

first possible logical sector for data

 

Returns

0 on success, <0 on error.


fdisk_set_last_lba ()

fdisk_sector_t
fdisk_set_last_lba (struct fdisk_context *cxt,
                    fdisk_sector_t lba);

It's strongly recommended to use the default library setting. The last LBA is always reset by fdisk_assign_device(), fdisk_override_geometry() and fdisk_reset_alignment().

The default is number of sectors on the device, but maybe modified by the current disklabel driver (for example GPT uses the end of disk for backup header, so last_lba is smaller than total number of sectors).

Parameters

cxt

fdisk context

 

lba

last possible logical sector

 

Returns

0 on success, <0 on error.


fdisk_set_size_unit ()

int
fdisk_set_size_unit (struct fdisk_context *cxt,
                     int unit);

Sets unit for SIZE output field (see fdisk_partition_to_string()).

Parameters

cxt

fdisk context

 

unit

FDISK_SIZEUNIT_*

 

Returns

0 on success, <0 on error.


fdisk_set_unit ()

int
fdisk_set_unit (struct fdisk_context *cxt,
                const char *str);

This is pure shit, unfortunately for example Sun addresses begin of the partition by cylinders...

Parameters

cxt

context

 

str

"cylinder" or "sector".

 

Returns

0 on success, <0 on error.


fdisk_unref_context ()

void
fdisk_unref_context (struct fdisk_context *cxt);

Deallocates context struct.

Parameters

cxt

fdisk context

 

fdisk_use_cylinders ()

int
fdisk_use_cylinders (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

1 if user wants to display in cylinders.

Types and Values

struct fdisk_context

struct fdisk_context;

Basic library handler.


FDISK_PLURAL

#define FDISK_PLURAL 0

FDISK_SINGULAR

#define FDISK_SINGULAR 1