Utils: libblockdev Reference Manual for libblockdev 3.1.1.

## Utils

Utils — library providing utility functions used by the blockdev library and its plugins

## Functions

gboolean | (*BDUtilsProgExtract) ()
void | (*BDUtilsProgFunc) ()
void | (*BDUtilsLogFunc) ()
GQuark | bd_utils_exec_error_quark ()
GQuark | bd_utils_dev_utils_error_quark ()
gboolean | bd_utils_exec_and_report_error ()
gboolean | bd_utils_exec_and_report_status_error ()
gboolean | bd_utils_exec_and_capture_output ()
gboolean | bd_utils_exec_and_report_error_no_progress ()
gboolean | bd_utils_exec_and_report_progress ()
gboolean | bd_utils_exec_with_input ()
gboolean | bd_utils_prog_reporting_initialized ()
gboolean | bd_utils_init_logging ()
gboolean | bd_utils_init_prog_reporting ()
gboolean | bd_utils_init_prog_reporting_thread ()
gboolean | bd_utils_mute_prog_reporting_thread ()
void | bd_utils_report_finished ()
void | bd_utils_report_progress ()
guint64 | bd_utils_report_started ()
guint64 | bd_utils_get_next_task_id ()
void | bd_utils_log_task_status ()
void | bd_utils_log ()
void | bd_utils_log_format ()
void | bd_utils_log_stdout ()
gboolean | bd_utils_echo_str_to_file ()
void | bd_utils_set_log_level ()
gboolean | bd_utils_check_util_version ()
gint | bd_utils_version_cmp ()
BDExtraArg * | bd_extra_arg_new ()
BDExtraArg * | bd_extra_arg_copy ()
void | bd_extra_arg_free ()
void | bd_extra_arg_list_free ()
GType | bd_extra_arg_get_type ()
gchar * | bd_utils_resolve_device ()
gchar ** | bd_utils_get_device_symlinks ()
gboolean | bd_utils_have_kernel_module ()
gboolean | bd_utils_load_kernel_module ()
gboolean | bd_utils_unload_kernel_module ()
BDUtilsLinuxVersion * | bd_utils_get_linux_version ()
gint | bd_utils_check_linux_version ()
gboolean | bd_utils_dbus_service_available ()
GQuark | bd_utils_dbus_error_quark ()
GQuark | bd_utils_module_error_quark ()

## Types and Values

enum | BDUtilsProgStatus
#define | BD_UTILS_EXEC_ERROR
enum | BDUtilsExecError
enum | BDUtilsDevUtilsError
enum | BDUtilsDBusError
enum | BDUtilsModuleError
#define | BD_UTILS_DEV_UTILS_ERROR
#define | BD_UTILS_DBUS_ERROR
#define | BD_UTILS_MODULE_ERROR
| BDUtilsLinuxVersion
| BDExtraArg
#define | EXBIBYTE
#define | EiB
#define | GIBIBYTE
#define | GiB
#define | KIBIBYTE
#define | KiB
#define | MEBIBYTE
#define | MiB
#define | PEBIBYTE
#define | PiB
#define | TEBIBYTE
#define | TiB
#define | EB
#define | EXABYTE
#define | GB
#define | GIGABYTE
#define | KB
#define | KILOBYTE
#define | MB
#define | MEGABYTE
#define | PB
#define | PETABYTE
#define | TB
#define | TERABYTE
#define | BD_UTILS_LOG_EMERG
#define | BD_UTILS_LOG_ALERT
#define | BD_UTILS_LOG_CRIT
#define | BD_UTILS_LOG_ERR
#define | BD_UTILS_LOG_WARNING
#define | BD_UTILS_LOG_NOTICE
#define | BD_UTILS_LOG_INFO
#define | BD_UTILS_LOG_DEBUG

## Includes

    #include <utils.h>

## Description

## Functions

### BDUtilsProgExtract ()

    gboolean
    (*BDUtilsProgExtract) (const gchar *line,
                           guint8 *completion);

Callback function used to process a line captured from spawned command's standard output and standard error output. Typically used to extract completion percentage of a long-running job.

