KernelBlockDevices: libblockdev Reference Manual

## KernelBlockDevices KernelBlockDevices — plugin for operations with kernel block devices |

## Functions

gboolean | bd_kbd_check_deps ()
gboolean | bd_kbd_init ()
void | bd_kbd_close ()
gboolean | bd_kbd_bcache_attach ()
gboolean | bd_kbd_bcache_create ()
gboolean | bd_kbd_bcache_destroy ()
gboolean | bd_kbd_bcache_detach ()
gchar * | bd_kbd_bcache_get_backing_device ()
gchar * | bd_kbd_bcache_get_cache_device ()
BDKBDBcacheMode | bd_kbd_bcache_get_mode ()
BDKBDBcacheMode | bd_kbd_bcache_get_mode_from_str ()
const gchar * | bd_kbd_bcache_get_mode_str ()
gboolean | bd_kbd_bcache_set_mode ()
BDKBDBcacheStats * | bd_kbd_bcache_stats_copy ()
void | bd_kbd_bcache_stats_free ()
BDKBDBcacheStats * | bd_kbd_bcache_status ()
GQuark | bd_kbd_error_quark ()
gboolean | bd_kbd_zram_create_devices ()
gboolean | bd_kbd_zram_destroy_devices ()
gboolean | bd_kbd_zram_add_device ()
gboolean | bd_kbd_zram_remove_device ()
BDKBDZramStats * | bd_kbd_zram_get_stats ()
BDKBDZramStats * | bd_kbd_zram_stats_copy ()
void | bd_kbd_zram_stats_free ()
gboolean | bd_kbd_is_tech_avail ()

## Types and Values

enum | BDKBDBcacheMode
| BDKBDBcacheStats
enum | BDKBDError
| BDKBDZramStats
#define | BD_KBD_ERROR
enum | BDKBDTech
enum | BDKBDTechMode

## Includes

    #include <kbd.h>

## Description

A plugin for operations with kernel block devices.

## Functions

### bd_kbd_check_deps ()

    gboolean
    bd_kbd_check_deps (void);

#### Returns

whether the plugin's runtime dependencies are satisfied or not

Function checking plugin's runtime dependencies.

### bd_kbd_init ()

    gboolean
    bd_kbd_init (void);

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

### bd_kbd_close ()

    void
    bd_kbd_close (void);

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

### bd_kbd_bcache_attach ()

    gboolean
    bd_kbd_bcache_attach (const gchar *c_set_uuid,
                          const gchar *bcache_device,
                          GError **error);

#### Parameters

c_set_uuid | cache set UUID of the cache to attach |
bcache_device | bcache device to attach `c_set_uuid` cache to |
error | place to store error (if any). | [out]

#### Returns

whether the `c_set_uuid` cache was successfully attached to `bcache_device` or not

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_MODIFY`

### bd_kbd_bcache_create ()

    gboolean
    bd_kbd_bcache_create (const gchar *backing_device,
                          const gchar *cache_device,
                          const BDExtraArg **extra,
                          const gchar **bcache_device,
                          GError **error);

#### Parameters

backing_device | backing (slow) device of the cache |
cache_device | cache (fast) device of the cache |
extra | extra options for the creation (right now passed to the 'make-bcache' utility). | [allow-none][array zero-terminated=1]
bcache_device | place to store the name of the new bcache device (if any). | [out][allow-none][transfer full]
error | place to store error (if any). | [out]

#### Returns

whether the bcache device was successfully created or not

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_CREATE`

### bd_kbd_bcache_destroy ()

    gboolean
    bd_kbd_bcache_destroy (const gchar *bcache_device,
                           GError **error);

#### Parameters

bcache_device | bcache device to destroy |
error | place to store error (if any). | [out]

#### Returns

whether the bcache device `bcache_device` was successfully destroyed or not

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_DESTROY`

### bd_kbd_bcache_detach ()

    gboolean
    bd_kbd_bcache_detach (const gchar *bcache_device,
                          gchar **c_set_uuid,
                          GError **error);

#### Parameters

bcache_device | bcache device to detach the cache from |
c_set_uuid | cache set UUID of the detached cache. | [out][allow-none][transfer full]
error | place to store error (if any). | [out]

#### Returns

whether the bcache device `bcache_device` was successfully destroyed or not

Note: Flushes the cache first.

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_MODIFY`

### bd_kbd_bcache_get_backing_device ()

    gchar *
    bd_kbd_bcache_get_backing_device (const gchar *bcache_device,
                                      GError **error);

#### Parameters

bcache_device | Bcache device to get the backing device for |
error | place to store error (if any). | [out]

