MD RAID: libblockdev Reference Manual

MD RAID

MD RAID — plugin for basic operations with MD RAID

Functions

#define	BD_MD_SUPERBLOCK_SIZE
#define	BD_MD_CHUNK_SIZE
GQuark	bd_md_error_quark ()
BDMDExamineData *	bd_md_examine_data_copy ()
void	bd_md_examine_data_free ()
void	bd_md_detail_data_free ()
BDMDDetailData *	bd_md_detail_data_copy ()
guint64	bd_md_get_superblock_size ()
gboolean	bd_md_create ()
gboolean	bd_md_destroy ()
gboolean	bd_md_deactivate ()
gboolean	bd_md_activate ()
gboolean	bd_md_run ()
gboolean	bd_md_nominate ()
gboolean	bd_md_denominate ()
gboolean	bd_md_add ()
gboolean	bd_md_remove ()
BDMDExamineData *	bd_md_examine ()
gchar *	bd_md_canonicalize_uuid ()
gchar *	bd_md_get_md_uuid ()
BDMDDetailData *	bd_md_detail ()
gchar *	bd_md_node_from_name ()
gchar *	bd_md_name_from_node ()

Types and Values

#define	BD_MD_ERROR
enum	BDMDError
	BDMDExamineData
	BDMDDetailData

Includes

#include <mdraid.h>

Description

A plugin for basic operations with MD RAID. Also sizes are in bytes unless specified otherwise.

Functions

BD_MD_SUPERBLOCK_SIZE

#define BD_MD_SUPERBLOCK_SIZE (2 MiB)

BD_MD_CHUNK_SIZE

#define BD_MD_CHUNK_SIZE (512 KiB)

bd_md_error_quark ()

GQuark
bd_md_error_quark (void);

bd_md_examine_data_copy ()

BDMDExamineData *
bd_md_examine_data_copy (BDMDExamineData *data);

Creates a new copy of data .

bd_md_examine_data_free ()

void
bd_md_examine_data_free (BDMDExamineData *data);

Frees data .

bd_md_detail_data_free ()

void
bd_md_detail_data_free (BDMDDetailData *data);

Frees data .

bd_md_detail_data_copy ()

BDMDDetailData *
bd_md_detail_data_copy (BDMDDetailData *data);

Creates a new copy of data .

bd_md_get_superblock_size ()

guint64
bd_md_get_superblock_size (guint64 size,
                           gchar *version,
                           GError **error);

Parameters

size	size of the array
version	metadata version or `NULL` to use the current default version.	[allow-none]
error	place to store error (if any).	[out]

Returns

Calculated superblock size for given array size and metadata version or default if unsupported version is used.

bd_md_create ()

gboolean
bd_md_create (gchar *device_name,
              gchar *level,
              gchar **disks,
              guint64 spares,
              gchar *version,
              gboolean bitmap,
              GError **error);

Parameters

device_name	name of the device to create
level	RAID level (as understood by mdadm, see mdadm(8))
disks	disks to use for the new RAID (including spares).	[array zero-terminated=1]
spares	number of spare devices
version	metadata version.	[allow-none]
bitmap	whether to create an internal bitmap on the device or not
error	place to store error (if any).	[out]

Returns

whether the new MD RAID device device_name was successfully created or not

bd_md_destroy ()

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

Parameters

device	device to destroy MD RAID metadata on
error	place to store error (if any).	[out]

Returns

whether the MD RAID metadata was successfully destroyed on device or not

bd_md_deactivate ()

gboolean
bd_md_deactivate (gchar *device_name,
                  GError **error);

Parameters

device_name	name of the RAID device to deactivate
error	place to store error (if any).	[out]

Returns

whether the RAID device device_name was successfully deactivated or not

bd_md_activate ()

gboolean
bd_md_activate (gchar *device_name,
                gchar **members,
                gchar *uuid,
                GError **error);

Parameters

device_name	name of the RAID device to activate
members	member devices to be considered for `device` activation.	[allow-none][array zero-terminated=1]
uuid	UUID (in the MD RAID format!) of the MD RAID to activate.	[allow-none]
error	place to store error (if any).	[out]

Returns

whether the MD RAID device was successfully activated or not

Note: either members or uuid (or both) have to be specified.

bd_md_run ()

gboolean
bd_md_run (gchar *raid_name,
           GError **error);

Parameters

raid_name	name of the (possibly degraded) MD RAID to be started
error	place to store error (if any).	[out]

Returns

whether the raid_name was successfully started or not

bd_md_nominate ()

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

Parameters

device	device to nominate (add to its appropriate RAID) as a MD RAID device
error	place to store error (if any).	[out]

Returns

