Utils

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

Synopsis

#include <utils.h>

gboolean            (*BDUtilsProgExtract)               (const gchar *line,
                                                         guint8 *completion);
void                (*BDUtilsProgFunc)                  (guint64 task_id,
                                                         BDUtilsProgStatus status,
                                                         guint8 completion,
                                                         gchar *msg);
enum                BDUtilsProgStatus;
void                (*BDUtilsLogFunc)                   (gint level,
                                                         const gchar *msg);
GQuark              bd_utils_exec_error_quark           (void);
#define             BD_UTILS_EXEC_ERROR
enum                BDUtilsExecError;
gboolean            bd_utils_exec_and_report_error      (const gchar **argv,
                                                         const BDExtraArg **extra,
                                                         GError **error);
gboolean            bd_utils_exec_and_report_status_error
                                                        (const gchar **argv,
                                                         const BDExtraArg **extra,
                                                         gint *status,
                                                         GError **error);
gboolean            bd_utils_exec_and_capture_output    (const gchar **argv,
                                                         const BDExtraArg **extra,
                                                         gchar **output,
                                                         GError **error);
gboolean            bd_utils_exec_and_report_error_no_progress
                                                        (const gchar **argv,
                                                         const BDExtraArg **extra,
                                                         GError **error);
gboolean            bd_utils_exec_and_report_progress   (const gchar **argv,
                                                         const BDExtraArg **extra,
                                                         BDUtilsProgExtract prog_extract,
                                                         gint *proc_status,
                                                         GError **error);
gboolean            bd_utils_init_logging               (BDUtilsLogFunc new_log_func,
                                                         GError **error);
gboolean            bd_utils_init_prog_reporting        (BDUtilsProgFunc new_prog_func,
                                                         GError **error);
void                bd_utils_report_finished            (guint64 task_id,
                                                         gchar *msg);
void                bd_utils_report_progress            (guint64 task_id,
                                                         guint64 completion,
                                                         gchar *msg);
guint64             bd_utils_report_started             (gchar *msg);
gboolean            bd_utils_echo_str_to_file           (const gchar *str,
                                                         const gchar *file_path,
                                                         GError **error);
gboolean            bd_utils_check_util_version         (const gchar *util,
                                                         const gchar *version,
                                                         const gchar *version_arg,
                                                         const gchar *version_regexp,
                                                         GError **error);
gint                bd_utils_version_cmp                (const gchar *ver_string1,
                                                         const gchar *ver_string2,
                                                         GError **error);
                    BDExtraArg;
BDExtraArg *        bd_extra_arg_new                    (const gchar *opt,
                                                         const gchar *val);
BDExtraArg *        bd_extra_arg_copy                   (BDExtraArg *arg);
void                bd_extra_arg_free                   (BDExtraArg *arg);
GType               bd_extra_arg_get_type               ();
gchar *             bd_utils_resolve_device             (const gchar *dev_spec,
                                                         GError **error);
gchar **            bd_utils_get_device_symlinks        (const gchar *dev_spec,
                                                         GError **error);
#define             EXBIBYTE
#define             EiB
#define             GIBIBYTE
#define             GiB
#define             KIBIBYTE
#define             KiB
#define             MEBIBYTE
#define             MiB
#define             PEBIBYTE
#define             PiB
#define             TEBIBYTE
#define             TiB

Description

Details

BDUtilsProgExtract ()

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

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

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]

enum BDUtilsProgStatus

typedef enum {
    BD_UTILS_PROG_STARTED,
    BD_UTILS_PROG_PROGRESS,
    BD_UTILS_PROG_FINISHED,
} BDUtilsProgStatus;

BD_UTILS_PROG_STARTED

BD_UTILS_PROG_PROGRESS

BD_UTILS_PROG_FINISHED

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.

level :

 log level (as understood by syslog(3))

msg :

 log message

bd_utils_exec_error_quark ()

GQuark              bd_utils_exec_error_quark           (void);

BD_UTILS_EXEC_ERROR

#define BD_UTILS_EXEC_ERROR bd_utils_exec_error_quark ()

enum BDUtilsExecError

typedef enum {
    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,
} BDUtilsExecError;

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

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

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

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

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

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

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

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

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

void                bd_utils_report_finished            (guint64 task_id,
                                                         gchar *msg);

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

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

msg :

 message describing the started task/action

Returns :

 ID of the started task/action

bd_utils_echo_str_to_file ()

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

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

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

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[.Z2[.Z3...[-R]]]]] where all components are natural numbers!**

BDExtraArg

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

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

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
5
 
<!-- language="C" -->
BDExtraArg label_arg = {"-L", "label"};
const BDExtraArg *extra_args[2] = {&label_arg, NULL};

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

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

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

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]

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
Generated by GTK-Doc V1.19