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

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

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


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

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

   

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