whether the device was successfully nominated (added to its appropriate RAID) or not

Note: may start the MD RAID if it becomes ready by adding device .

bd_md_denominate ()

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

Parameters

device	device to denominate (remove from its appropriate RAID) as a MD RAID device
error	place to store error (if any).	[out]

Returns

whether the device was successfully denominated (added to its appropriate RAID) or not

Note: may start the MD RAID if it becomes ready by adding device .

bd_md_add ()

gboolean
bd_md_add (gchar *raid_name,
           gchar *device,
           guint64 raid_devs,
           GError **error);

Parameters

raid_name	name of the RAID device to add `device` into
device	name of the device to add to the `raid_name` RAID device
raid_devs	number of devices the `raid_name` RAID should actively use or 0 to leave unspecified (see below)
error	place to store error (if any).	[out]

Returns

whether the device was successfully added to the raid_name RAID or not

The raid_devs parameter is used when adding devices to a raid array that has no actual redundancy. In this case it is necessary to explicitly grow the array all at once rather than manage it in the sense of adding spares.

Whether the new device will be added as a spare or an active member is decided by mdadm.

bd_md_remove ()

gboolean
bd_md_remove (gchar *raid_name,
              gchar *device,
              gboolean fail,
              GError **error);

Parameters

raid_name	name of the RAID device to remove `device` from
device	device to remove from the `raid_name` RAID
fail	whether to mark the `device` as failed before removing
error	place to store error (if any).	[out]

Returns

whether the device was successfully removed from the raid_name RAID or not.

bd_md_examine ()

BDMDExamineData *
bd_md_examine (gchar *device,
               GError **error);

Parameters

device	name of the device (a member of an MD RAID) to examine
error	place to store error (if any).	[out]

Returns

information about the MD RAID extracted from the device

bd_md_canonicalize_uuid ()

gchar *
bd_md_canonicalize_uuid (gchar *uuid,
                         GError **error);

Parameters

uuid	UUID to canonicalize
error	place to store error (if any).	[out]

Returns

cannonicalized form of uuid or NULL in case of error

This function expects a UUID in the form that mdadm returns. The change is as follows: 3386ff85:f5012621:4a435f06:1eb47236 -> 3386ff85-f501-2621-4a43-5f061eb47236.

[transfer full]

bd_md_get_md_uuid ()

gchar *
bd_md_get_md_uuid (gchar *uuid,
                   GError **error);

Parameters

uuid	UUID to transform into format used by MD RAID
error	place to store error (if any).	[out]

Returns

transformed form of uuid or NULL in case of error

This function expects a UUID in the canonical (traditional format) and returns a UUID in the format used by MD RAID and is thus reverse to bd_md_canonicalize_uuid(). The change is as follows: 3386ff85-f501-2621-4a43-5f061eb47236 -> 3386ff85:f5012621:4a435f06:1eb47236.

[transfer full]

bd_md_detail ()

BDMDDetailData *
bd_md_detail (gchar *raid_name,
              GError **error);

Parameters

raid_name	name of the MD RAID to examine
error	place to store error (if any).	[out]

Returns

information about the MD RAID raid_name

bd_md_node_from_name ()

gchar *
bd_md_node_from_name (gchar *name,
                      GError **error);

Parameters

name	name of the MD RAID
error	place to store error (if any).	[out]

Returns

path to the name MD RAID's device node or NULL in case of error

bd_md_name_from_node ()

gchar *
bd_md_name_from_node (gchar *node,
                      GError **error);

Parameters

node	path of the MD RAID's device node
error	place to store error (if any).	[out]

Returns

name of the MD RAID the device node belongs to or NULL in case of error

Types and Values

BD_MD_ERROR

#define BD_MD_ERROR bd_md_error_quark ()

enum BDMDError

Members

BD_MD_ERROR_PARSE
BD_MD_ERROR_BAD_FORMAT
BD_MD_ERROR_NO_MATCH

BDMDExamineData

typedef struct {
    gchar *device;
    gchar *level;
    guint64 num_devices;
    gchar *name;
    guint64 size;
    gchar *uuid;
    guint64 update_time;
    gchar *dev_uuid;
    guint64 events;
    gchar *metadata;
} BDMDExamineData;

BDMDDetailData

typedef struct {
    gchar *device;
    gchar *metadata;
    gchar *creation_time;
    gchar *level;
    gchar *name;
    guint64 array_size;
    guint64 use_dev_size;
    guint64 raid_devices;
    guint64 total_devices;
    guint64 active_devices;
    guint64 working_devices;
    guint64 failed_devices;
    guint64 spare_devices;
    gboolean clean;
    gchar *uuid;
} BDMDDetailData;