org.freedesktop.UDisks2.Block: UDisks Reference Manual

org.freedesktop.UDisks2.Block

org.freedesktop.UDisks2.Block — Block device

Methods

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);
Rescan                  (IN  a{sv}     options);

Properties

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

Description

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

Method Details

The AddConfigurationItem() method

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.

`IN (sa{sv}) item`:	The configuration item to add.
`IN a{sv} options`:	Options (currently unused except for standard options).

The RemoveConfigurationItem() method

RemoveConfigurationItem (IN  (sa{sv}) item,
                         IN  a{sv}    options);

Removes an existing configuration item.

See the "Configuration" property for details about valid configuration items.

`IN (sa{sv}) item`:	The configuration item to remove.
`IN a{sv} options`:	Options (currently unused except for standard options).

The UpdateConfigurationItem() method

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.

`IN (sa{sv}) old_item`:	The configuration item to remove.
`IN (sa{sv}) new_item`:	The configuration item to add. Must be of the same type as `old_item`.
`IN a{sv} options`:	Options (currently unused except for standard options).

The GetSecretConfiguration() method

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.

`IN a{sv} options`:	Options (currently unused except for standard options).
`OUT a(sa{sv}) configuration`:	The resulting configuration.

The Format() method

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

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

`IN s type`:	The type of file system, partition table or other content to format the device with.
`IN a{sv} options`:	Options - known options (in addition to standard options) includes `label` (of type 's'), `take-ownership` (of type 'b'), `encrypt.passphrase` (of type 's' or 'ay'), `erase` (of type 's'), `no-block` (of type 'b') and `update-partition-type` (of type 'b').

The OpenForBackup() method

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.

`IN a{sv} options`:	Options (currently unused except for standard options).
`OUT h fd`:	An index for the returned file descriptor.

The OpenForRestore() method

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.

`IN a{sv} options`:	Options (currently unused except for standard options).
`OUT h fd`:	An index for the returned file descriptor.

The OpenForBenchmark() method

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

`IN a{sv} options`:	Options (currently unused except for standard options).
`OUT h fd`:	An index for the returned file descriptor.

The Rescan() method

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.

IN a{sv} options:

Options (currently unused except for standard options).

Property Details

The "Device" property

Device  readable   ay

The special device file for the block device e.g. /dev/sda2.

The "PreferredDevice" property

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.

The "Symlinks" property

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.

The "DeviceNumber" property

DeviceNumber  readable   t

The dev_t of the block device.

The "Id" property

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

The "Size" property

Size  readable   t

The size of the block device.

The "ReadOnly" property

ReadOnly  readable   b

If TRUE, the device can not be written to, only read from.

The "Drive" property

Drive  readable   o

The org.freedesktop.UDisks2.Drive object that the block device belongs to, or '/' if no such object exists.

The "MDRaid" property

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

The "MDRaidMember" property

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

The "IdUsage" property

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.

The "IdType" property

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. `vfat`).
crypto	Encrypted data. Known values include `crypto_LUKS`.
raid	RAID or similar. Known values include `LVM2_member` (for LVM2 components), `linux_raid_member` (for MD-RAID components.)
other	Something else. Known values include `swap` (for swap space), `suspend` (data used when resuming from suspend-to-disk.

See the note for the "IdUsage" property about usage.

The "IdVersion" property

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.

The "IdLabel" property

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.

The "IdUUID" property

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.

The "Configuration" property

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 `'ay'`)	The special device
dir (type `'ay'`)	The mount point
type (type `'ay'`)	The filesystem type
opts (type `'ay'`)	Options
freq (type `'i'`)	Dump frequency in days
passno (type `'i'`)	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 `'ay'`)	The name to set the device up as
device (type `'ay'`)	The special device
passphrase-path (type `'ay'`)	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 `/dev` such as `/dev/random`.
passphrase-contents (type `'ay'`)	The contents of the file containing the encryption password, if applicable. This is only available via the GetSecretConfiguration() method.
opts (type `'ay'`)	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.

The "CryptoBackingDevice" property

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.

The "HintPartitionable" property

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.