Utilities: UDisks Reference Manual

## Utilities Utilities — Various utility routines |

## Functions

gchar * | udisks_decode_udev_string ()
void | udisks_safe_append_to_object_path ()
guint64 | udisks_daemon_util_block_get_size ()
gchar * | udisks_daemon_util_resolve_link ()
gchar ** | udisks_daemon_util_resolve_links ()
gboolean | udisks_daemon_util_check_authorization_sync ()
gboolean | udisks_daemon_util_get_caller_uid_sync ()
gboolean | udisks_daemon_util_get_caller_pid_sync ()
gboolean | udisks_daemon_util_setup_by_user ()
gpointer | udisks_daemon_util_dup_object ()
UDisksInhibitCookie * | udisks_daemon_util_inhibit_system_sync ()
void | udisks_daemon_util_uninhibit_system_sync ()
gchar * | udisks_daemon_util_hexdump ()
void | udisks_daemon_util_hexdump_debug ()
gboolean | udisks_daemon_util_file_set_contents ()
gboolean | udisks_daemon_util_on_user_seat ()
gchar * | udisks_daemon_util_get_free_mdraid_device ()
guint16 | udisks_ata_identify_get_word ()
void | udisks_daemon_util_trigger_uevent ()
gboolean | udisks_daemon_util_trigger_uevent_sync ()
gboolean | udisks_module_validate_name ()

## Types and Values

typedef | UDisksInhibitCookie

## Description

Various utility routines.

## Functions

### udisks_decode_udev_string ()

    gchar *
    udisks_decode_udev_string (const gchar *str,
                               const gchar *fallback_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.

#### Parameters

str | An udev-encoded string or `NULL`. |
fallback_str | String to use when `str` can't be converted to a valid UTF-8 string. |

#### 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[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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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,
                                    GError **error);

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

#### Parameters

daemon | A UDisksDaemon. |
invocation | A GDBusMethodInvocation. |
cancellable | A GCancellable or `NULL`. | [allow-none]
out_uid | Return location for resolved uid or `NULL`. | [out]
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` .

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

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

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

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

#### Parameters

daemon | A UDisksDaemon. |
object | The GDBusObject that the call is on or `NULL`. |
user | The user to check for. |

#### Returns

`TRUE` if `object` is on the same seat as one of `user` 's active sessions, `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` .

#### Parameters

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

### udisks_daemon_util_trigger_uevent ()

    void
    udisks_daemon_util_trigger_uevent (UDisksDaemon *daemon,
                                       const gchar *device_file,
                                       const gchar *sysfs_path);

Triggers a 'change' uevent in the kernel.

The `sysfs_path` takes precedence if non-NULL over a `device_file` . In case of using `device_file` any symlinks are resolved, this expects the block device has been processed by udev already.

The triggered event will bubble up from the kernel through the udev stack and will eventually be received by the udisks daemon process itself. This method does not wait for the event to be received.

#### Parameters

daemon | A UDisksDaemon. |
device_file | Block device file (/dev/xxx) or `NULL`. |
sysfs_path | Device path in /sys or `NULL`. |

### udisks_daemon_util_trigger_uevent_sync ()

    gboolean
    udisks_daemon_util_trigger_uevent_sync
                                   (UDisksDaemon *daemon,
                                    const gchar *device_file,
                                    const gchar *sysfs_path,
                                    guint timeout_seconds);

Triggers a 'change' uevent in the kernel and waits until it's received and processed by udisks.

The `sysfs_path` takes precedence if non-NULL over a `device_file` . In case of using `device_file` any symlinks are resolved, this expects the block device has been processed by udev already.

Unlike `udisks_daemon_util_trigger_uevent()` that just triggers a synthetic uevent to the kernel, this call will actually block and wait until the UDisksLinuxProvider receives the uevent, performs probing and processes the uevent further down the UDisks object stack. Upon returning from this function call the caller may assume the event has been fully processed, all D-Bus objects are updated and settled. Typically used in busy wait for a particular D-Bus interface.

Note that this uses synthetic uevent tagging and only works on linux kernel 4.13 and higher. In case an older kernel is detected this acts like the classic `udisks_daemon_util_trigger_uevent()` call and `FALSE` is returned.

#### Parameters

daemon | A UDisksDaemon. |
device_file | Block device file (/dev/xxx) or `NULL`. |
sysfs_path | Device path in /sys or `NULL`. |
timeout_seconds | Maximum time to wait for the uevent (in seconds). |

#### Returns

`TRUE` if the uevent has been successfully received, `FALSE` otherwise or when the kernel version is too old.

### udisks_module_validate_name ()

    gboolean
    udisks_module_validate_name (const gchar *module_name);

Checks the string for a valid udisks2 module name. Only alphanumeric characters along with the '-' and '_' separators are permitted.

#### Parameters

module_name | A udisks2 module name. |

#### Returns

`TRUE` if the string is a valid udisks2 module name, `FALSE` otherwise.

## Types and Values

### UDisksInhibitCookie

    typedef struct UDisksInhibitCookie UDisksInhibitCookie;

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