Note that both outputs are read simultaneously with no guarantees of message order this function is called with.

The value the `completion` points to may contain value previously returned from this callback or zero when called for the first time. This is useful for extractors where only some kind of a tick mark is printed out as a progress and previous value is needed to compute an incremented value. It's important to keep in mind that this function is only called over lines, i.e. progress reporting printing out tick marks (e.g. dots) without a newline character might not work properly.

The `line` string usually contains trailing newline character, which may be absent however in case the spawned command exits without printing one. It's guaranteed this function is called over remaining buffer no matter what the trailing character is.

#### Parameters

line | line to extract progress from |
completion | percentage of completion. | [out]

#### Returns

whether the line was a progress reporting line and should be excluded from the collected standard output string or not.

### BDUtilsProgFunc ()

    void
    (*BDUtilsProgFunc) (guint64 task_id,
                        BDUtilsProgStatus status,
                        guint8 completion,
                        gchar *msg);

#### Parameters

task_id | ID of the task/action the progress is reported for |
status | progress status |
completion | percentage of completion |
msg | arbitrary progress message (for the user). | [nullable]

### BDUtilsLogFunc ()

    void
    (*BDUtilsLogFunc) (gint level,
                       const gchar *msg);

Function type for logging function used by the libblockdev's exec utils to log the information about program executing.

#### Parameters

level | log level (as understood by syslog(3)) |
msg | log message |

### bd_utils_exec_error_quark ()

    GQuark
    bd_utils_exec_error_quark (void);

[skip]

### bd_utils_dev_utils_error_quark ()

    GQuark
    bd_utils_dev_utils_error_quark (void);

[skip]

### bd_utils_exec_and_report_error ()

    gboolean
    bd_utils_exec_and_report_error (const gchar **argv,
                                    const BDExtraArg **extra,
                                    GError **error);

#### Parameters

argv | the argv array for the call. | [array zero-terminated=1]
extra | extra arguments. | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `argv` was successfully executed (no error and exit code 0) or not

### bd_utils_exec_and_report_status_error ()

    gboolean
    bd_utils_exec_and_report_status_error (const gchar **argv,
                                           const BDExtraArg **extra,
                                           gint *status,
                                           GError **error);

#### Parameters

argv | the argv array for the call. | [array zero-terminated=1]
extra | extra arguments. | [nullable][array zero-terminated=1]
status | place to store the status. | [out]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `argv` was successfully executed (no error and exit code 0) or not

### bd_utils_exec_and_capture_output ()

    gboolean
    bd_utils_exec_and_capture_output (const gchar **argv,
                                      const BDExtraArg **extra,
                                      gchar **output,
                                      GError **error);

Note that any NULL bytes read from standard output and standard error output will be discarded.

#### Parameters

argv | the argv array for the call. | [array zero-terminated=1]
extra | extra arguments. | [nullable][array zero-terminated=1]
output | variable to store output to. | [out]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `argv` was successfully executed capturing the output or not

### bd_utils_exec_and_report_error_no_progress ()

    gboolean
    bd_utils_exec_and_report_error_no_progress
                                   (const gchar **argv,
                                    const BDExtraArg **extra,
                                    GError **error);

#### Parameters

argv | the argv array for the call. | [array zero-terminated=1]
extra | extra arguments. | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `argv` was successfully executed (no error and exit code 0) or not

### bd_utils_exec_and_report_progress ()

    gboolean
    bd_utils_exec_and_report_progress (const gchar **argv,
                                       const BDExtraArg **extra,
                                       BDUtilsProgExtract prog_extract,
                                       gint *proc_status,
                                       GError **error);

Note that any NULL bytes read from standard output and standard error output are treated as separators similar to newlines and `prog_extract` will be called with the respective chunk.

#### Parameters

argv | the argv array for the call. | [array zero-terminated=1]
extra | extra arguments. | [nullable][array zero-terminated=1]
prog_extract | function for extracting progress information. | [scope notified][nullable]
proc_status | place to store the process exit status. | [out]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `argv` was successfully executed (no error and exit code 0) or not

