![]() |
![]() |
![]() |
UDisks Reference Manual | ![]() |
---|
udisksudisks — Introduction to udisks |
udisks provides interfaces to enumerate and perform operations
on storage devices. Any application (including unprivileged
ones) can access the
udisksd(8)
daemon via the name org.freedesktop.UDisks2
on the system message bus. In addition to the D-Bus API, a
library, libudisks2
is also provided. This
library can be used from C/C++ and any high-level language with
GObjectIntrospection
support such as Javascript and Python.
Except for providing a list of devices, support for udev properties as well as routines used to present the devices to the end user, udisks, as a system-level component, is not involved with what a desktop user interface shows the user. For GNOME see these GVfs notes about what is shown in the desktop user interface and how to influence it.
By default, logged-in users in active log-in sessions are permitted to perform operations (for example, mounting, unlocking or modifying) on devices attached to the seat their session is on. Access-control is fine-grained and based on polkit(8), see the “Authorization Checks” chapter in the udisks documentation for more information (available online here).
Note that the x-udisks-auth
option can be
used in the /etc/fstab
and
/etc/crypttab
files to specify that
additional authorization is required to mount resp. unlock the
device (typically requiring the user to authenticate as an
administrator).
udisks relies on recent versions of udev(7) and the Linux kernel. Influential device properties in the udev database include:
|
If set, this overrides the value of the HintSystem property. |
|
If set, this overrides the value of the HintIgnore property. |
|
If set, this overrides the value of the HintAuto property. |
|
The name to use for the device when presenting it in an user interface. This corresponds to the HintName property. |
|
The icon to use for the device when presenting it in an user interface. If set, the name must adhere to the freedesktop.org icon theme specification. This corresponds to the HintIconName property. |
|
The physical seat the device is attached to. If unset or set to the empty string, “seat0” (the first seat) is assumed. |
udisks guarantees a stable D-Bus API within the same major
version and this guarantee also extends to the client-side
library libudisks2
. Additionally, several
major versions of udisks can be installed and operate at the
same time although interoperability may be limited - for
example, a device mounted using the udisks N.x API may require
additional authorization if attempting to unmount it through the
the (N-1).x API.
The udisks developers do not anticipate breaking API but does reserve the right to do so and if it happens, promises to bump the major version and ensure the new major version of udisks is parallel-installable with any older major version. However, note that programs, man pages and other artifacts may change name (for example, adopt a “2” suffix) to make room for the next major version. Therefore, applications can not rely on tools like e.g. udisksctl(1) to be available. Additionally, there is no guarantee that the options, command-line switches etc. of command-line tools or similar will remain stable.
Instead, applications should only use the D-Bus API, the
libudisks2
library or tools such as
dbus-send(1)
or
gdbus(1)
to interact with
udisksd(8).
The intended audience of udisks include operating system developers working on the higher-level parts of the operating system, for example the desktop shell (such as GNOME) and disk management applications (e.g. GNOME's Disks application). Software on this level typically depend on a specific (major) version of udisks and may even have support for previous versions of udisks or alternative interfaces performing the same role as udisks.
While udisks indeed provides a stable API and a clear upgrade path, it may not be an appropriate dependency for third party applications. For example, if the operating system switches to udisks version N.x and an application is still using the udisks (N-1).x API, the application will not work unless udisks (N-1).x is installed. While this situation is still workable (since both udisks N.x and udisks (N-1).x can be installed) it may not be desirable to ask the user to install the old version - in fact, the operating system vendor may not even provide a packaged version of the old version. Hence, if an application does not want to tie itself to a specific version of the operating system, it should not use udisks.
Viable alternatives to udisks are APIs that are guaranteed to be around for longer time-frames, including:
Low-level APIs and commands such as e.g. sysfs, libudev, /proc/self/mountinfo and util-linux.
High-level APIs such as GVolumeMonitor.
In particular, for desktop applications it is a much better idea to use something like GVolumeMonitor since it will make the application show the same devices as the desktop shell (e.g. file manager, file chooser and so on) is showing.
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at http://bugs.freedesktop.org/enter_bug.cgi?product=udisks.