LVM: libblockdev Reference Manual

LVM

LVM — plugin for operations with LVM

Functions

#define	BD_LVM_MAX_LV_SIZE
#define	BD_LVM_DEFAULT_PE_SIZE
#define	BD_LVM_DEFAULT_PE_START
#define	BD_LVM_MIN_PE_SIZE
#define	BD_LVM_MAX_PE_SIZE
#define	RESOLVE_PE_SIZE()
#define	BD_LVM_MIN_THPOOL_MD_SIZE
#define	BD_LVM_MAX_THPOOL_MD_SIZE
#define	BD_LVM_MIN_THPOOL_CHUNK_SIZE
#define	BD_LVM_MAX_THPOOL_CHUNK_SIZE
#define	THPOOL_MD_FACTOR_NEW
#define	THPOOL_MD_FACTOR_EXISTS
GQuark	bd_lvm_error_quark ()
void	bd_lvm_pvdata_free ()
BDLVMPVdata *	bd_lvm_pvdata_copy ()
void	bd_lvm_vgdata_free ()
BDLVMVGdata *	bd_lvm_vgdata_copy ()
void	bd_lvm_lvdata_free ()
BDLVMLVdata *	bd_lvm_lvdata_copy ()
gboolean	bd_lvm_is_supported_pe_size ()
guint64 *	bd_lvm_get_supported_pe_sizes ()
guint64	bd_lvm_get_max_lv_size ()
guint64	bd_lvm_round_size_to_pe ()
guint64	bd_lvm_get_lv_physical_size ()
guint64	bd_lvm_get_thpool_padding ()
gboolean	bd_lvm_is_valid_thpool_md_size ()
gboolean	bd_lvm_is_valid_thpool_chunk_size ()
gboolean	bd_lvm_pvcreate ()
gboolean	bd_lvm_pvresize ()
gboolean	bd_lvm_pvremove ()
gboolean	bd_lvm_pvmove ()
gboolean	bd_lvm_pvscan ()
BDLVMPVdata *	bd_lvm_pvinfo ()
BDLVMPVdata **	bd_lvm_pvs ()
gboolean	bd_lvm_vgcreate ()
gboolean	bd_lvm_vgremove ()
gboolean	bd_lvm_vgactivate ()
gboolean	bd_lvm_vgdeactivate ()
gboolean	bd_lvm_vgextend ()
gboolean	bd_lvm_vgreduce ()
BDLVMVGdata *	bd_lvm_vginfo ()
BDLVMVGdata **	bd_lvm_vgs ()
gchar *	bd_lvm_lvorigin ()
gboolean	bd_lvm_lvcreate ()
gboolean	bd_lvm_lvremove ()
gboolean	bd_lvm_lvresize ()
gboolean	bd_lvm_lvactivate ()
gboolean	bd_lvm_lvdeactivate ()
gboolean	bd_lvm_lvsnapshotcreate ()
gboolean	bd_lvm_lvsnapshotmerge ()
BDLVMLVdata *	bd_lvm_lvinfo ()
BDLVMLVdata **	bd_lvm_lvs ()
gboolean	bd_lvm_thpoolcreate ()
gboolean	bd_lvm_thlvcreate ()
gchar *	bd_lvm_thlvpoolname ()
gboolean	bd_lvm_thsnapshotcreate ()
gboolean	bd_lvm_set_global_config ()
gchar *	bd_lvm_get_global_config ()

Types and Values

#define	USE_DEFAULT_PE_SIZE
#define	BD_LVM_ERROR
enum	BDLVMError
	BDLVMPVdata
	BDLVMVGdata
	BDLVMLVdata

Includes

#include <lvm.h>

Description

A plugin for operations with LVM. All sizes passed in/out to/from the functions are in bytes.

Functions

BD_LVM_MAX_LV_SIZE

#define BD_LVM_MAX_LV_SIZE (8 EiB)

BD_LVM_DEFAULT_PE_SIZE

#define BD_LVM_DEFAULT_PE_SIZE (4 MiB)

BD_LVM_DEFAULT_PE_START

#define BD_LVM_DEFAULT_PE_START (1 MiB)

BD_LVM_MIN_PE_SIZE

#define BD_LVM_MIN_PE_SIZE (1 KiB)

BD_LVM_MAX_PE_SIZE

#define BD_LVM_MAX_PE_SIZE (16 GiB)

RESOLVE_PE_SIZE()

#define RESOLVE_PE_SIZE(size) ((size) == USE_DEFAULT_PE_SIZE ? BD_LVM_DEFAULT_PE_SIZE : (size))

