Utils

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

Functions

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

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).

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

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.

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

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.

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

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