Utilities

## Utilities Utilities — Various utility routines |

## Synopsis

    gchar *             udisks_decode_udev_string           (const gchar *str);
    void                udisks_safe_append_to_object_path   (GString *str,
                                                             const gchar *s);
    guint64             udisks_daemon_util_block_get_size   (GUdevDevice *device,
                                                             gboolean *out_media_available,
                                                             gboolean *out_media_change_detected);
    gchar *             udisks_daemon_util_resolve_link     (const gchar *path,
                                                             const gchar *name);
    gchar **            udisks_daemon_util_resolve_links    (const gchar *path,
                                                             const gchar *dir_name);
    gboolean            udisks_daemon_util_check_authorization_sync
                                                            (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             const gchar *action_id,
                                                             GVariant *options,
                                                             const gchar *message,
                                                             GDBusMethodInvocation *invocation);
    gboolean            udisks_daemon_util_get_caller_uid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             uid_t *out_uid,
                                                             gid_t *out_gid,
                                                             gchar **out_user_name,
                                                             GError **error);
    gboolean            udisks_daemon_util_get_caller_pid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             pid_t *out_pid,
                                                             GError **error);
    gboolean            udisks_daemon_util_setup_by_user    (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             uid_t user);
    gpointer            udisks_daemon_util_dup_object       (gpointer interface_,
                                                             GError **error);
    gchar *             udisks_daemon_util_escape           (const gchar *str);
    gchar *             udisks_daemon_util_escape_and_quote (const gchar *str);
    typedef             UDisksInhibitCookie;
    UDisksInhibitCookie * udisks_daemon_util_inhibit_system_sync
                                                            (const gchar *reason);
    void                udisks_daemon_util_uninhibit_system_sync
                                                            (UDisksInhibitCookie *cookie);
    gchar *             udisks_daemon_util_hexdump          (gconstpointer data,
                                                             gsize len);
    void                udisks_daemon_util_hexdump_debug    (gconstpointer data,
                                                             gsize len);
    gboolean            udisks_daemon_util_file_set_contents
                                                            (const gchar *filename,
                                                             const gchar *contents,
                                                             gssize contents_len,
                                                             gint mode_for_new_file,
                                                             GError **error);
    gboolean            udisks_daemon_util_on_same_seat     (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             pid_t process);
    gchar *             udisks_daemon_util_get_free_mdraid_device
                                                            (void);
    guint16             udisks_ata_identify_get_word        (const guchar *identify_data,
                                                             guint word_number);

## Description

Various utility routines.

## Details

### udisks_decode_udev_string ()

    gchar *             udisks_decode_udev_string           (const gchar *str);

Unescapes sequences like \x20 to " " and ensures the returned string is valid UTF-8.

If the string is not valid UTF-8, try as hard as possible to convert to UTF-8.

If `NULL` is passed, then `NULL` is returned.

See `udev_util_encode_string()` in libudev/libudev-util.c in the udev tree for what kinds of strings can be used.

`str` : | An udev-encoded string or `NULL`.
Returns : | A valid UTF-8 string that must be freed with `g_free()`.

### udisks_safe_append_to_object_path ()

    void                udisks_safe_append_to_object_path   (GString *str,
                                                             const gchar *s);

Appends `s` to `str` in a way such that only characters that can be used in a D-Bus object path will be used. E.g. a character not in `[A-Z][a-z][0-9]_` will be escaped as _HEX where HEX is a two-digit hexadecimal number.

Note that his mapping is not bijective - e.g. you cannot go back to the original string.

`str` : | A GString to append to.
`s` : | A UTF-8 string.

### udisks_daemon_util_block_get_size ()

    guint64             udisks_daemon_util_block_get_size   (GUdevDevice *device,
                                                             gboolean *out_media_available,
                                                             gboolean *out_media_change_detected);

Gets the size of the `device` top-level block device, checking for media in the process

`device` : | A GUdevDevice for a top-level block device.
`out_media_available` : | Return location for whether media is available or `NULL`. [out]
`out_media_change_detected` : | Return location for whether media change is detected or `NULL`. [out]
Returns : | The size of `device` or 0 if no media is available or if unknown.

### udisks_daemon_util_resolve_link ()

    gchar *             udisks_daemon_util_resolve_link     (const gchar *path,
                                                             const gchar *name);

Resolves the symlink `path`/`name`.

`path` : | A path
`name` : | Name of a symlink in `path`.
Returns : | A canonicalized absolute pathname or `NULL` if the symlink could not be resolved. Free with `g_free()`.