BD_LVM_MIN_THPOOL_MD_SIZE

#define BD_LVM_MIN_THPOOL_MD_SIZE (2 MiB)

BD_LVM_MAX_THPOOL_MD_SIZE

#define BD_LVM_MAX_THPOOL_MD_SIZE (16 GiB)

BD_LVM_MIN_THPOOL_CHUNK_SIZE

#define BD_LVM_MIN_THPOOL_CHUNK_SIZE (64 KiB)

BD_LVM_MAX_THPOOL_CHUNK_SIZE

#define BD_LVM_MAX_THPOOL_CHUNK_SIZE (1 GiB)

THPOOL_MD_FACTOR_NEW

#define THPOOL_MD_FACTOR_NEW (0.2)

THPOOL_MD_FACTOR_EXISTS

#define THPOOL_MD_FACTOR_EXISTS (1 / 6.0)

bd_lvm_error_quark ()

GQuark
bd_lvm_error_quark (void);

bd_lvm_pvdata_free ()

void
bd_lvm_pvdata_free (BDLVMPVdata *data);

bd_lvm_pvdata_copy ()

BDLVMPVdata *
bd_lvm_pvdata_copy (BDLVMPVdata *data);

bd_lvm_vgdata_free ()

void
bd_lvm_vgdata_free (BDLVMVGdata *data);

bd_lvm_vgdata_copy ()

BDLVMVGdata *
bd_lvm_vgdata_copy (BDLVMVGdata *data);

bd_lvm_lvdata_free ()

void
bd_lvm_lvdata_free (BDLVMLVdata *data);

bd_lvm_lvdata_copy ()

BDLVMLVdata *
bd_lvm_lvdata_copy (BDLVMLVdata *data);

bd_lvm_is_supported_pe_size ()

gboolean
bd_lvm_is_supported_pe_size (guint64 size,
                             GError **error);

Parameters

size	size (in bytes) to test
error	place to store error (if any).	[out]

Returns

whether the given size is supported physical extent size or not

bd_lvm_get_supported_pe_sizes ()

guint64 *
bd_lvm_get_supported_pe_sizes (GError **error);

Parameters

error

place to store error (if any).

[out]

Returns

list of supported PE sizes.

[transfer full][array zero-terminated=1]

bd_lvm_get_max_lv_size ()

guint64
bd_lvm_get_max_lv_size (GError **error);

Parameters

error

place to store error (if any).

[out]

Returns

maximum LV size in bytes

bd_lvm_round_size_to_pe ()

guint64
bd_lvm_round_size_to_pe (guint64 size,
                         guint64 pe_size,
                         gboolean roundup,
                         GError **error);

Parameters

size	size to be rounded
pe_size	physical extent (PE) size or 0 to use the default
roundup	whether to round up or down (ceil or floor)
error	place to store error (if any).	[out]

Returns

size rounded to pe_size according to the roundup

Rounds given size up/down to a multiple of pe_size according to the value of the roundup parameter. If the rounded value is too big to fit in the return type, the result is rounded down (floored) regardless of the roundup parameter.

bd_lvm_get_lv_physical_size ()

guint64
bd_lvm_get_lv_physical_size (guint64 lv_size,
                             guint64 pe_size,
                             GError **error);

Parameters

lv_size	LV size
pe_size	PE size
error	place to store error (if any).	[out]

Returns

space taken on disk(s) by the LV with given size

Gives number of bytes needed for an LV with the size lv_size on an LVM stack using given pe_size .

bd_lvm_get_thpool_padding ()

guint64
bd_lvm_get_thpool_padding (guint64 size,
                           guint64 pe_size,
                           gboolean included,
                           GError **error);

Parameters

size	size of the thin pool
pe_size	PE size or 0 if the default value should be used
included	if padding is already included in the size
error	place to store error (if any).	[out]

Returns

size of the padding needed for a thin pool with the given size according to the pe_size and included

bd_lvm_is_valid_thpool_md_size ()

gboolean
bd_lvm_is_valid_thpool_md_size (guint64 size,
                                GError **error);

Parameters

size	the size to be tested
error	place to store error (if any).	[out]

Returns

whether the given size is a valid thin pool metadata size or not

bd_lvm_is_valid_thpool_chunk_size ()

gboolean
bd_lvm_is_valid_thpool_chunk_size (guint64 size,
                                   gboolean discard,
                                   GError **error);

Parameters

size	the size to be tested
discard	whether discard/TRIM is required to be supported or not
error	place to store error (if any).	[out]

Returns

whether the given size is a valid thin pool chunk size or not