#### Returns

name of the backing device of the `bcache_device` or `NULL` if failed to determine (`error` is populated)

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_QUERY`.

[transfer full]

### bd_kbd_bcache_get_cache_device ()

    gchar *
    bd_kbd_bcache_get_cache_device (const gchar *bcache_device,
                                    GError **error);

#### Parameters

bcache_device | Bcache device to get the cache device for |
error | place to store error (if any). | [out]

#### Returns

name of the cache device of the `bcache_device` or `NULL` if failed to determine (`error` is populated)

Note: returns the name of the first cache device of `bcache_device` (in case there are more)

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_QUERY`.

[transfer full]

### bd_kbd_bcache_get_mode ()

    BDKBDBcacheMode
    bd_kbd_bcache_get_mode (const gchar *bcache_device,
                            GError **error);

#### Parameters

bcache_device | device to get mode of |
error | place to store error (if any). | [out]

#### Returns

current mode of the `bcache_device`

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_QUERY`

### bd_kbd_bcache_get_mode_from_str ()

    BDKBDBcacheMode
    bd_kbd_bcache_get_mode_from_str (const gchar *mode_str,
                                     GError **error);

#### Parameters

mode_str | string representation of mode |
error | place to store error (if any). | [out]

#### Returns

mode matching the `mode_str` given or `BD_KBD_MODE_UNKNOWN` in case of no match

### bd_kbd_bcache_get_mode_str ()

    const gchar *
    bd_kbd_bcache_get_mode_str (BDKBDBcacheMode mode,
                                GError **error);

#### Parameters

mode | mode to get string representation of |
error | place to store error (if any). | [out]

#### Returns

string representation of `mode` or `NULL` in case of error

Tech category: always available.

[transfer none]

### bd_kbd_bcache_set_mode ()

    gboolean
    bd_kbd_bcache_set_mode (const gchar *bcache_device,
                            BDKBDBcacheMode mode,
                            GError **error);

#### Parameters

bcache_device | bcache device to set mode of |
mode | mode to set |
error | place to store error (if any). | [out]

#### Returns

whether the mode was successfully set or not

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_MODIFY`

### bd_kbd_bcache_stats_copy ()

    BDKBDBcacheStats *
    bd_kbd_bcache_stats_copy (BDKBDBcacheStats *data);

Creates a new copy of `data` .

[skip]

### bd_kbd_bcache_stats_free ()

    void
    bd_kbd_bcache_stats_free (BDKBDBcacheStats *data);

Frees `data` .

[skip]

### bd_kbd_bcache_status ()

    BDKBDBcacheStats *
    bd_kbd_bcache_status (const gchar *bcache_device,
                          GError **error);

#### Parameters

bcache_device | bcache device to get status for |
error | place to store error (if any). | [out]

#### Returns

status of the `bcache_device` or `NULL` in case of error (`error` is set)

Tech category: `BD_KBD_TECH_BCACHE`-`BD_KBD_TECH_MODE_QUERY`.

[transfer full]

### bd_kbd_error_quark ()

    GQuark
    bd_kbd_error_quark (void);

[skip]

### bd_kbd_zram_create_devices ()

    gboolean
    bd_kbd_zram_create_devices (guint64 num_devices,
                                const guint64 *sizes,
                                const guint64 *nstreams,
                                GError **error);

#### Parameters

num_devices | number of devices to create |
sizes | requested sizes (in bytes) for created zRAM devices. | [array zero-terminated=1]
nstreams | numbers of streams for created zRAM devices. | [allow-none][array zero-terminated=1]
error | place to store error (if any). | [out]

#### Returns

whether `num_devices` zRAM devices were successfully created or not

**Lengths of `size` and `nstreams` (if given) have to be >= `num_devices` !**

Tech category: `BD_KBD_TECH_ZRAM`-`BD_KBD_TECH_MODE_CREATE`

### bd_kbd_zram_destroy_devices ()

    gboolean
    bd_kbd_zram_destroy_devices (GError **error);

#### Parameters

error | place to store error (if any). | [out]

#### Returns

whether zRAM devices were successfully destroyed or not

The only way how to destroy zRAM device right now is to unload the 'zram' module and thus destroy all of them. That's why this function doesn't allow specification of which devices should be destroyed.

Tech category: `BD_KBD_TECH_ZRAM`-`BD_KBD_TECH_MODE_DESTROY`

### bd_kbd_zram_add_device ()

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

#### Parameters

