Welcome to NYCU CSIT Mirror site

Label: libfdisk Reference Manual

Label

Label — disk label (PT) specific data and functions

Functions

int fdisk_create_disklabel ()
int fdisk_list_disklabel ()
int fdisk_locate_disklabel ()
int fdisk_reorder_partitions ()
int fdisk_set_disklabel_id ()
int fdisk_set_disklabel_id_from_string ()
int fdisk_set_partition_type ()
int fdisk_toggle_partition_flag ()
int fdisk_verify_disklabel ()
int fdisk_write_disklabel ()
int fdisk_get_disklabel_id ()
struct fdisk_label * fdisk_get_label ()
size_t fdisk_get_nlabels ()
int fdisk_next_label ()
size_t fdisk_get_npartitions ()
#define fdisk_is_label()
struct fdisk_parttype * fdisk_label_advparse_parttype ()
const struct fdisk_field * fdisk_label_get_field ()
const struct fdisk_field * fdisk_label_get_field_by_name ()
int fdisk_label_get_fields_ids ()
int fdisk_label_get_fields_ids_all ()
int fdisk_label_get_geomrange_cylinders ()
int fdisk_label_get_geomrange_heads ()
int fdisk_label_get_geomrange_sectors ()
const char * fdisk_label_get_name ()
size_t fdisk_label_get_nparttypes ()
struct fdisk_parttype * fdisk_label_get_parttype ()
struct fdisk_parttype * fdisk_label_get_parttype_from_code ()
struct fdisk_parttype * fdisk_label_get_parttype_from_string ()
int fdisk_label_get_parttype_shortcut ()
int fdisk_label_get_type ()
int fdisk_label_has_code_parttypes ()
int fdisk_label_has_parttypes_shortcuts ()
int fdisk_label_is_changed ()
int fdisk_label_is_disabled ()
struct fdisk_parttype * fdisk_label_parse_parttype ()
int fdisk_label_require_geometry ()
void fdisk_label_set_changed ()
void fdisk_label_set_disabled ()

Types and Values

Description

The fdisk_new_context() initializes all label drivers, and allocate per-label specific data struct. This concept can be used to store label specific settings to the label driver independently on the currently active label driver. Note that label struct cannot be deallocated, so there is no reference counting for fdisk_label objects. All is destroyed by fdisk_unref_context() only.

Anyway, all label drives share in-memory first sector. The function fdisk_create_disklabel() overwrites this in-memory sector. But it's possible that label driver also uses another buffers, for example GPT reads more sectors from the device.

All label operations are in-memory only, except fdisk_write_disklabel().

All functions that use "struct fdisk_context" rather than "struct fdisk_label" use the currently active label driver.

Functions

fdisk_create_disklabel ()

int
fdisk_create_disklabel (struct fdisk_context *cxt,
                        const char *name);

Creates a new disk label of type name . If name is NULL, then it will create a default system label type, either SUN or DOS. The function automatically switches the current label driver to name . The function fdisk_get_label() returns the current label driver.

The function modifies in-memory data only.

Parameters

cxt

fdisk context

 

name

label name

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_list_disklabel ()

int
fdisk_list_disklabel (struct fdisk_context *cxt);

Lists details about disklabel, but no partitions.

This function is based on fdisk_get_disklabel_item() and prints all label specific information by ASK interface (FDISK_ASKTYPE_INFO, aka fdisk_info()). The function requires enabled "details" by fdisk_enable_details().

It's recommended to use fdisk_get_disklabel_item() if you need better control on output and formatting.

Parameters

cxt

fdisk context

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_locate_disklabel ()

int
fdisk_locate_disklabel (struct fdisk_context *cxt,
                        int n,
                        const char **name,
                        uint64_t *offset,
                        size_t *size);

Locate disklabel and returns info about n item of the label.

For example GPT is composed from three items, PMBR and GPT, n=0 return offset to PMBR and n=1 return offset to GPT Header and n=2 returns offset to GPT array of partitions, n=3 and n=4 returns location of the backup GPT label at the end of the disk.

The function returns the current in-memory situation. It's possible that a header location is modified by write operation, for example when enabled minimization (see fdisk_gpt_enable_minimize()). In this case it's better to call this function after fdisk_write_disklabel().