bd_lvm_pvcreate ()

gboolean
bd_lvm_pvcreate (gchar *device,
                 guint64 data_alignment,
                 guint64 metadata_size,
                 GError **error);

Parameters

device	the device to make PV from
data_alignment	data (first PE) alignment or 0 to use the default
metadata_size	size of the area reserved for metadata or 0 to use the default
error	place to store error (if any).	[out]

Returns

whether the PV was successfully created or not

bd_lvm_pvresize ()

gboolean
bd_lvm_pvresize (gchar *device,
                 guint64 size,
                 GError **error);

Parameters

device	the device to resize
size	the new requested size of the PV or 0 if it should be adjusted to device's size
error	place to store error (if any).	[out]

Returns

whether the PV's size was successfully changed or not

If given size different from 0, sets the PV's size to the given value (see pvresize(8)). If given size 0, adjusts the PV's size to the underlaying block device's size.

bd_lvm_pvremove ()

gboolean
bd_lvm_pvremove (gchar *device,
                 GError **error);

Parameters

device	the PV device to be removed/destroyed
error	place to store error (if any).	[out]

Returns

whether the PV was successfully removed/destroyed or not

bd_lvm_pvmove ()

gboolean
bd_lvm_pvmove (gchar *src,
               gchar *dest,
               GError **error);

Parameters

src	the PV device to move extents off of
dest	the PV device to move extents onto or `NULL`.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the extents from the src PV where successfully moved or not

If dest is NULL, VG allocation rules are used for the extents from the src PV (see pvmove(8)).

bd_lvm_pvscan ()

gboolean
bd_lvm_pvscan (gchar *device,
               gboolean update_cache,
               GError **error);

Parameters

device	the device to scan for PVs or `NULL`.	[allow-none]
update_cache	whether to update the lvmetad cache or not
error	place to store error (if any).	[out]

Returns

whether the system or device was successfully scanned for PVs or not

The device argument is used only if update_cache is TRUE. Otherwise the whole system is scanned for PVs.

bd_lvm_pvinfo ()

BDLVMPVdata *
bd_lvm_pvinfo (gchar *device,
               GError **error);

Parameters

device	a PV to get information about or `NULL`
error	place to store error (if any).	[out]

Returns

information about the PV on the given device or NULL in case of error (the error ) gets populated in those cases).

[transfer full]

bd_lvm_pvs ()

BDLVMPVdata **
bd_lvm_pvs (GError **error);

Parameters

error

place to store error (if any).

[out]

Returns

information about PVs found in the system.

[array zero-terminated=1]

bd_lvm_vgcreate ()

gboolean
bd_lvm_vgcreate (gchar *name,
                 gchar **pv_list,
                 guint64 pe_size,
                 GError **error);

Parameters

name	name of the newly created VG
pv_list	list of PVs the newly created VG should use.	[array zero-terminated=1]
pe_size	PE size or 0 if the default value should be used
error	place to store error (if any).	[out]

Returns

whether the VG name was successfully created or not

bd_lvm_vgremove ()

gboolean
bd_lvm_vgremove (gchar *vg_name,
                 GError **error);

Parameters

vg_name	name of the to be removed VG
error	place to store error (if any).	[out]

Returns

whether the VG was successfully removed or not

bd_lvm_vgactivate ()

gboolean
bd_lvm_vgactivate (gchar *vg_name,
                   GError **error);

Parameters

vg_name	name of the to be activated VG
error	place to store error (if any).	[out]

Returns

whether the VG was successfully activated or not

bd_lvm_vgdeactivate ()

gboolean
bd_lvm_vgdeactivate (gchar *vg_name,
                     GError **error);

Parameters

vg_name	name of the to be deactivated VG
error	place to store error (if any).	[out]

Returns

whether the VG was successfully deactivated or not

bd_lvm_vgextend ()

gboolean
bd_lvm_vgextend (gchar *vg_name,
                 gchar *device,
                 GError **error);

Parameters

vg_name	name of the to be extended VG
device	PV device to extend the `vg_name` VG with
error	place to store error (if any).	[out]

Returns

whether the VG vg_name was successfully extended with the given device or not.

bd_lvm_vgreduce ()

gboolean
bd_lvm_vgreduce (gchar *vg_name,
                 gchar *device,
                 GError **error);

Parameters

vg_name	name of the to be reduced VG
device	PV device the `vg_name` VG should be reduced of or `NULL` if the VG should be reduced of the missing PVs.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the VG vg_name was successfully reduced of the given device or not

