UDisksState: UDisks Reference Manual

UDisksState

UDisksState — Object used for recording state and cleaning up

Functions

UDisksState *	udisks_state_new ()
void	udisks_state_start_cleanup ()
void	udisks_state_stop_cleanup ()
void	udisks_state_check ()
void	udisks_state_check_block ()
UDisksDaemon *	udisks_state_get_daemon ()
void	udisks_state_add_mounted_fs ()
gchar *	udisks_state_find_mounted_fs ()
void	udisks_state_add_unlocked_crypto_dev ()
dev_t	udisks_state_find_unlocked_crypto_dev ()
void	udisks_state_add_loop ()
gboolean	udisks_state_has_loop ()
void	udisks_state_add_mdraid ()
gboolean	udisks_state_has_mdraid ()
void	udisks_state_add_module ()
void	udisks_state_clear_modules ()
gchar **	udisks_state_get_modules ()

Properties

UDisksDaemon *

daemon

Read / Write / Construct Only

Types and Values

UDisksState

Object Hierarchy

    GObject
    ╰── UDisksState

Description

This type is used for recording actions done by users and cleaning up when devices set up via the udisks interfaces are removed while still in use - for example, a USB stick being yanked.

The following files are used:

Table 3. Persistent information and state

File	Usage
`/run/udisks2/mounted-fs`	A serialized 'a{sa{sv}}' GVariant mapping from the mount point (e.g. `/media/EOS_DIGITAL`) into a set of details. Known details include `block-device` (of type 't') that is the dev_t for the mounted device, `mounted-by-uid` (of type 'u') that is the uid_t of the user who mounted the device, and `fstab-mount` (of type 'b') that is `TRUE` if the device was mounted via an entry in /etc/fstab. Contains only non-persistent mount points. This state file is typically stored on a non-persistent filesystem.
`/var/lib/udisks2/mounted-fs-persistent`	Similar in contents and data structure to `/run/udisks2/mounted-fs` except that only persistent mount points are stored there. This state file is typically stored on a persistent filesystem.
`/run/udisks2/unlocked-crypto-dev`	A serialized 'a{ta{sv}}' GVariant mapping from the dev_t of the clear-text device (e.g. `/dev/dm-0`) into a set of details. Known details include `crypto-device` (of type 't') that is the dev_t for the crypto-text device, `dm-uuid` (of type 'ay') that is the device mapper UUID for the clear-text device and `unlocked-by-uid` (of type 'u') that is the uid_t of the user who unlocked the device.
`/run/udisks2/loop`	A serialized 'a{sa{sv}}' GVariant mapping from the loop device name (e.g. `/dev/loop0`) into a set of details. Known details include `backing-file` (of type 'ay') for the name of the backing file and `backing-file-device` (of type 't') for the dev_t for of the device holding the backing file (or 0 if unknown) and `setup-by-uid` (of type 'u') that is the uid_t of the user who set up the loop device.
`/run/udisks2/mdraid`	A serialized 'a{ta{sv}}' GVariant mapping from the dev_t of the raid device (e.g. `/dev/md127`) into a set of details. Known details include `started-by-uid` (of type 'u') that is the uid_t of the user who started the array.
`/run/udisks2/modules`	A serialized 'a{sa{sv}}' GVariant mapping from the module name (e.g. `lvm2`) into a set of details. No details are defined at this point, reserved for future use. Contains currently active module names primarily for the purpose of crash recovery upon next daemon start.

Cleaning up is implemented by running a thread (to ensure that actions are serialized) that checks all data in the files mentioned above and cleans up the entry in question by e.g. unmounting a filesystem, removing a mount point or tearing down a device-mapper device when needed. The clean-up thread itself needs to be manually kicked using e.g. udisks_state_check() from suitable places in the UDisksDaemon and UDisksProvider implementations.

Since cleaning up is only necessary when a device has been removed without having been properly stopped or shut down, the fact that it was cleaned up is logged to ensure that the information is brought to the attention of the system administrator.

