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 ()
gchar * | udisks_daemon_util_escape ()
gchar * | udisks_daemon_util_escape_and_quote ()
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 ()

## Types and Values

typedef | UDisksInhibitCookie

## Description

Various utility routines.

## Functions

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

#### Parameters

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[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_escape ()

    gchar *
    udisks_daemon_util_escape (const gchar *str);

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

#### Parameters

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.

#### Parameters

str | The string to escape. |

#### Returns

The double-quoted and escaped string. Free with `g_free()`.

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

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