size | size of the zRAM device to add |
nstreams | number of streams to use for the new device (or 0 to use the defaults) |
device | place to store the name of the newly added device. | [allow-none][out]
error | place to store error (if any). | [out]

#### Returns

whether a new zRAM device was added or not

Tech category: `BD_KBD_TECH_ZRAM`-`BD_KBD_TECH_MODE_MODIFY`

### bd_kbd_zram_remove_device ()

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

#### Parameters

device | zRAM device to remove |
error | place to store error (if any). | [out]

#### Returns

whether the `device` was successfully removed or not

Tech category: `BD_KBD_TECH_ZRAM`-`BD_KBD_TECH_MODE_MODIFY`

### bd_kbd_zram_get_stats ()

    BDKBDZramStats *
    bd_kbd_zram_get_stats (const gchar *device,
                           GError **error);

#### Parameters

device | zRAM device to get stats for |
error | place to store error (if any). | [out]

#### Returns

statistics for the zRAM device

Tech category: `BD_KBD_TECH_ZRAM`-`BD_KBD_TECH_MODE_QUERY`.

[transfer full]

### bd_kbd_zram_stats_copy ()

    BDKBDZramStats *
    bd_kbd_zram_stats_copy (BDKBDZramStats *data);

Creates a new copy of `data` .

[skip]

### bd_kbd_zram_stats_free ()

    void
    bd_kbd_zram_stats_free (BDKBDZramStats *data);

Frees `data` .

[skip]

### bd_kbd_is_tech_avail ()

    gboolean
    bd_kbd_is_tech_avail (BDKBDTech tech,
                          guint64 mode,
                          GError **error);

#### Parameters

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

#### Returns

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

## Types and Values

### enum BDKBDBcacheMode

#### Members

BD_KBD_MODE_WRITETHROUGH |  |
BD_KBD_MODE_WRITEBACK |  |
BD_KBD_MODE_WRITEAROUND |  |
BD_KBD_MODE_NONE |  |
BD_KBD_MODE_UNKNOWN |  |

### BDKBDBcacheStats

    typedef struct {
        gchar *state;
        guint64 block_size;
        guint64 cache_size;
        guint64 cache_used;
        guint64 hits;
        guint64 misses;
        guint64 bypass_hits;
        guint64 bypass_misses;
    } BDKBDBcacheStats;

#### Members

gchar *`state`; | state of the cache |
guint64 `block_size`; | block size used by the cache |
guint64 `cache_size`; | size of the cache |
guint64 `cache_used`; | size of the used space in the cache |
guint64 `hits`; | number of hits |
guint64 `misses`; | number of misses |
guint64 `bypass_hits`; | number of bypass hits |
guint64 `bypass_misses`; | number of bypass misses |

### enum BDKBDError

#### Members

BD_KBD_ERROR_INVAL |  |
BD_KBD_ERROR_ZRAM_NOEXIST |  |
BD_KBD_ERROR_ZRAM_INVAL |  |
BD_KBD_ERROR_BCACHE_PARSE |  |
BD_KBD_ERROR_BCACHE_SETUP_FAIL |  |
BD_KBD_ERROR_BCACHE_DETACH_FAIL |  |
BD_KBD_ERROR_BCACHE_NOT_ATTACHED |  |
BD_KBD_ERROR_BCACHE_UUID |  |
BD_KBD_ERROR_BCACHE_MODE_FAIL |  |
BD_KBD_ERROR_BCACHE_MODE_INVAL |  |
BD_KBD_ERROR_BCACHE_NOEXIST |  |
BD_KBD_ERROR_BCACHE_INVAL |  |
BD_KBD_ERROR_TECH_UNAVAIL |  |

### BDKBDZramStats

    typedef struct {
        guint64 disksize;
        guint64 num_reads;
        guint64 num_writes;
        guint64 invalid_io;
        guint64 zero_pages;
        guint64 max_comp_streams;
        gchar* comp_algorithm;
        guint64 orig_data_size;
        guint64 compr_data_size;
        guint64 mem_used_total;
    } BDKBDZramStats;

see zRAM kernel documentation for details (https://www.kernel.org/doc/Documentation/blockdev/zram.txt)

### BD_KBD_ERROR

    #define             BD_KBD_ERROR

### enum BDKBDTech

#### Members

BD_KBD_TECH_ZRAM |  |
BD_KBD_TECH_BCACHE |  |

### enum BDKBDTechMode

#### Members

BD_KBD_TECH_MODE_CREATE |  |
BD_KBD_TECH_MODE_DESTROY |  |
BD_KBD_TECH_MODE_MODIFY |  |
BD_KBD_TECH_MODE_QUERY |  |