Functions

udisks_state_new ()

UDisksState *
udisks_state_new (UDisksDaemon *daemon);

Creates a new UDisksState object.

Parameters

daemon

A UDisksDaemon.

Returns

A UDisksState that should be freed with g_object_unref().

udisks_state_start_cleanup ()

void
udisks_state_start_cleanup (UDisksState *state);

Starts the clean-up thread.

The clean-up thread will hold a reference to state for as long as it's running - use udisks_state_stop_cleanup() to stop it.

Parameters

state

A UDisksState.

udisks_state_stop_cleanup ()

void
udisks_state_stop_cleanup (UDisksState *state);

Stops the clean-up thread. Blocks the calling thread until it has stopped.

Parameters

state

A UDisksState.

udisks_state_check ()

void
udisks_state_check (UDisksState *state);

Causes the clean-up thread for state to check if anything should be cleaned up.

This can be called from any thread and will not block the calling thread.

Parameters

state

A UDisksState.

udisks_state_check_block ()

void
udisks_state_check_block (UDisksState *state,
                          dev_t block_device);

Performs cleanup of a mounted filesystem over a single block device. In case the clean-up thread is busy, waits until the current iteration is finished.

This can be called from any thread and will block the calling thread until cleanup is finished. Note that this ignores UDisksLinuxBlockObject cleanup lock that is supposed to be held by the caller.

Parameters

state	A UDisksState.
block_device	Device number of the block device to check.

udisks_state_get_daemon ()

UDisksDaemon *
udisks_state_get_daemon (UDisksState *state);

Gets the daemon used by state .

Parameters

state

A UDisksState.

Returns

A UDisksDaemon. Do not free, the object is owned by state .

udisks_state_add_mounted_fs ()

void
udisks_state_add_mounted_fs (UDisksState *state,
                             const gchar *mount_point,
                             dev_t block_device,
                             uid_t uid,
                             gboolean fstab_mount,
                             gboolean persistent);

Adds a new entry to the /run/udisks2/mounted-fs file.

Parameters

state	A UDisksState.
block_device	The block device.
mount_point	The mount point.
uid	The user id of the process requesting the device to be mounted.
fstab_mount	`TRUE` if the device was mounted via /etc/fstab.
persistent	`TRUE` if the mount point is on a persistent filesystem.

udisks_state_find_mounted_fs ()

gchar *
udisks_state_find_mounted_fs (UDisksState *state,
                              dev_t block_device,
                              uid_t *out_uid,
                              gboolean *out_fstab_mount);

Gets the mount point for block_device , if it exists in the /run/udisks2/mounted-fs file.

Parameters

state	A UDisksState.
block_device	The block device.
out_uid	Return location for the user id who mounted the device or `NULL`.
out_fstab_mount	Return location for whether the device was a fstab mount or `NULL`.

Returns

The mount point for block_device or NULL if not found.

udisks_state_add_unlocked_crypto_dev ()

void
udisks_state_add_unlocked_crypto_dev (UDisksState *state,
                                      dev_t cleartext_device,
                                      dev_t crypto_device,
                                      const gchar *dm_uuid,
                                      uid_t uid);

Adds a new entry to the /run/udisks2/unlocked-crypto-dev file.

Parameters

state	A UDisksState.
cleartext_device	The clear-text device.
crypto_device	The crypto device.
dm_uuid	The UUID of the unlocked dm device.
uid	The user id of the process requesting the device to be unlocked.

udisks_state_find_unlocked_crypto_dev ()

dev_t
udisks_state_find_unlocked_crypto_dev (UDisksState *state,
                                       dev_t crypto_device,
                                       uid_t *out_uid);

Gets the clear-text device for crypto_device , if it exists in the /run/udisks2/unlocked-crypto-dev file.

Parameters

state	A UDisksState.
crypto_device	The block device.
out_uid	Return location for the user id who mounted the device or `NULL`.