### udisks_daemon_util_resolve_links ()

    gchar **            udisks_daemon_util_resolve_links    (const gchar *path,
                                                             const gchar *dir_name);

Resolves all symlinks in `path`/`dir_name`. This can be used to easily walk e.g. holders or slaves of block devices.

`path` : | A path
`dir_name` : | Name of a directory in `path` holding symlinks.
Returns : | An array of canonicalized absolute pathnames. Free with `g_strfreev()`.

### udisks_daemon_util_check_authorization_sync ()

    gboolean            udisks_daemon_util_check_authorization_sync
                                                            (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             const gchar *action_id,
                                                             GVariant *options,
                                                             const gchar *message,
                                                             GDBusMethodInvocation *invocation);

Checks if the caller represented by `invocation` is authorized for the action identified by `action_id`, optionally displaying `message` if authentication is needed. Additionally, if the caller is not authorized, the appropriate error is already returned to the caller via `invocation`.

The calling thread is blocked for the duration of the authorization check which could be a very long time since it may involve presenting an authentication dialog and having a human user use it. If “auth.no_user_interaction” in `options` is `TRUE` no authentication dialog will be presented and the check is not expected to take a long time.

See Table 1, “Known polkit variables” for the variables that can be used in `message` but note that not all variables can be used in all checks. For example, any check involving a UDisksDrive or a UDisksBlock object can safely include the fragment “$(drive)” since it will always expand to the name of the drive, e.g. “INTEL SSDSA2MH080G1GC (/dev/sda1)” or the block device file e.g. “/dev/vg_lucifer/lv_root” or “/dev/sda1”. However this won't work for operations that isn't on a drive or block device, for example calls on the Manager object.

`daemon` : | A UDisksDaemon.
`object` : | The GDBusObject that the call is on or `NULL`. [allow-none]
`action_id` : | The action id to check for.
`options` : | A GVariant to check for the “auth.no_user_interaction” option or `NULL`. [allow-none]
`message` : | The message to convey (use N_).
`invocation` : | The invocation to check for.
Returns : | `TRUE` if caller is authorized, `FALSE` if not.

### udisks_daemon_util_get_caller_uid_sync ()

    gboolean            udisks_daemon_util_get_caller_uid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             uid_t *out_uid,
                                                             gid_t *out_gid,
                                                             gchar **out_user_name,
                                                             GError **error);

Gets the UNIX user id (and possibly group id and user name) of the peer represented by `invocation`.

`daemon` : | A UDisksDaemon.
`invocation` : | A GDBusMethodInvocation.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`out_uid` : | Return location for resolved uid or `NULL`. [out]
`out_gid` : | Return location for resolved gid or `NULL`. [out][allow-none]
`out_user_name` : | Return location for resolved user name or `NULL`. [out][allow-none]
`error` : | Return location for error.
Returns : | `TRUE` if the user id (and possibly group id) was obtained, `FALSE` otherwise

### udisks_daemon_util_get_caller_pid_sync ()

    gboolean            udisks_daemon_util_get_caller_pid_sync
                                                            (UDisksDaemon *daemon,
                                                             GDBusMethodInvocation *invocation,
                                                             GCancellable *cancellable,
                                                             pid_t *out_pid,
                                                             GError **error);

Gets the UNIX process id of the peer represented by `invocation`.

`daemon` : | A UDisksDaemon.
`invocation` : | A GDBusMethodInvocation.
`cancellable` : | A GCancellable or `NULL`. [allow-none]
`out_pid` : | Return location for resolved pid or `NULL`. [out]
`error` : | Return location for error.
Returns : | `TRUE` if the process id was obtained, `FALSE` otherwise

### udisks_daemon_util_setup_by_user ()

    gboolean            udisks_daemon_util_setup_by_user    (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             uid_t user);

Checks whether the device represented by `object` (if any) has been setup by `user`.

`daemon` : | A UDisksDaemon.
`object` : | The GDBusObject that the call is on or `NULL`.
`user` : | The user in question.
Returns : | `TRUE` if `object` has been set-up by `user`, `FALSE` if not.

### udisks_daemon_util_dup_object ()

    gpointer            udisks_daemon_util_dup_object       (gpointer interface_,
                                                             GError **error);

Gets the enclosing UDisksObject for `interface`, if any.

`interface_` : | A GDBusInterface-derived instance. [type GDBusInterface]
`error` : | `NULL`, or an unset GError to set if the return value is `NULL`.
Returns : | Either `NULL` or a UDisksObject-derived instance that must be released with `g_object_unref()`. [transfer full][type UDisksObject]