Note: This function does not move extents off of the PV before removing it from the VG. You must do that first by calling bd_lvm_pvmove.

bd_lvm_vginfo ()

BDLVMVGdata *
bd_lvm_vginfo (gchar *vg_name,
               GError **error);

Parameters

vg_name	a VG to get information about
error	place to store error (if any).	[out]

Returns

information about the vg_name VG or NULL in case of error (the error ) gets populated in those cases).

[transfer full]

bd_lvm_vgs ()

BDLVMVGdata **
bd_lvm_vgs (GError **error);

Parameters

error

place to store error (if any).

[out]

Returns

information about VGs found in the system.

[array zero-terminated=1]

bd_lvm_lvorigin ()

gchar *
bd_lvm_lvorigin (gchar *vg_name,
                 gchar *lv_name,
                 GError **error);

Parameters

vg_name	name of the VG containing the queried LV
lv_name	name of the queried LV
error	place to store error (if any).	[out]

Returns

the origin volume for the vg_name /lv_name LV or NULL if failed to determine (error ) is set in those cases).

[transfer full]

bd_lvm_lvcreate ()

gboolean
bd_lvm_lvcreate (gchar *vg_name,
                 gchar *lv_name,
                 guint64 size,
                 gchar **pv_list,
                 GError **error);

Parameters

vg_name	name of the VG to create a new LV in
lv_name	name of the to-be-created LV
size	requested size of the new LV
pv_list	list of PVs the newly created LV should use or `NULL` if not specified.	[allow-none][array zero-terminated=1]
error	place to store error (if any).	[out]

Returns

whether the given vg_name /lv_name LV was successfully created or not

bd_lvm_lvremove ()

gboolean
bd_lvm_lvremove (gchar *vg_name,
                 gchar *lv_name,
                 gboolean force,
                 GError **error);

Parameters

vg_name	name of the VG containing the to-be-removed LV
lv_name	name of the to-be-removed LV
force	whether to force removal or not
error	place to store error (if any).	[out]

Returns

whether the vg_name /lv_name LV was successfully removed or not

bd_lvm_lvresize ()

gboolean
bd_lvm_lvresize (gchar *vg_name,
                 gchar *lv_name,
                 guint64 size,
                 GError **error);

Parameters

vg_name	name of the VG containing the to-be-resized LV
lv_name	name of the to-be-resized LV
size	the requested new size of the LV
error	place to store error (if any).	[out]

Returns

whether the vg_name /lv_name LV was successfully resized or not

bd_lvm_lvactivate ()

gboolean
bd_lvm_lvactivate (gchar *vg_name,
                   gchar *lv_name,
                   gboolean ignore_skip,
                   GError **error);

Parameters

vg_name	name of the VG containing the to-be-activated LV
lv_name	name of the to-be-activated LV
ignore_skip	whether to ignore the skip flag or not
error	place to store error (if any).	[out]

Returns

whether the vg_name /lv_name LV was successfully activated or not

bd_lvm_lvdeactivate ()

gboolean
bd_lvm_lvdeactivate (gchar *vg_name,
                     gchar *lv_name,
                     GError **error);

Parameters

vg_name	name of the VG containing the to-be-deactivated LV
lv_name	name of the to-be-deactivated LV
error	place to store error (if any).	[out]

Returns

whether the vg_name /lv_name LV was successfully deactivated or not

bd_lvm_lvsnapshotcreate ()

gboolean
bd_lvm_lvsnapshotcreate (gchar *vg_name,
                         gchar *origin_name,
                         gchar *snapshot_name,
                         guint64 size,
                         GError **error);

Parameters

vg_name	name of the VG containing the LV a new snapshot should be created of
origin_name	name of the LV a new snapshot should be created of
snapshot_name	name fo the to-be-created snapshot
size	requested size for the snapshot
error	place to store error (if any).	[out]

Returns

whether the snapshot_name snapshot of the vg_name /origin_name LV was successfully created or not.

bd_lvm_lvsnapshotmerge ()

gboolean
bd_lvm_lvsnapshotmerge (gchar *vg_name,
                        gchar *snapshot_name,
                        GError **error);

Parameters

vg_name	name of the VG containing the to-be-merged LV snapshot
snapshot_name	name of the to-be-merged LV snapshot
error	place to store error (if any).	[out]

Returns

whether the vg_name /snapshot_name LV snapshot was successfully merged or not

bd_lvm_lvinfo ()

BDLVMLVdata *
bd_lvm_lvinfo (gchar *vg_name,
               gchar *lv_name,
               GError **error);

Parameters

