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