## MD RAID

MD RAID — plugin for basic operations with MD RAID

## Functions

gboolean | bd_md_init ()
void | bd_md_close ()
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 ()
gchar * | bd_md_get_status ()
gboolean | bd_md_set_bitmap_location ()
gchar * | bd_md_get_bitmap_location ()
gboolean | bd_md_request_sync_action ()
gboolean | bd_md_is_tech_avail ()

## Types and Values

#define | BD_MD_SUPERBLOCK_SIZE
#define | BD_MD_CHUNK_SIZE
#define | BD_MD_ERROR
enum | BDMDError
| BDMDExamineData
| BDMDDetailData
enum | BDMDTech
enum | BDMDTechMode

## Includes

    #include <mdraid.h>

## Description

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

## Functions

### bd_md_init ()

    gboolean
    bd_md_init (void);

Initializes the plugin. **This function is called automatically by the library's initialization functions.**

### bd_md_close ()

    void
    bd_md_close (void);

Cleans up after the plugin. **This function is called automatically by the library's functions that unload it.**

### bd_md_error_quark ()

    GQuark
    bd_md_error_quark (void);

[skip]

### bd_md_examine_data_copy ()

    BDMDExamineData *
    bd_md_examine_data_copy (BDMDExamineData *data);

Creates a new copy of `data` .

[skip]

#### Parameters

data | `BDMDExamineData` to copy. | [nullable]

### bd_md_examine_data_free ()

    void
    bd_md_examine_data_free (BDMDExamineData *data);

Frees `data` .

[skip]

#### Parameters

data | `BDMDExamineData` to free. | [nullable]

### bd_md_detail_data_free ()

    void
    bd_md_detail_data_free (BDMDDetailData *data);

Frees `data` .

[skip]

#### Parameters

data | `BDMDDetailData` to free. | [nullable]

### bd_md_detail_data_copy ()

    BDMDDetailData *
    bd_md_detail_data_copy (BDMDDetailData *data);

Creates a new copy of `data` .

[skip]

#### Parameters

data | `BDMDDetailData` to copy. | [nullable]

### bd_md_get_superblock_size ()

    guint64
    bd_md_get_superblock_size (guint64 member_size,
                               const gchar *version,
                               GError **error);

#### Parameters

member_size | size of an array member |
version | metadata version or `NULL` to use the current default version. | [nullable]
error | place to store error (if any). | [out][optional]

#### Returns

Calculated superblock size for an array with a given `member_size` and metadata `version` or default if unsupported `version` is used.

Tech category: always available