Returns

The cleartext device for crypto_device or 0 if not found.

udisks_state_add_loop ()

void
udisks_state_add_loop (UDisksState *state,
                       const gchar *device_file,
                       const gchar *backing_file,
                       dev_t backing_file_device,
                       uid_t uid);

Adds a new entry to the /run/udisks2/loop file.

Parameters

state	A UDisksState.
device_file	The loop device file.
backing_file	The backing file.
backing_file_device	The dev_t of the backing file or 0 if unknown.
uid	The user id of the process requesting the loop device.

udisks_state_has_loop ()

gboolean
udisks_state_has_loop (UDisksState *state,
                       const gchar *device_file,
                       uid_t *out_uid);

Checks if device_file is set up via udisks.

Parameters

state	A UDisksState
device_file	A loop device file.
out_uid	Return location for the user id who setup the loop device or `NULL`.

Returns

TRUE if set up via udisks, otherwise FALSE or if error is set.

udisks_state_add_mdraid ()

void
udisks_state_add_mdraid (UDisksState *state,
                         dev_t raid_device,
                         uid_t uid);

Adds a new entry to the /run/udisks2/mdraid file.

Parameters

state	A UDisksState.
raid_device	The dev_t for the RAID device.
uid	The user id of the process requesting the loop device.

udisks_state_has_mdraid ()

gboolean
udisks_state_has_mdraid (UDisksState *state,
                         dev_t raid_device,
                         uid_t *out_uid);

Checks if raid_device is set up via udisks.

Parameters

state	A UDisksState
raid_device	A dev_t for the RAID device.
out_uid	Return location for the user id who setup the loop device or `NULL`.

Returns

TRUE if set up via udisks, otherwise FALSE or if error is set.

udisks_state_add_module ()

void
udisks_state_add_module (UDisksState *state,
                         const gchar *module_name);

Adds a new entry to the /run/udisks2/modules file. The module_name string should be the one returned by udisks_module_get_name().

Parameters

state	A UDisksState.
module_name	The UDisksModule name.

udisks_state_clear_modules ()

void
udisks_state_clear_modules (UDisksState *state);

Removes all entries from the /run/udisks2/modules state file.

Parameters

state

A UDisksState.

udisks_state_get_modules ()

gchar **
udisks_state_get_modules (UDisksState *state);

Retrieves list of modules recorded in the /run/udisks2/modules state file.

Parameters

state

A UDisksState

Returns

A list of module names. Free with g_strfreev().

[transfer full][array zero-terminated=1]

Types and Values

UDisksState

typedef struct _UDisksState UDisksState;

The UDisksState structure contains only private data and should only be accessed using the provided API.

Property Details

The `“daemon”` property

  “daemon”                   UDisksDaemon *

The UDisksDaemon object.

Owner: UDisksState

Flags: Read / Write / Construct Only

UDisksState

Functions

Properties

Types and Values

Object Hierarchy

Description

Functions

udisks_state_new ()

Parameters

Returns

udisks_state_start_cleanup ()

Parameters

udisks_state_stop_cleanup ()

Parameters

udisks_state_check ()

Parameters

udisks_state_check_block ()

Parameters

udisks_state_get_daemon ()

Parameters

Returns

udisks_state_add_mounted_fs ()

Parameters

udisks_state_find_mounted_fs ()

Parameters

Returns

udisks_state_add_unlocked_crypto_dev ()

Parameters

udisks_state_find_unlocked_crypto_dev ()

Parameters

Returns

udisks_state_add_loop ()

Parameters

udisks_state_has_loop ()

Parameters

Returns

udisks_state_add_mdraid ()

Parameters

udisks_state_has_mdraid ()

Parameters

Returns

udisks_state_add_module ()

Parameters

udisks_state_clear_modules ()

Parameters

udisks_state_get_modules ()

Parameters

Returns

Types and Values

UDisksState

Property Details

The “daemon” property

The `“daemon”` property