## 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_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 ()
void | bd_utils_log ()
gboolean | bd_utils_echo_str_to_file ()
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 ()
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 ()

## Types and Values

enum | BDUtilsProgStatus
#define | BD_UTILS_EXEC_ERROR
enum | BDUtilsExecError
enum | BDUtilsDevUtilsError
#define | BD_UTILS_DEV_UTILS_ERROR
| 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

## Includes

    #include <utils.h>

## Description

## Functions

### BDUtilsProgExtract ()

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

#### Parameters

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

#### Returns

whether the line was a progress reporting line 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). | [allow-none]

### 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. | [allow-none][array zero-terminated=1]
error | place to store error (if any). | [out]

#### 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. | [allow-none][array zero-terminated=1]
status | place to store the status. | [out]
error | place to store error (if any). | [out]

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

#### Parameters

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

#### 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. | [allow-none][array zero-terminated=1]
error | place to store error (if any). | [out]

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

#### Parameters

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

#### Returns

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

### 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 reset to default. | [allow-none][scope notified]
error | place to store error (if any). | [out]

#### 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. | [allow-none][scope notified]
error | place to store error (if any). | [out]

#### 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. | [allow-none][scope notified]
error | place to store error (if any). | [out]

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

#### 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_log ()

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

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

#### Returns

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

### 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. | [allow-none]
version_arg | argument to use with the `util` to get version info or `NULL` to use "--version". | [allow-none]
version_regexp | regexp to extract version from the version info or `NULL` if only version is printed by "$ `util` `version_arg` ". | [allow-none]
error | place to store error (if any). | [out]

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

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

### bd_extra_arg_free ()

    void
    bd_extra_arg_free (BDExtraArg *arg);

Frees `arg` .

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

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

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

#### 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. | [allow-none]
error | place to store error (if any). | [out]

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

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

#### 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`. | [allow-none]
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]

#### Returns

whether the service was found in the system

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

### BD_UTILS_DEV_UTILS_ERROR

    #define BD_UTILS_DEV_UTILS_ERROR bd_utils_dev_utils_error_quark ()

### BDExtraArg

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

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

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