### bd_md_create ()

    gboolean
    bd_md_create (const gchar *device_name,
                  const gchar *level,
                  const gchar **disks,
                  guint64 spares,
                  const gchar *version,
                  const gchar *bitmap,
                  guint64 chunk_size,
                  const BDExtraArg **extra,
                  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. | [nullable]
bitmap | write-intent bitmap location ('none', 'internal') or `NULL` to let mdadm decide (i.e. internal > 100GB). | [nullable]
chunk_size | chunk size of the device to create |
extra | extra options for the creation (right now passed to the 'mdadm' utility). | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

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

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_CREATE`

### bd_md_destroy ()

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

#### Parameters

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

#### Returns

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

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_DELETE`

### bd_md_deactivate ()

    gboolean
    bd_md_deactivate (const gchar *raid_spec,
                      GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) |
error | place to store error (if any). | [out][optional]

#### Returns

whether the RAID device `raid_spec` was successfully deactivated or not

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_activate ()

    gboolean
    bd_md_activate (const gchar *raid_spec,
                    const gchar **members,
                    const gchar *uuid,
                    gboolean start_degraded,
                    const BDExtraArg **extra,
                    GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to activate (if not given "--scan" is implied and `members` is ignored). | [nullable]
members | member devices to be considered for `device` activation. | [nullable][array zero-terminated=1]
uuid | UUID (in the MD RAID format!) of the MD RAID to activate. | [nullable]
start_degraded | whether to start the array even if it's degraded |
extra | extra options for the activation (right now passed to the 'mdadm' utility). | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

whether the MD RAID `device` was successfully activated or not

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

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_run ()

    gboolean
    bd_md_run (const gchar *raid_spec,
               GError **error);

#### Parameters

raid_spec | specification of the (possibly degraded) RAID device (name, node or path) to be started |
error | place to store error (if any). | [out][optional]

#### Returns

whether the `raid_spec` was successfully started or not

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_nominate ()

    gboolean
    bd_md_nominate (const 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][optional]

#### 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` .

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_denominate ()

    gboolean
    bd_md_denominate (const 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][optional]

#### 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` .

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_add ()

    gboolean
    bd_md_add (const gchar *raid_spec,
               const gchar *device,
               guint64 raid_devs,
               const BDExtraArg **extra,
               GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to add `device` into |
device | name of the device to add to the `raid_spec` RAID device |
raid_devs | number of devices the `raid_spec` RAID should actively use or 0 to leave unspecified (see below) |
extra | extra options for the addition (right now passed to the 'mdadm' utility). | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `device` was successfully added to the `raid_spec` 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.

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_remove ()

    gboolean
    bd_md_remove (const gchar *raid_spec,
                  const gchar *device,
                  gboolean fail,
                  const BDExtraArg **extra,
                  GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to remove `device` from |
device | device to remove from the `raid_spec` RAID |
fail | whether to mark the `device` as failed before removing |
extra | extra options for the removal (right now passed to the 'mdadm' utility). | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `device` was successfully removed from the `raid_spec` RAID or not.

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_examine ()

    BDMDExamineData *
    bd_md_examine (const 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][optional]

#### Returns

information about the MD RAID extracted from the `device`

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_QUERY`

### bd_md_canonicalize_uuid ()

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

#### Parameters

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

#### Returns

canonicalized 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

Tech category: always available.

[transfer full]

### bd_md_get_md_uuid ()

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

#### Parameters

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

#### 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

Tech category: always available.

[transfer full]

### bd_md_detail ()

    BDMDDetailData *
    bd_md_detail (const gchar *raid_spec,
                  GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to examine |
error | place to store error (if any). | [out][optional]

#### Returns

information about the MD RAID `raid_spec`

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_QUERY`

### bd_md_node_from_name ()

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

#### Parameters

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

#### Returns

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

Tech category: always available

### bd_md_name_from_node ()

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

#### Parameters

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

#### Returns

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

Tech category: always available

### bd_md_get_status ()

    gchar *
    bd_md_get_status (const gchar *raid_spec,
                      GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to get status |
error | place to store error (if any). | [out][optional]

#### Returns

status of the `raid_spec` RAID.

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_QUERY`.

[transfer full]

### bd_md_set_bitmap_location ()

    gboolean
    bd_md_set_bitmap_location (const gchar *raid_spec,
                               const gchar *location,
                               GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to set the bitmap location |
location | bitmap location (none, internal or path) |
error | place to store error (if any). | [out][optional]

#### Returns

whether `location` was successfully set for `raid_spec`

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_get_bitmap_location ()

    gchar *
    bd_md_get_bitmap_location (const gchar *raid_spec,
                               GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to get the bitmap location |
error | place to store error (if any). | [out][optional]

#### Returns

bitmap location for `raid_spec`

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_QUERY`.

[transfer full]

### bd_md_request_sync_action ()

    gboolean
    bd_md_request_sync_action (const gchar *raid_spec,
                               const gchar *action,
                               GError **error);

#### Parameters

raid_spec | specification of the RAID device (name, node or path) to request sync action on |
action | requested sync action (resync, recovery, check, repair or idle) |
error | place to store error (if any). | [out][optional]

#### Returns

whether the `action` was successfully requested for the `raid_spec` RAID or not.

Tech category: `BD_MD_TECH_MDRAID`-`BD_MD_TECH_MODE_MODIFY`

### bd_md_is_tech_avail ()

    gboolean
    bd_md_is_tech_avail (BDMDTech tech,
                         guint64 mode,
                         GError **error);

#### Parameters

tech | the queried tech |
mode | a bit mask of queried modes of operation for `tech` |
error | place to store error (details about why the `tech` -`mode` combination is not available). | [out][optional]

#### Returns

whether the `tech` -`mode` combination is available -- supported by the plugin implementation and having all the runtime dependencies available

## Types and Values

### BD_MD_SUPERBLOCK_SIZE

    #define             BD_MD_SUPERBLOCK_SIZE

### BD_MD_CHUNK_SIZE

    #define             BD_MD_CHUNK_SIZE

### BD_MD_ERROR

    #define             BD_MD_ERROR

### enum BDMDError

#### Members

BD_MD_ERROR_TECH_UNAVAIL |  |
BD_MD_ERROR_FAIL |  |
BD_MD_ERROR_PARSE |  |
BD_MD_ERROR_BAD_FORMAT |  |
BD_MD_ERROR_NO_MATCH |  |
BD_MD_ERROR_INVAL |  |

### 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;
        guint64 chunk_size;
    } BDMDExamineData;

#### Members

gchar *`device`; | path of the MD device |
gchar *`level`; | RAID level of the device |
guint64 `num_devices`; | number of devices used by the MD device |
gchar *`name`; | name of the MD device |
guint64 `size`; | size of the MD device |
gchar *`uuid`; | array UUID |
guint64 `update_time`; | update time of the MD device |
gchar *`dev_uuid`; | UUID of the member device |
guint64 `events`; | number of events on the MD device |
gchar *`metadata`; | version of the metadata used by the MD device |
guint64 `chunk_size`; | chunk size used by the MD device |

### 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;
        gchar *container;
    } BDMDDetailData;

#### Members

gchar *`device`; | path of the device |
gchar *`metadata`; | version of the metadata used by the device |
gchar *`creation_time`; | creation time |
gchar *`level`; | level of the MD RAID |
gchar *`name`; | name of the MD device |
guint64 `array_size`; | size of the MD array |
guint64 `use_dev_size`; | size of the used space |
guint64 `raid_devices`; | number of devices in the MD array |
guint64 `total_devices`; | total number of devices in the MD array |
guint64 `active_devices`; | number of active devices in the MD array |
guint64 `working_devices`; | number of working devices in the MD array |
guint64 `failed_devices`; | number of failed devices in the MD array |
guint64 `spare_devices`; | number of spare devices in the MD array |
gboolean `clean`; | whether the MD array is clean or not |
gchar *`uuid`; | uuid of the MD array |
gchar *`container`; | path of the MD container this device belongs to |

### enum BDMDTech

#### Members

BD_MD_TECH_MDRAID |  |

### enum BDMDTechMode

#### Members

BD_MD_TECH_MODE_CREATE |  |
BD_MD_TECH_MODE_DELETE |  |
BD_MD_TECH_MODE_MODIFY |  |
BD_MD_TECH_MODE_QUERY |  |