### bd_utils_exec_with_input ()

    gboolean
    bd_utils_exec_with_input (const gchar **argv,
                              const gchar *input,
                              const BDExtraArg **extra,
                              GError **error);

#### Parameters

argv | the argv array for the call. | [array zero-terminated=1]
input | input for the executed program. | [nullable]
extra | extra arguments. | [nullable][array zero-terminated=1]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `argv` was successfully executed (no error and exit code 0) or not

### bd_utils_prog_reporting_initialized ()

    gboolean
    bd_utils_prog_reporting_initialized (void);

#### Returns

TRUE if progress reporting has been initialized, i.e. a reporting function was set up with either bd_utils_init_prog_reporting or bd_utils_init_prog_reporting_thread (takes precedence). FALSE if bd_utils_mute_prog_reporting_thread was used to mute the thread.

### bd_utils_init_logging ()

    gboolean
    bd_utils_init_logging (BDUtilsLogFunc new_log_func,
                           GError **error);

#### Parameters

new_log_func | logging function to use or `NULL` to disable logging; use bd_utils_log_stdout to reset to the default behaviour. | [nullable][scope notified]
error | place to store error (if any). | [out][optional]

#### Returns

whether logging was successfully initialized or not

### bd_utils_init_prog_reporting ()

    gboolean
    bd_utils_init_prog_reporting (BDUtilsProgFunc new_prog_func,
                                  GError **error);

#### Parameters

new_prog_func | progress reporting function to use or `NULL` to reset to default. | [nullable][scope notified]
error | place to store error (if any). | [out][optional]

#### Returns

whether progress reporting was successfully initialized or not

### bd_utils_init_prog_reporting_thread ()

    gboolean
    bd_utils_init_prog_reporting_thread (BDUtilsProgFunc new_prog_func,
                                         GError **error);

#### Parameters

new_prog_func | progress reporting function to use on current thread or `NULL` to reset to default or global. | [nullable][scope notified]
error | place to store error (if any). | [out][optional]

#### Returns

whether progress reporting was successfully initialized or not

### bd_utils_mute_prog_reporting_thread ()

    gboolean
    bd_utils_mute_prog_reporting_thread (GError **error);

#### Parameters

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

#### Returns

whether progress reporting for the current thread was successfully muted (deinitialized even in presence of a global reporting function) or not

### bd_utils_report_finished ()

    void
    bd_utils_report_finished (guint64 task_id,
                              const gchar *msg);

#### Parameters

task_id | ID of the task/action |
msg | message describing the status of the task/action |

### bd_utils_report_progress ()

    void
    bd_utils_report_progress (guint64 task_id,
                              guint64 completion,
                              const gchar *msg);

#### Parameters

task_id | ID of the task/action |
completion | percentage of completion |
msg | message describing the status of the task/action |

### bd_utils_report_started ()

    guint64
    bd_utils_report_started (const gchar *msg);

#### Parameters

msg | message describing the started task/action |

#### Returns

ID of the started task/action

### bd_utils_get_next_task_id ()

    guint64
    bd_utils_get_next_task_id (void);

### bd_utils_log_task_status ()

    void
    bd_utils_log_task_status (guint64 task_id,
                              const gchar *msg);

#### Parameters

task_id | ID of the task the status of which is being logged |
msg | log message |

### bd_utils_log ()

    void
    bd_utils_log (gint level,
                  const gchar *msg);

#### Parameters

level | log level |
msg | log message |

### bd_utils_log_format ()

    void
    bd_utils_log_format (gint level,
                         const gchar *format,
                         ...);

#### Parameters

level | log level |
format | printf-style format for the log message |
... | arguments for `format` |

### bd_utils_log_stdout ()

    void
    bd_utils_log_stdout (gint level,
                         const gchar *msg);

Convenient function for logging to stdout. Can be used as BDUtilsLogFunc.

#### Parameters

level | log level |
msg | log message |

### bd_utils_echo_str_to_file ()

    gboolean
    bd_utils_echo_str_to_file (const gchar *str,
                               const gchar *file_path,
                               GError **error);

#### Parameters

str | string to write to `file_path` |
file_path | path to file |
error | place to store error (if any). | [out][optional]