For more details see 'D' expert fdisk command.

Parameters

cxt

context

 

n

N item

 

name

return item name

 

offset

return offset where is item

 

size

of the item

 

Returns

0 on success, <0 on error, 1 no more items.


fdisk_reorder_partitions ()

int
fdisk_reorder_partitions (struct fdisk_context *cxt);

Sort partitions according to the partition start sector.

Parameters

cxt

fdisk context

 

Returns

0 on success, 1 reorder unnecessary, otherwise a corresponding error.


fdisk_set_disklabel_id ()

int
fdisk_set_disklabel_id (struct fdisk_context *cxt);

Parameters

cxt

fdisk context

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_set_disklabel_id_from_string ()

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

Parameters

cxt

fdisk context

 

str

new Id

 

Returns

0 on success, otherwise, a corresponding error.

Since: 2.36


fdisk_set_partition_type ()

int
fdisk_set_partition_type (struct fdisk_context *cxt,
                          size_t partnum,
                          struct fdisk_parttype *t);

Parameters

cxt

fdisk context

 

partnum

partition number

 

t

new type

 

Returns

0 on success, < 0 on error.


fdisk_toggle_partition_flag ()

int
fdisk_toggle_partition_flag (struct fdisk_context *cxt,
                             size_t partnum,
                             unsigned long  flag);

Parameters

cxt

fdisk context

 

partnum

partition number

 

flag

flag ID

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_verify_disklabel ()

int
fdisk_verify_disklabel (struct fdisk_context *cxt);

Verifies the partition table.

Parameters

cxt

fdisk context

 

Returns

0 on success, <1 runtime or option errors, >0 number of detected issues


fdisk_write_disklabel ()

int
fdisk_write_disklabel (struct fdisk_context *cxt);

This function wipes the device (if enabled by fdisk_enable_wipe()) and then it writes in-memory changes to disk. Be careful!

Parameters

cxt

fdisk context

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_get_disklabel_id ()

int
fdisk_get_disklabel_id (struct fdisk_context *cxt,
                        char **id);

Parameters

cxt

fdisk context

 

id

returns pointer to allocated string (MBR Id or GPT dirk UUID)

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_get_label ()

struct fdisk_label *
fdisk_get_label (struct fdisk_context *cxt,
                 const char *name);

If no name specified then returns the current context label.

The label is allocated and maintained within the context cxt. There is nothing like reference counting for labels, you cannot deallocate the label.

Parameters

cxt

context instance

 

name

label name (e.g. "gpt")

 

Returns

label struct or NULL in case of error.


fdisk_get_nlabels ()

size_t
fdisk_get_nlabels (struct fdisk_context *cxt);

Parameters

cxt

context

 

Returns

number of supported label types


fdisk_next_label ()

int
fdisk_next_label (struct fdisk_context *cxt,
                  struct fdisk_label **lb);
1
2
3
4
5
6
7
// print all supported labels
struct fdisk_context *cxt = fdisk_new_context();
struct fdisk_label *lb = NULL;

while (fdisk_next_label(cxt, &lb) == 0)
	print("label name: %s\n", fdisk_label_get_name(lb));
fdisk_unref_context(cxt);

Parameters

cxt

context instance

 

lb

returns pointer to the next label

 

Returns

<0 in case of error, 0 on success, 1 at the end.


fdisk_get_npartitions ()

size_t
fdisk_get_npartitions (struct fdisk_context *cxt);

The maximal number of the partitions depends on disklabel and does not have to describe the real limit of PT.

For example the limit for MBR without extend partition is 4, with extended partition it's unlimited (so the function returns the current number of all partitions in this case).

And for example for GPT it depends on space allocated on disk for array of entry records (usually 128).

It's fine to use fdisk_get_npartitions() in loops, but don't forget that partition may be unused (see fdisk_is_partition_used()).

1
2
3
4
5
6
7
8
struct fdisk_partition *pa = NULL;
size_t i, nmax = fdisk_get_npartitions(cxt);

for (i = 0; i < nmax; i++) {
	if (!fdisk_is_partition_used(cxt, i))
		continue;
	... do something ...
}

