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);
    OpenDevice              (IN  s         mode,
                             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.

This method is deprecated since 2.7.3. Use OpenDevice() with `O_EXCL` and `O_CLOEXEC` flags instead.

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

This method is deprecated since 2.7.3. Use OpenDevice() with `O_EXCL`, `O_SYNC` and `O_CLOEXEC` flags instead.

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

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

### The OpenDevice() method

    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.

`IN s `mode``: | Mode: "r" for read-only, "w" for write-only or "rw" for read-write
`IN a{sv} `options``: | Options - known options (in addition to standard options) includes `flags` (of type 'i')
`OUT h `fd``: | An index for the returned file descriptor.

Since 2.7.3

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

### The "HintSystem" property

    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.

### The "HintIgnore" 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.

### The "HintAuto" 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.

### The "HintName" 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.

### The "HintIconName" 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.

### The "HintSymbolicIconName" 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