vg_name	name of the VG that contains the LV to get information about
lv_name	name of the LV to get information about
error	place to store error (if any).	[out]

Returns

information about the vg_name /lv_name LV or NULL in case of error (the error ) gets populated in those cases).

[transfer full]

bd_lvm_lvs ()

BDLVMLVdata **
bd_lvm_lvs (gchar *vg_name,
            GError **error);

Parameters

vg_name	name of the VG to get information about LVs from.	[allow-none]
error	place to store error (if any).	[out]

Returns

information about LVs found in the given vg_name VG or in system if vg_name is NULL.

[array zero-terminated=1]

bd_lvm_thpoolcreate ()

gboolean
bd_lvm_thpoolcreate (gchar *vg_name,
                     gchar *lv_name,
                     guint64 size,
                     guint64 md_size,
                     guint64 chunk_size,
                     gchar *profile,
                     GError **error);

Parameters

vg_name	name of the VG to create a thin pool in
lv_name	name of the to-be-created pool LV
size	requested size of the to-be-created pool
md_size	requested metadata size or 0 to use the default
chunk_size	requested chunk size or 0 to use the default
profile	profile to use (see lvm(8) for more information) or `NULL` to use the default.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the vg_name /lv_name thin pool was successfully created or not

bd_lvm_thlvcreate ()

gboolean
bd_lvm_thlvcreate (gchar *vg_name,
                   gchar *pool_name,
                   gchar *lv_name,
                   guint64 size,
                   GError **error);

Parameters

vg_name	name of the VG containing the thin pool providing extents for the to-be-created thin LV
pool_name	name of the pool LV providing extents for the to-be-created thin LV
lv_name	name of the to-be-created thin LV
size	requested virtual size of the to-be-created thin LV
error	place to store error (if any).	[out]

Returns

whether the vg_name /lv_name thin LV was successfully created or not

bd_lvm_thlvpoolname ()

gchar *
bd_lvm_thlvpoolname (gchar *vg_name,
                     gchar *lv_name,
                     GError **error);

Parameters

vg_name	name of the VG containing the queried thin LV
lv_name	name of the queried thin LV
error	place to store error (if any).	[out]

Returns

the name of the pool volume for the vg_name /lv_name thin LV or NULL if failed to determine (error ) is set in those cases).

[transfer full]

bd_lvm_thsnapshotcreate ()

gboolean
bd_lvm_thsnapshotcreate (gchar *vg_name,
                         gchar *origin_name,
                         gchar *snapshot_name,
                         gchar *pool_name,
                         GError **error);

Parameters

vg_name	name of the VG containing the thin LV a new snapshot should be created of
origin_name	name of the thin LV a new snapshot should be created of
snapshot_name	name fo the to-be-created snapshot
pool_name	name of the thin pool to create the snapshot in or `NULL` if not specified.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the snapshot_name snapshot of the vg_name /origin_name thin LV was successfully created or not.

bd_lvm_set_global_config ()

gboolean
bd_lvm_set_global_config (gchar *new_config,
                          GError **error);

Parameters

new_config	string representation of the new global LVM configuration to set or `NULL` to reset to default.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the new requested global config new_config was successfully set or not

bd_lvm_get_global_config ()

gchar *
bd_lvm_get_global_config (GError **error);

Parameters

error

place to store error (if any).

[out]

Returns

a copy of a string representation of the currently set LVM global configuration.

[transfer full]

Types and Values

USE_DEFAULT_PE_SIZE

#define USE_DEFAULT_PE_SIZE 0

BD_LVM_ERROR

#define BD_LVM_ERROR bd_lvm_error_quark ()

enum BDLVMError

Members

BD_LVM_ERROR_PARSE

BDLVMPVdata

typedef struct {
    gchar *pv_name;
    gchar *pv_uuid;
    guint64 pe_start;
    gchar *vg_name;
    gchar *vg_uuid;
    guint64 vg_size;
    guint64 vg_free;
    guint64 vg_extent_size;
    guint64 vg_extent_count;
    guint64 vg_free_count;
    guint64 vg_pv_count;
} BDLVMPVdata;

BDLVMVGdata

typedef struct {
    gchar *name;
    gchar *uuid;
    guint64 size;
    guint64 free;
    guint64 extent_size;
    guint64 extent_count;
    guint64 free_count;
    guint64 pv_count;
} BDLVMVGdata;

BDLVMLVdata

typedef struct {
    gchar *lv_name;
    gchar *vg_name;
    gchar *uuid;
    guint64 size;
    gchar *attr;
    gchar *segtype;
} BDLVMLVdata;