Utils: libblockdev Reference Manual

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

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

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