Top | ![]() |
![]() |
![]() |
![]() |
AddConfigurationItem (IN (sa{sv}) item, IN a{sv} options); RemoveConfigurationItem (IN (sa{sv}) item, IN a{sv} options); UpdateConfigurationItem (IN (sa{sv}) old_item, IN (sa{sv}) new_item, IN a{sv} options); GetSecretConfiguration (IN a{sv} options, OUT a(sa{sv}) configuration); Format (IN s type, IN a{sv} options); OpenForBackup (IN a{sv} options, OUT h fd); OpenForRestore (IN a{sv} options, OUT h fd); OpenForBenchmark (IN a{sv} options, OUT h fd); OpenDevice (IN s mode, IN a{sv} options, OUT h fd); Rescan (IN a{sv} options);
Device readable ay PreferredDevice readable ay Symlinks readable aay DeviceNumber readable t Id readable s Size readable t ReadOnly readable b Drive readable o MDRaid readable o MDRaidMember readable o IdUsage readable s IdType readable s IdVersion readable s IdLabel readable s IdUUID readable s Configuration readable a(sa{sv}) CryptoBackingDevice readable o HintPartitionable readable b HintSystem readable b HintIgnore readable b HintAuto readable b HintName readable s HintIconName readable s HintSymbolicIconName readable s UserspaceMountOptions readable as
This interface represents a block device.
This should not be confused with the org.freedesktop.UDisks2.Drive interface that is used to represent disk drives. For example, the org.freedesktop.UDisks2.Block interface is also used for block devices that do not correspond to drives at all (e.g. Loop Devices).
AddConfigurationItem (IN (sa{sv}) item, IN a{sv} options);
Adds a new configuration item.
See the "Configuration" property for details about valid configuration items.
Some fields can be omitted and will then receive default values. This is useful when passing configuration items to Format, for example, because the proper values are not known before the formatting is done.
If 'fsname' is omitted in a 'fstab' entry, or 'device' is omitted in a 'crypttab' entry, it defaults to "UUID=..." when the block device has a filesystem UUID, or to the name of the device in the filesystem..
If 'name' is omitted in a 'crypttab' entry, it defaults to "luks-<UUID>".
If 'passphrase-path' is omitted, it defaults to "/etc/luks-keys/<NAME>".
If 'track-parents' is set to true in item
, then the 'opts'
and 'options' fields will be augmented with "x-parent"
elements, as appropriate. This will make item
appear in the
ChildConfiguration properties, and will allow the 'tear-down'
option of Format, DeletePartition, and other methods to remove
this item reliably.
|
The configuration item to add. |
|
Options (currently unused except for standard options). |
RemoveConfigurationItem (IN (sa{sv}) item, IN a{sv} options);
Removes an existing configuration item.
See the "Configuration" property for details about valid configuration items.
|
The configuration item to remove. |
|
Options (currently unused except for standard options). |
UpdateConfigurationItem (IN (sa{sv}) old_item, IN (sa{sv}) new_item, IN a{sv} options);
Removes a configuration item and adds a new one. This is
equivalent to calling
RemoveConfigurationItem()
followed by
AddConfigurationItem()
with the change that only one PolicyKit check is made
and that new_item
can be validated against old_item
.
See the "Configuration" property for details about valid configuration items.
|
The configuration item to remove. |
|
The configuration item to add. Must be of the same type as |
|
Options (currently unused except for standard options). |
GetSecretConfiguration (IN a{sv} options, OUT a(sa{sv}) configuration);
Returns the same value as in the "Configuration" property but without secret information filtered out.
|
Options (currently unused except for standard options). |
|
The resulting configuration. |
Format (IN s type, IN a{sv} options);
Formats the device with a file system, partition table or other well-known content.
Known values for type
includes empty
(to
just zero out areas of the device known to host file system
signatures) and swap
(Linux swap space)
and most file systems supported by the mkfs(8)
program through its -t
option.
Known partition table formats includes
dos
and gpt
.
If type
supports it, you can specify a label with the
label
option in the options
parameter;
however, note that this may not be supported on all file
systems and, if supported, the maximum allowed length may
vary.
If the file system in question supports owners and the option
take-ownership
is set to TRUE
then the
root directory of the created file system will be owned by the
caller of this method.
If the option encrypt.passphrase
is
given then a LUKS device is created with the given passphrase
and the file system is created on the unlocked device. The
unlocked device will be left open. This parameter can be used
to supply the binary contents of an arbitrary keyfile by passing
a value of type “ay”.
Option encrypt.type
can be used to
specify encryption "technology" that will be used. Currently
only “luks1” and “luks2” are supported.
If the option erase
is used then the
underlying device will be erased. Valid values include
“zero” to write zeroes over the entire device
before formatting, “ata-secure-erase” to perform
a secure erase or “ata-secure-erase-enhanced” to
perform an enhanced secure erase.
If the option update-partition-type
is
set to TRUE
and the object in question is a partition, then
its type (cf. the "Type"
property) will be set to the natural
partition type matching type
, if any. For example, if
formatting a GPT partition with a FAT filesystem, the
“Microsoft Basic Data” partition type will be
chosen; similar, if formatting a DOS partition with a Ext4
filesystem then partition type 0x83 is chosen.
If the option no-block
is set to TRUE
then the method returns just before the actual formatting
takes place but after authorization and other checks are
done. This is useful for applications that want to format
several devices in parallel.
If the option dry-run-first
is set to
TRUE
then a dry run of the formatting command is performed
first, if Udisks knows how to do that. The idea is that
this allows a deeper check of the parameters even when
no-block
is TRUE
.
If the option no-discard
is set to
TRUE
then Udisks tells the formatting utility not to issue
BLKDISCARD ioctls.
If the option config-items
is set, it
should be an array of configuration items suitable for
org.freedesktop.UDisks2.Block.AddConfigurationItem. They will
all be added after the formatting is done.
If the option tear-down
is set to
TRUE
, then the block device and all its children will be
cleaned up before formatting. This cleanup consists of
removing entries from /etc/fstab and /etc/crypttab, and
locking of encrypted block devices. Entries in /etc/fstab and
/etc/crypttab that have been created with the 'track-parents'
options to AddConfigurationItem will be removed even if their
block device is currently unavailable.
|
The type of file system, partition table or other content to format the device with. |
|
Options - known options (in addition to standard options) includes |
OpenForBackup (IN a{sv} options, OUT h fd);
Gets a read-only file descriptor for the device intended for a byte-by-byte imaging of the device. This can only be done if the device is not already in use.
This method is deprecated since 2.7.3.
Use OpenDevice() with O_EXCL
and O_CLOEXEC
flags instead.
|
Options (currently unused except for standard options). |
|
An index for the returned file descriptor. |
OpenForRestore (IN a{sv} options, OUT h fd);
Gets a writable file descriptor for the device intended for a byte-by-byte restore of a disk image onto the device. This can only be done if the device is not already in use.
This method is deprecated since 2.7.3.
Use OpenDevice() with O_EXCL
,
O_SYNC
and O_CLOEXEC
flags instead.
|
Options (currently unused except for standard options). |
|
An index for the returned file descriptor. |
OpenForBenchmark (IN a{sv} options, OUT h fd);
Gets a file descriptor for the device that is suitable to be
used for benchmarking the device (transfer rate, access time
etc.). Note that the file descriptor may be opened with the
O_DIRECT
and O_SYNC
flags so care must be taken to only perform block-aligned I/O.
If the writable
in options
is TRUE
then the returned file descriptor will be writable. This only
works if the device is not already in use.
This method is deprecated since 2.7.3.
Use OpenDevice() with O_DIRECT
,
O_SYNC
and O_CLOEXEC
flags instead.
|
Options (currently unused except for standard options). |
|
An index for the returned file descriptor. |
OpenDevice (IN s mode, IN a{sv} options, OUT h fd);
Option flags
can be used to specify additional flags.
See man 2 open
for list of supported flags.
O_RDONLY
, O_WRONLY
and
O_RDWR
are not allowed, use mode
instead.
Gets a file descriptor for the device.
|
Mode: "r" for read-only, "w" for write-only or "rw" for read-write |
|
Options - known options (in addition to standard options) includes |
|
An index for the returned file descriptor. |
Since 2.7.3
Rescan (IN a{sv} options);
Request that the kernel and core OS rescans the contents of
the device and update their state to reflect this (including
things such as the /dev/disk/
hierarchy
of symlinks). This includes requesting that the kernel
re-reads the partition table, if appropriate.
This is usually not needed since the OS automatically does this when the last process with a writable file descriptor for the device closes it.
|
Options (currently unused except for standard options). |
Device readable ay
The special device file for the block device e.g. /dev/sda2
.
PreferredDevice readable ay
The special device file to present in the UI instead of the value of the "Device" property.
For example this could be
e.g. /dev/mapper/mpathk
for a multipath
device with special device file /dev/dm-9
.
Symlinks readable aay
Known symlinks in /dev
that points to
the device file in the
"Device" property.
For example, this array could include symlinks such as
/dev/disk/by-id/ata-INTEL_SSDSA2MH080G1GC_CVEM842101HD080DGN
and
/dev/disk/by-id/wwn-0x5001517387d61905
.
Id readable s
A unique and persistent identifier for the device or blank if no such identifier is available.
For devices with fixed media, this identifier is derived from vital product data / UUIDs / serial numbers of the drive or construct (e.g. LVM or MD-RAID) the block device is part of. For devices with removable media, this identifier is derived from the medium currently inserted.
This identifier is guaranteed to not include the slash character '/' (U+002F SOLIDUS) which means it can be used as a filename.
Examples: “by-id-ata-INTEL_SSDSA2MH080G1GC_CVEM842101HD080DGN”, “by-id-ata-ST1000LM024_HN-M101MBB_S2TBJA0C230233-part3”, “by-id-usb-Kingston_DataTraveler_2.0_0013729940C4F9A166250D3E-0:0”, “by-id-dm-name-luks-6d81fe85-26b1-4f8b-b834-405454c1cd46”, “by-id-dm-name-vg_thinkpad-lv_swap”, “by-label-HARRY_POTTER_SORCERERS_STONE-”, “by-uuid-D22D-08B8”.
Since 2.0.0
ReadOnly readable b
If TRUE
, the device can not be written to, only read from.
Drive readable o
The org.freedesktop.UDisks2.Drive object that the block device belongs to, or '/' if no such object exists.
MDRaid readable o
If the block device is a running MD-RAID array, this is set to the org.freedesktop.UDisks2.MDRaid object that it correspond to. Is '/' if no such object exists.
Since 2.0.0
MDRaidMember readable o
If the block device is a member of a MD-RAID array, this is set to the org.freedesktop.UDisks2.MDRaid object that it correspond to. Is '/' if no such object exists.
Since 2.0.0
IdUsage readable s
A result of probing for signatures on the block device. Known values include:
filesystem |
Used for mountable filesystems |
crypto |
Used for e.g. LUKS devices |
raid |
Used for e.g. RAID members and LVM PVs |
other |
Something else was detected. |
If blank, no known signature was detected. This doesn't necessarily mean the device contains no structured data; it only means that no signature known to the probing code was detected.
Applications should not rely on the value in this or the "IdType" property - instead, applications should check for whether the object in question implements interfaces such as e.g. org.freedesktop.UDisks2.Filesystem, org.freedesktop.UDisks2.Swapspace or org.freedesktop.UDisks2.Encrypted.
IdType readable s
This property contains more information about the result of probing the block device. Its value depends of the value the "IdUsage" property:
filesystem |
The mountable file system that was detected (e.g. |
crypto |
Encrypted data. Known values include |
raid |
RAID or similar. Known values include |
other |
Something else. Known values include |
See the note for the "IdUsage" property about usage.
IdVersion readable s
The version of the filesystem or other structured data on the block device. Do not make any assumptions about the format.
This property is blank if there is no version or the version is unknown.
IdLabel readable s
The label of the filesystem or other structured data on the block device.
This property is blank if there is no label or the label is unknown.
IdUUID readable s
The UUID of the filesystem or other structured data on the block device. Do not make any assumptions about the UUID as its format depends on what kind of data is on the device.
This property is blank if there is no UUID or the UUID is unknown.
Configuration readable a(sa{sv})
The configuration for the device.
This is an array of pairs of (type
, details
) where type
is
a string identifying the configuration source
(e.g. fstab
) and details
contains the
actual configuration data.
Use the AddConfigurationItem(), RemoveConfigurationItem() and UpdateConfigurationItem() methods to add, remove and update configuration items.
Use GetSecretConfiguration() to get the secrets (e.g. passphrases) that may be part of the configuration but isn't exported in this property for security reasons.
For entries of type fstab
, it means that
the block device is referenced in the system-wide
/etc/fstab
file. Known configuration
items for type fstab
are
fsname (type |
The special device |
dir (type |
The mount point |
type (type |
The filesystem type |
opts (type |
Options |
freq (type |
Dump frequency in days |
passno (type |
Pass number of parallel fsck |
For entries of type crypttab
, it means that
the block device is referenced in the system-wide
/etc/crypttab
file. Known configuration
items for type crypttab
are
name (type |
The name to set the device up as |
device (type |
The special device |
passphrase-path (type |
Either empty to specify that no password is set,
otherwise a path to a file containing the encryption password.
This may also point to a special device file in |
passphrase-contents (type |
The contents of the file containing the encryption password, if applicable. This is only available via the GetSecretConfiguration() method. |
opts (type |
Options |
For security reasons, when creating a new
crypttab
entry (via the
AddConfigurationItem()
method), then the passphrase-path
must
reference an unexisting file in the
/etc/luks-keys
directory.
CryptoBackingDevice readable o
The org.freedesktop.UDisks2.Block object that is
backing the device or /
if unknown or if
the block device is not the cleartext device for an encrypted
device.
HintPartitionable readable b
If TRUE
, the device is normally expected to be
partitionable. Devices for which this is not the case include
floppy drives, optical drives and LVM logical volumes.
HintSystem readable b
If TRUE
, the device is considered a system device.
System devices are devices that require additional permissions to access.
See udisks(8) for how to influence the value of this property.
HintIgnore readable b
If TRUE
, the device should be hidden from users.
See udisks(8) for how to influence the value of this property.
HintAuto readable b
If TRUE
, the device should be automatically started (e.g. mounted, unlocked etc.).
See udisks(8) for how to influence the value of this property.
HintName readable s
If not blank, the name to use when presenting the device.
See udisks(8) for how to influence the value of this property.
HintIconName readable s
If not blank, the icon name to use when presenting the device.
The name must adhere to the freedesktop.org icon theme specification.
See udisks(8) for how to influence the value of this property.
HintSymbolicIconName readable s
If not blank, the icon name to use when presenting the device using a symbolic icon.
The name must adhere to the freedesktop.org icon theme specification.
See udisks(8) for how to influence the value of this property.
Since 2.0.0