Note that the recommended way to list partitions is to use fdisk_get_partitions() and struct fdisk_table then ask disk driver for each individual partitions.

Parameters

cxt

context

 

Returns

maximal number of partitions for the current label.


fdisk_is_label()

#define fdisk_is_label(c, x) fdisk_is_labeltype(c, FDISK_DISKLABEL_ ## x)

fdisk_label_advparse_parttype ()

struct fdisk_parttype *
fdisk_label_advparse_parttype (const struct fdisk_label *lb,
                               const char *str,
                               int flags);

This function is advanced partition types parser. It parses partition type from str according to the label. The function returns a pointer to static table of the partition types, or newly allocated partition type for unknown types (see fdisk_parttype_is_unknown(). It's safe to call fdisk_unref_parttype() for all results.

The str may be type data (hex code or UUID), alias or shortcut. For GPT also sequence number of the type in the list of the supported types.

Parameters

lb

label

 

str

string to parse from

 

flags

FDISK_PARTTYPE_PARSE_*

 

Returns

pointer to type or NULL on error.


fdisk_label_get_field ()

const struct fdisk_field *
fdisk_label_get_field (const struct fdisk_label *lb,
                       int id);

The field struct describes data stored in struct fdisk_partition. The info about data is usable for example to generate human readable output (e.g. fdisk 'p'rint command). See fdisk_partition_to_string() and fdisk code.

Parameters

lb

label

 

id

FDISK_FIELD_*

 

Returns

pointer to static instance of the field.


fdisk_label_get_field_by_name ()

const struct fdisk_field *
fdisk_label_get_field_by_name (const struct fdisk_label *lb,
                               const char *name);

Parameters

lb

label

 

name

field name

 

Returns

pointer to static instance of the field.


fdisk_label_get_fields_ids ()

int
fdisk_label_get_fields_ids (const struct fdisk_label *lb,
                            struct fdisk_context *cxt,
                            int **ids,
                            size_t *nids);

This function returns the default fields for the label.

Note that the set of the default fields depends on fdisk_enable_details() function. If the details are enabled then this function usually returns more fields.

Parameters

lb

label (or NULL for the current label)

 

cxt

context

 

ids

returns allocated array with FDISK_FIELD_* IDs

 

nids

returns number of items in fields

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_label_get_fields_ids_all ()

int
fdisk_label_get_fields_ids_all (const struct fdisk_label *lb,
                                struct fdisk_context *cxt,
                                int **ids,
                                size_t *nids);

This function returns all fields for the label.

Parameters

lb

label (or NULL for the current label)

 

cxt

context

 

ids

returns allocated array with FDISK_FIELD_* IDs

 

nids

returns number of items in fields

 

Returns

0 on success, otherwise, a corresponding error.


fdisk_label_get_geomrange_cylinders ()

int
fdisk_label_get_geomrange_cylinders (const struct fdisk_label *lb,
                                     fdisk_sector_t *mi,
                                     fdisk_sector_t *ma);

The function provides minimal and maximal geometry supported for the label, if no range defined by library then returns -ENOSYS.

Parameters

lb

label

 

mi

minimal number

 

ma

maximal number

 

Returns

0 on success, otherwise, a corresponding error.

Since: 2.32


fdisk_label_get_geomrange_heads ()

int
fdisk_label_get_geomrange_heads (const struct fdisk_label *lb,
                                 unsigned int *mi,
                                 unsigned int *ma);

The function provides minimal and maximal geometry supported for the label, if no range defined by library then returns -ENOSYS.

Parameters

lb

label

 

mi

minimal number

 

ma

maximal number

 

Returns

0 on success, otherwise, a corresponding error.

Since: 2.32


fdisk_label_get_geomrange_sectors ()

int
fdisk_label_get_geomrange_sectors (const struct fdisk_label *lb,
                                   fdisk_sector_t *mi,
                                   fdisk_sector_t *ma);

The function provides minimal and maximal geometry supported for the label, if no range defined by library then returns -ENOSYS.

Parameters

lb

label

 

mi

minimal number

 

ma

maximal number

 

Returns

0 on success, otherwise, a corresponding error.

Since: 2.32


fdisk_label_get_name ()

const char *
fdisk_label_get_name (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

label name


fdisk_label_get_nparttypes ()

size_t
fdisk_label_get_nparttypes (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

number of types supported by label.


fdisk_label_get_parttype ()

struct fdisk_parttype *
fdisk_label_get_parttype (const struct fdisk_label *lb,
                          size_t n);

Parameters

lb

label

 

n

number

 

Returns

return parttype


fdisk_label_get_parttype_from_code ()

struct fdisk_parttype *
fdisk_label_get_parttype_from_code (const struct fdisk_label *lb,
                                    unsigned int code);

Search for partition type in label-specific table. The result is pointer to static array of label types.

Parameters

lb

label

 

code

code to search for

 

Returns

partition type or NULL upon failure or invalid code .


fdisk_label_get_parttype_from_string ()

struct fdisk_parttype *
fdisk_label_get_parttype_from_string (const struct fdisk_label *lb,
                                      const char *str);

Search for partition type in label-specific table. The result is pointer to static array of label types.

Parameters

lb

label

 

str

string to search for

 

Returns

partition type or NULL upon failure or invalid str .


fdisk_label_get_parttype_shortcut ()

int
fdisk_label_get_parttype_shortcut (const struct fdisk_label *lb,
                                   size_t n,
                                   const char **typestr,
                                   const char **shortcut,
                                   const char **alias);

Parameters

lb

label

 

n

number

 

typestr

returns type as string

 

shortcut

returns type shortcut string

 

alias

returns type alias string

 

Returns

return 0 on success, <0 on error, 2 for deprecated alias, 1 for n out of range

Since: 2.36


fdisk_label_get_type ()

int
fdisk_label_get_type (const struct fdisk_label *lb);

fdisk_label_has_code_parttypes ()

int
fdisk_label_has_code_parttypes (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

1 if the label uses code as partition type identifiers (e.g. MBR) or 0.


fdisk_label_has_parttypes_shortcuts ()

int
fdisk_label_has_parttypes_shortcuts (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

1 if the label support shortuts/aliases for partition types or 0.

Since: 2.36


fdisk_label_is_changed ()

int
fdisk_label_is_changed (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

1 if in-memory data has been changed.


fdisk_label_is_disabled ()

int
fdisk_label_is_disabled (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

1 if label driver disabled.


fdisk_label_parse_parttype ()

struct fdisk_parttype *
fdisk_label_parse_parttype (const struct fdisk_label *lb,
                            const char *str);

Parses partition type from str according to the label. The function returns a pointer to static table of the partition types, or newly allocated partition type for unknown types (see fdisk_parttype_is_unknown(). It's safe to call fdisk_unref_parttype() for all results.

Note that for GPT it accepts sequence number of UUID.

Parameters

lb

label

 

str

string to parse from (type name, UUID, etc.)

 

Returns

pointer to type or NULL on error.


fdisk_label_require_geometry ()

int
fdisk_label_require_geometry (const struct fdisk_label *lb);

Parameters

lb

label

 

Returns

1 if label requires CHS geometry


fdisk_label_set_changed ()

void
fdisk_label_set_changed (struct fdisk_label *lb,
                         int changed);

Marks in-memory data as changed, to force fdisk_write_disklabel() to write to device. This should be unnecessary by default, the library keeps track about changes.

Parameters

lb

label

 

changed

0/1

 

fdisk_label_set_disabled ()

void
fdisk_label_set_disabled (struct fdisk_label *lb,
                          int disabled);

Mark label as disabled, then libfdisk is going to ignore the label when probe device for labels.

Parameters

lb

label

 

disabled

0 or 1

 

Types and Values

struct fdisk_label

struct fdisk_label;

Disk label specific driver and setting.


enum fdisk_labeltype

Supported partition table types (labels)

Members

FDISK_DISKLABEL_DOS

MBR label type

 

FDISK_DISKLABEL_SUN

SUN label type

 

FDISK_DISKLABEL_SGI

SGI label type

 

FDISK_DISKLABEL_BSD

BSD label type

 

FDISK_DISKLABEL_GPT

UEFI GPT type