#### Returns

whether the `str` was successfully written to `file_path` or not.

### bd_utils_set_log_level ()

    void
    bd_utils_set_log_level (gint level);

Level of messages to log. Only messages with level <= `level` will be logged. For example using with BD_UTILS_LOG_WARNING (default value) only messages with log levels BD_UTILS_LOG_WARNING, BD_UTILS_LOG_ERR, ..., BD_UTILS_LOG_EMERG will be logged.

Note: BD_UTILS_LOG_DEBUG level messages are always skipped unless compiled with `--enable-debug` configure option.

#### Parameters

level | log level |

### bd_utils_check_util_version ()

    gboolean
    bd_utils_check_util_version (const gchar *util,
                                 const gchar *version,
                                 const gchar *version_arg,
                                 const gchar *version_regexp,
                                 GError **error);

#### Parameters

util | name of the utility to check |
version | minimum required version of the utility or `NULL` if no version is required. | [nullable]
version_arg | argument to use with the `util` to get version info or `NULL` to use "--version". | [nullable]
version_regexp | regexp to extract version from the version info or `NULL` if only version is printed by "$ `util` `version_arg` ". | [nullable]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `util` is available in a version >= `version` or not (`error` is set in such case).

### bd_utils_version_cmp ()

    gint
    bd_utils_version_cmp (const gchar *ver_string1,
                          const gchar *ver_string2,
                          GError **error);

#### Parameters

ver_string1 | first version string |
ver_string2 | second version string |
error | place to store error (if any). | [out][optional]

#### Returns

-1, 0 or 1 if `ver_string1` is lower, the same or higher version as `ver_string2` respectively. If an error occurs, returns -2 and `error` is set.

**ONLY SUPPORTS VERSION STRINGS OF FORMAT `X[.Y[.Z[.Z2[.Z3...[-R]]]]]` where all components are natural numbers!**

### bd_extra_arg_new ()

    BDExtraArg *
    bd_extra_arg_new (const gchar *opt,
                      const gchar *val);

Example of calling `bd_fs_xfs_mkfs()` with an extra argument. This will result in calling `mkfs.xfs` with `-L label`.

    1
    2
    3
    4
    BDExtraArg label_arg = {"-L", "label"};
    const BDExtraArg *extra_args[2] = {&label_arg, NULL};

    ret = bd_fs_xfs_mkfs ("/dev/sda", extra_args, error);

[constructor]

#### Parameters

opt | extra option |
val | value for the extra option `opt` |

#### Returns

a new extra argument.

[transfer full]

### bd_extra_arg_copy ()

    BDExtraArg *
    bd_extra_arg_copy (BDExtraArg *arg);

Creates a new copy of `arg` .

#### Parameters

arg | `BDExtraArg` to copy. | [nullable]

### bd_extra_arg_free ()

    void
    bd_extra_arg_free (BDExtraArg *arg);

Frees `arg` .

#### Parameters

arg | `BDExtraArg` to free. | [nullable]

### bd_extra_arg_list_free ()

    void
    bd_extra_arg_list_free (BDExtraArg **args);

Frees `args` and all its elements.

#### Parameters

args | A list of `BDExtraArg` to free. | [nullable][array zero-terminated=1]

### bd_extra_arg_get_type ()

    GType
    bd_extra_arg_get_type (void);

### bd_utils_resolve_device ()

    gchar *
    bd_utils_resolve_device (const gchar *dev_spec,
                             GError **error);

#### Parameters

dev_spec | specification of the device (e.g. "/dev/sda", any symlink, or the name of a file under "/dev") |
error | place to store error (if any). | [out][optional]

#### Returns

the full real path of the device (e.g. "/dev/md126" for "/dev/md/my_raid") or `NULL` in case of error.

[transfer full]

### bd_utils_get_device_symlinks ()

    gchar **
    bd_utils_get_device_symlinks (const gchar *dev_spec,
                                  GError **error);

#### Parameters

dev_spec | specification of the device (e.g. "/dev/sda", any symlink, or the name of a file under "/dev") |
error | place to store error (if any). | [out][optional]

#### Returns