### udisks_daemon_util_escape ()

    gchar *             udisks_daemon_util_escape           (const gchar *str);

Escapes double-quotes (") and back-slashes (\) in a string using back-slash (\).

`str` : | The string to escape.
Returns : | The escaped string. Free with `g_free()`.

### udisks_daemon_util_escape_and_quote ()

    gchar *             udisks_daemon_util_escape_and_quote (const gchar *str);

Like `udisks_daemon_util_escape()` but also wraps the result in double-quotes.

`str` : | The string to escape.
Returns : | The double-quoted and escaped string. Free with `g_free()`.

### UDisksInhibitCookie

    typedef struct UDisksInhibitCookie UDisksInhibitCookie;

Opaque data structure used in `udisks_daemon_util_inhibit_system_sync()` and `udisks_daemon_util_uninhibit_system_sync()`.

### udisks_daemon_util_inhibit_system_sync ()

    UDisksInhibitCookie * udisks_daemon_util_inhibit_system_sync
                                                            (const gchar *reason);

Tries to inhibit the system.

Right now only systemd inhibitors are supported but other inhibitors can be added in the future.

`reason` : | A human readable explanation of why the system is being inhibited.
Returns : | A cookie that can be used with `udisks_daemon_util_uninhibit_system_sync()`.

### udisks_daemon_util_uninhibit_system_sync ()

    void                udisks_daemon_util_uninhibit_system_sync
                                                            (UDisksInhibitCookie *cookie);

Does nothing if `cookie` is `NULL`, otherwise uninhibits.

`cookie` : | `NULL` or a cookie obtained from `udisks_daemon_util_inhibit_system_sync()`.

### udisks_daemon_util_hexdump ()

    gchar *             udisks_daemon_util_hexdump          (gconstpointer data,
                                                             gsize len);

Utility function to generate a hexadecimal representation of `len` bytes of `data`.

`data` : | Pointer to data.
`len` : | Length of data.
Returns : | A multi-line string. Free with `g_free()` when done using it.

### udisks_daemon_util_hexdump_debug ()

    void                udisks_daemon_util_hexdump_debug    (gconstpointer data,
                                                             gsize len);

Utility function to dumps the hexadecimal representation of `len` bytes of `data` generated with `udisks_daemon_util_hexdump()` using `udisks_debug()`.

`data` : | Pointer to data.
`len` : | Length of data.

### udisks_daemon_util_file_set_contents ()

    gboolean            udisks_daemon_util_file_set_contents
                                                            (const gchar *filename,
                                                             const gchar *contents,
                                                             gssize contents_len,
                                                             gint mode_for_new_file,
                                                             GError **error);

Like `g_file_set_contents()` but preserves the mode of the file if it already exists and sets it to `mode_for_new_file` otherwise.

`filename` : | Name of a file to write `contents` to, in the GLib file name encoding. [type filename]
`contents` : | String to write to the file. [array length=length][element-type guint8]
`contents_len` : | Length of `contents`, or -1 if `contents` is a NUL-terminated string.
`mode_for_new_file` : | Mode for new file.
`error` : | Return location for a GError, or `NULL`.
Returns : | `TRUE` on success, `FALSE` if an error occurred

### udisks_daemon_util_on_same_seat ()

    gboolean            udisks_daemon_util_on_same_seat     (UDisksDaemon *daemon,
                                                             UDisksObject *object,
                                                             pid_t process);

Checks whether the device represented by `object` (if any) is plugged into a seat where the caller represented by `process` is logged in.

This works if `object` is a drive or a block object.

`daemon` : | A UDisksDaemon.
`object` : | The GDBusObject that the call is on or `NULL`.
`process` : | The process to check for.
Returns : | `TRUE` if `object` and `process` is on the same seat, `FALSE` otherwise.

### udisks_daemon_util_get_free_mdraid_device ()

    gchar *             udisks_daemon_util_get_free_mdraid_device
                                                            (void);

Gets a free MD RAID device.

Returns : | A string of the form "/dev/mdNNN" that should be freed with `g_free()` or `NULL` if no free device is available.

### udisks_ata_identify_get_word ()

    guint16             udisks_ata_identify_get_word        (const guchar *identify_data,
                                                             guint word_number);

Gets a “word” from position `word_number` from `identify_data`.

`identify_data` : | A 512-byte array containing ATA IDENTIFY or ATA IDENTIFY PACKET DEVICE data or `NULL`. [allow-none]
`word_number` : | The word number to get - must be less than 256.
Returns : | The word at the specified position or 0 if `identify_data` is `NULL`.