Struct devicemapper::DM

pub struct DM { /* fields omitted */ }

Context needed for communicating with devicemapper.

Methods

impl DM

pub fn new() -> DmResult<DM>

Create a new context for communicating with DM.

pub fn file(&self) -> &File

Get the file within the DM context, likely for polling purposes.

pub fn version(&self) -> DmResult<(u32, u32, u32)>

Devicemapper version information: Major, Minor, and patchlevel versions.

pub fn remove_all(&self, flags: DmFlags) -> DmResult<()>

Remove all DM devices and tables. Use discouraged other than for debugging.

If DM_DEFERRED_REMOVE is set, the request will succeed for in-use devices, and they will be removed when released.

Valid flags: DM_DEFERRED_REMOVE

pub fn list_devices(&self) -> DmResult<Vec<(DmNameBuf, Device, Option<u32>)>>

Returns a list of tuples containing DM device names, a Device, which holds their major and minor device numbers, and on kernels that support it, each device's last event_nr.

pub fn device_create(
    &self,
    name: &DmName,
    uuid: Option<&DmUuid>,
    flags: DmFlags
) -> DmResult<DeviceInfo>

Create a DM device. It starts out in a "suspended" state.

Valid flags: DM_READONLY, DM_PERSISTENT_DEV

Example

use devicemapper::{DM, DmFlags, DmName};

let dm = DM::new().unwrap();

// Setting a uuid is optional
let name = DmName::new("example-dev").expect("is valid DM name");
let dev = dm.device_create(name, None, DmFlags::empty()).unwrap();

pub fn device_remove(&self, id: &DevId, flags: DmFlags) -> DmResult<DeviceInfo>

Remove a DM device and its mapping tables.

If DM_DEFERRED_REMOVE is set, the request for an in-use devices will succeed, and it will be removed when no longer used.

Valid flags: DM_DEFERRED_REMOVE

pub fn device_rename(
    &self,
    old_name: &DmName,
    new: &DevId
) -> DmResult<DeviceInfo>

Change a DM device's name OR set the device's uuid for the first time.

Prerequisite: if new == DevId::Name(new_name), old_name != new_name Prerequisite: if new == DevId::Uuid(uuid), device's current uuid must be "". Note: Possibly surprisingly, returned DeviceInfo's uuid or name field contains the previous value, not the newly set value.

pub fn device_suspend(&self, id: &DevId, flags: DmFlags) -> DmResult<DeviceInfo>

Suspend or resume a DM device, depending on if DM_SUSPEND flag is set or not.

Resuming a DM device moves a table loaded into the "inactive" slot by table_load() into the "active" slot.

Will block until pending I/O is completed unless DM_NOFLUSH flag is given. Will freeze filesystem unless DM_SKIP_LOCKFS flags is given. Additional I/O to a suspended device will be held until it is resumed.

Valid flags: DM_SUSPEND, DM_NOFLUSH, DM_SKIP_LOCKFS

Example

use devicemapper::{DM, DevId, DmFlags, DmName};
let dm = DM::new().unwrap();

let name = DmName::new("example-dev").expect("is valid DM name");
let id = DevId::Name(name);
dm.device_suspend(&id, DmFlags::DM_SUSPEND).unwrap();

pub fn device_info(&self, id: &DevId) -> DmResult<DeviceInfo>

Get DeviceInfo for a device. This is also returned by other methods, but if just the DeviceInfo is desired then this just gets it.

pub fn device_wait(
    &self,
    id: &DevId,
    flags: DmFlags
) -> DmResult<(DeviceInfo, Vec<(Sectors, Sectors, TargetTypeBuf, String)>)>

Wait for a device to report an event.

Once an event occurs, this function behaves just like table_status, see that function for more details.

This interface is not very friendly to monitoring multiple devices. Events are also exported via uevents, that method may be preferable.

pub fn table_load(
    &self,
    id: &DevId,
    targets: &[(Sectors, Sectors, TargetTypeBuf, String)]
) -> DmResult<DeviceInfo>

Load targets for a device into its inactive table slot.

targets is an array of (sector_start, sector_length, type, params).

params are target-specific, please see [Linux kernel documentation] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/ -> Documentation/device-mapper for more.

Example

use devicemapper::{DM, DevId, DmName, Sectors, TargetTypeBuf};
let dm = DM::new().unwrap();

// Create a 16MiB device (32768 512-byte sectors) that maps to /dev/sdb1
// starting 1MiB into sdb1
let table = vec![(
    Sectors(0),
    Sectors(32768),
    TargetTypeBuf::new("linear".into()).expect("valid"),
    "/dev/sdb1 2048".into()
)];

let name = DmName::new("example-dev").expect("is valid DM name");
let id = DevId::Name(name);
dm.table_load(&id, &table).unwrap();

pub fn table_clear(&self, id: &DevId) -> DmResult<DeviceInfo>

Clear the "inactive" table for a device.

pub fn table_deps(&self, id: &DevId, flags: DmFlags) -> DmResult<Vec<Device>>

Query DM for which devices are referenced by the "active" table for this device.

If DM_QUERY_INACTIVE_TABLE is set, instead return for the inactive table.

Valid flags: DM_QUERY_INACTIVE_TABLE

pub fn table_status(
    &self,
    id: &DevId,
    flags: DmFlags
) -> DmResult<(DeviceInfo, Vec<(Sectors, Sectors, TargetTypeBuf, String)>)>

Return the status of all targets for a device's "active" table.

Returns DeviceInfo and a Vec of (sector_start, sector_length, type, params).

If DM_STATUS_TABLE flag is set, returns the current table value. Otherwise returns target-specific status information.

If DM_NOFLUSH is set, retrieving the target-specific status information for targets with metadata will not cause a metadata write.

If DM_QUERY_INACTIVE_TABLE is set, instead return the status of the inactive table.

Valid flags: DM_NOFLUSH, DM_STATUS_TABLE, DM_QUERY_INACTIVE_TABLE

Example

use devicemapper::{DM, DevId, DmFlags, DmName};
let dm = DM::new().unwrap();

let name = DmName::new("example-dev").expect("is valid DM name");
let id = DevId::Name(name);
let res = dm.table_status(&id, DmFlags::DM_STATUS_TABLE).unwrap();
println!("{} {:?}", res.0.name(), res.1);

pub fn list_versions(&self) -> DmResult<Vec<(String, u32, u32, u32)>>

Returns a list of each loaded target type with its name, and version broken into major, minor, and patchlevel.

pub fn target_msg(
    &self,
    id: &DevId,
    sector: Option<Sectors>,
    msg: &str
) -> DmResult<(DeviceInfo, Option<String>)>

Send a message to the device specified by id and the sector specified by sector. If sending to the whole device, set sector to None.

pub fn arm_poll(&self) -> DmResult<DeviceInfo>

If DM is being used to poll for events, once it indicates readiness it will continue to do so until we rearm it, which is what this method does.

Trait Implementations