a list of all symlinks (known to udev) for the device specified with `dev_spec` or `NULL` in case of error.

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

### bd_utils_have_kernel_module ()

    gboolean
    bd_utils_have_kernel_module (const gchar *module_name,
                                 GError **error);

#### Parameters

module_name | name of the kernel module to check |
error | place to store error (if any). | [out][optional]

#### Returns

whether the `module_name` was found in the system, either as a module or built-in in the kernel

### bd_utils_load_kernel_module ()

    gboolean
    bd_utils_load_kernel_module (const gchar *module_name,
                                 const gchar *options,
                                 GError **error);

#### Parameters

module_name | name of the kernel module to load |
options | module options. | [nullable]
error | place to store error (if any). | [out][optional]

#### Returns

whether the `module_name` was successfully loaded or not

### bd_utils_unload_kernel_module ()

    gboolean
    bd_utils_unload_kernel_module (const gchar *module_name,
                                   GError **error);

#### Parameters

module_name | name of the kernel module to unload |
error | place to store error (if any). | [out][optional]

#### Returns

whether the `module_name` was successfully unloaded or not

### bd_utils_get_linux_version ()

    BDUtilsLinuxVersion *
    bd_utils_get_linux_version (GError **error);

Retrieves version of currently running Linux kernel. Acts also as an initializer for statically cached data.

#### Parameters

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

#### Returns

Detected Linux kernel version or `NULL` in case of an error. The returned value belongs to the library, do not free.

[transfer none]

### bd_utils_check_linux_version ()

    gint
    bd_utils_check_linux_version (guint major,
                                  guint minor,
                                  guint micro);

Checks whether the currently running linux kernel version is equal or higher than the specified required `major` .`minor` .`micro` version.

#### Parameters

major | Minimal major linux kernel version. |
minor | Minimal minor linux kernel version. |
micro | Minimal micro linux kernel version. |

#### Returns

an integer less than, equal to, or greater than zero, if detected version is <, == or > than the specified `major` .`minor` .`micro` version.

### bd_utils_dbus_service_available ()

    gboolean
    bd_utils_dbus_service_available (GDBusConnection *connection,
                                     GBusType bus_type,
                                     const gchar *bus_name,
                                     const gchar *obj_prefix,
                                     GError **error);

#### Parameters

connection | existing GDBusConnection or `NULL`. | [nullable]
bus_type | bus type (system or session), ignored if `connection` is specified |
bus_name | name of the service to check (e.g. "com.redhat.lvmdbus1") |
obj_prefix | object path prefix for the service (e.g. "/com/redhat/lvmdbus1") |
error | place to store error (if any). | [out][optional]

#### Returns

whether the service was found in the system

### bd_utils_dbus_error_quark ()

    GQuark
    bd_utils_dbus_error_quark (void);

[skip]

### bd_utils_module_error_quark ()

    GQuark
    bd_utils_module_error_quark (void);

[skip]

## Types and Values

### enum BDUtilsProgStatus

#### Members

BD_UTILS_PROG_STARTED |  |
BD_UTILS_PROG_PROGRESS |  |
BD_UTILS_PROG_FINISHED |  |

### BD_UTILS_EXEC_ERROR

    #define BD_UTILS_EXEC_ERROR bd_utils_exec_error_quark ()

### enum BDUtilsExecError

#### Members

BD_UTILS_EXEC_ERROR_FAILED |  |
BD_UTILS_EXEC_ERROR_NOOUT |  |
BD_UTILS_EXEC_ERROR_INVAL_VER |  |
BD_UTILS_EXEC_ERROR_UTIL_UNAVAILABLE |  |
BD_UTILS_EXEC_ERROR_UTIL_UNKNOWN_VER |  |
BD_UTILS_EXEC_ERROR_UTIL_LOW_VER |  |
BD_UTILS_EXEC_ERROR_UTIL_CHECK_ERROR |  |
BD_UTILS_EXEC_ERROR_UTIL_FEATURE_CHECK_ERROR |  |
BD_UTILS_EXEC_ERROR_UTIL_FEATURE_UNAVAILABLE |  |

### enum BDUtilsDevUtilsError

#### Members

BD_UTILS_DEV_UTILS_ERROR_FAILED |  |

### enum BDUtilsDBusError

#### Members

BD_UTILS_DBUS_ERROR_FAIL |  |
BD_UTILS_DBUS_ERROR_NOEXIST |  |

### enum BDUtilsModuleError

#### Members

BD_UTILS_MODULE_ERROR_KMOD_INIT_FAIL |  |
BD_UTILS_MODULE_ERROR_FAIL |  |
BD_UTILS_MODULE_ERROR_NOEXIST |  |
BD_UTILS_MODULE_ERROR_MODULE_CHECK_ERROR |  |
BD_UTILS_MODULE_ERROR_INVALID_PLATFORM |  |

### BD_UTILS_DEV_UTILS_ERROR

    #define BD_UTILS_DEV_UTILS_ERROR bd_utils_dev_utils_error_quark ()

### BD_UTILS_DBUS_ERROR

    #define BD_UTILS_DBUS_ERROR bd_utils_dbus_error_quark ()

### BD_UTILS_MODULE_ERROR

    #define BD_UTILS_MODULE_ERROR bd_utils_module_error_quark ()

### BDUtilsLinuxVersion

    typedef struct {
        guint major;
        guint minor;
        guint micro;
    } BDUtilsLinuxVersion;

### BDExtraArg

    typedef struct {
        gchar *opt;
        gchar *val;
    } BDExtraArg;

See `bd_extra_arg_new()` for an example on how to construct the extra args.

#### Members

gchar *`opt`; | extra option (command line option for most functions that allow extra options to be passed, e.g. "-L" to call `mkfs.xfs -L`) |
gchar *`val`; | value for `opt` , can be an empty string or `NULL` for options without parameter |

### EXBIBYTE

    #define EXBIBYTE *1024ULL PEBIBYTE

### EiB

    #define EiB EXBIBYTE

### GIBIBYTE

    #define GIBIBYTE *1024ULL MEBIBYTE

### GiB

    #define GiB GIBIBYTE

### KIBIBYTE

    #define KIBIBYTE *1024ULL

### KiB

    #define KiB KIBIBYTE

### MEBIBYTE

    #define MEBIBYTE *1024ULL KIBIBYTE

### MiB

    #define MiB MEBIBYTE

### PEBIBYTE

    #define PEBIBYTE *1024ULL TEBIBYTE

### PiB

    #define PiB PEBIBYTE

### TEBIBYTE

    #define TEBIBYTE *1024ULL GIBIBYTE

### TiB

    #define TiB TEBIBYTE

### EB

    #define EB EXABYTE

### EXABYTE

    #define EXABYTE *1000ULL PETABYTE

### GB

    #define GB GIGABYTE

### GIGABYTE

    #define GIGABYTE *1000ULL MEGABYTE

### KB

    #define KB KILOBYTE

### KILOBYTE

    #define KILOBYTE *1000ULL

### MB

    #define MB MEGABYTE

### MEGABYTE

    #define MEGABYTE *1000ULL KILOBYTE

### PB

    #define PB PETABYTE

### PETABYTE

    #define PETABYTE *1000ULL TERABYTE

### TB

    #define TB TERABYTE

### TERABYTE

    #define TERABYTE *1000ULL GIGABYTE

### BD_UTILS_LOG_EMERG

    #define BD_UTILS_LOG_EMERG   0

### BD_UTILS_LOG_ALERT

    #define BD_UTILS_LOG_ALERT   1

### BD_UTILS_LOG_CRIT

    #define BD_UTILS_LOG_CRIT    2

### BD_UTILS_LOG_ERR

    #define BD_UTILS_LOG_ERR     3

### BD_UTILS_LOG_WARNING

    #define BD_UTILS_LOG_WARNING 4

### BD_UTILS_LOG_NOTICE

    #define BD_UTILS_LOG_NOTICE  5

### BD_UTILS_LOG_INFO

    #define BD_UTILS_LOG_INFO    6

### BD_UTILS_LOG_DEBUG

    #define BD_UTILS_LOG_DEBUG   7