Devicemapper

https://docs.rs/devicemapper/0.34.7
Admin
A low-level Rust interface for Linux devicemapper kernel configuration, enabling creation and...
Tokens:149,877
Snippets:1,366
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Handle Same Name for Linear Device Setup

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Tests the behavior of setting up a linear device with a name that already exists. It asserts that a new setup with different segments fails, while a setup with identical segments succeeds.

```rust
let name = test_name("name").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params),
        )];
        let mut ld = LinearDev::setup(&dm, &name, None, table.clone()).unwrap();
        let params2 = LinearTargetParams::new(dev, Sectors(1));
        let table2 = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params2),
        )];
        assert_matches!(LinearDev::setup(&dm, &name, None, table2), Err(_));
        assert_matches!(LinearDev::setup(&dm, &name, None, table), Ok(_));
        ld.teardown(&dm).unwrap();
```

--------------------------------

### CacheDev::setup

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDev.html

Sets up a cache device using the provided metadata and data devices. This is an alternative to `new` for device setup.

```APIDOC
## CacheDev::setup

### Description
Set up a cache device from the given metadata and data devices.

### Method
```rust
pub fn setup(
    dm: &DM,
    name: &DmName,
    uuid: Option<&DmUuid>,
    meta: LinearDev,
    cache: LinearDev,
    origin: LinearDev,
    cache_block_size: Sectors,
) -> DmResult<CacheDev>
```

### Parameters
* `dm` (*DM): A reference to the DM object.
* `name` (*DmName): The name of the cache device.
* `uuid` (Option<&DmUuid>): An optional UUID for the device.
* `meta` (LinearDev): The LinearDev representing the metadata device.
* `cache` (LinearDev): The LinearDev representing the cache data device.
* `origin` (LinearDev): The LinearDev representing the origin device.
* `cache_block_size` (Sectors): The size of the cache blocks in sectors.

### Returns
* `DmResult<CacheDev>`: A Result containing the new CacheDev on success, or a DmResult error on failure.
```

--------------------------------

### Get Device Info for Non-Existent Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Attempts to get device information for a device specified by name that does not exist. This should return an ENXIO error.

```rust
let name = test_name("example_dev").expect("is valid DM name");
assert_matches!(
    DM::new().unwrap().device_info(&DevId::Name(&name)),
    Err(DmError::Core(Error::Ioctl(op, _, _, err))) if *err == nix::errno::Errno::ENXIO && op == dmi::DM_DEV_STATUS_CMD as u8
);
```

--------------------------------

### setup

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/cachedev.rs.html

Sets up a cache device from the given metadata, cache, and data devices. It can either create a new device or use an existing one, ensuring compatibility and proper initialization.

```APIDOC
## setup

### Description
Sets up a cache device from the given metadata, cache, and data devices. It can either create a new device or use an existing one, ensuring compatibility and proper initialization.

### Method

```
pub fn setup(
    dm: &DM,
    name: &DmName,
    uuid: Option<&DmUuid>,
    meta: LinearDev,
    cache: LinearDev,
    origin: LinearDev,
    cache_block_size: Sectors,
) -> DmResult<CacheDev>
```

### Parameters

* `dm` (*DM) - The devicemapper instance.
* `name` (*DmName) - The name of the cache device.
* `uuid` (Option<&DmUuid>) - The UUID of the cache device, if available.
* `meta` (LinearDev) - The metadata Linear Device.
* `cache` (LinearDev) - The cache Linear Device.
* `origin` (LinearDev) - The origin Linear Device.
* `cache_block_size` (Sectors) - The size of the cache blocks in sectors.

### Returns

A `DmResult` containing the initialized `CacheDev` on success, or a `DmError` on failure.
```

--------------------------------

### LinearDev Setup and Operations

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Demonstrates setting up a LinearDev, suspending it with specific options, resuming it, and finally tearing it down. This snippet is useful for understanding the basic lifecycle management of a linear device.

```rust
let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params),
        )];
        let mut ld = LinearDev::setup(&dm, &name, None, table).unwrap();

        ld.suspend(&dm, DmOptions::default().set_flags(DmFlags::DM_NOFLUSH))
            .unwrap();
        ld.suspend(&dm, DmOptions::default().set_flags(DmFlags::DM_NOFLUSH))
            .unwrap();
        ld.resume(&dm).unwrap();
        ld.resume(&dm).unwrap();

        ld.teardown(&dm).unwrap();
```

--------------------------------

### Setup Thin Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

Sets up a thin device, making it ready for use. This operation can be called multiple times and succeeds even on an existing or previously torn-down device.

```rust
assert_matches!(ThinDev::setup(&dm, &id, None, td_size, &tp, thin_id), Ok(_));
```

```rust
assert_matches!(ThinDev::setup(&dm, &id, None, td_size, &tp, thin_id), Ok(_));
```

```rust
let mut td = ThinDev::setup(&dm, &id, None, td_size, &tp, thin_id).unwrap();
```

--------------------------------

### Setup Existing Thin Pool Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thinpooldev.rs.html

Sets up a `ThinPoolDev` using existing metadata on the metadata device. If the device exists, it attempts to match it; otherwise, it creates a new device. Preconditions include well-formed and consistent metadata.

```rust
pub fn setup(
        dm: &DM,
        name: &DmName,
        uuid: Option<&DmUuid>,
        meta: LinearDev,
        data: LinearDev,
        data_block_size: Sectors,
        low_water_mark: DataBlocks,
        feature_args: Vec<String>,
    ) -> DmResult<ThinPoolDev> {
        let table =
            ThinPoolDev::gen_table(&meta, &data, data_block_size, low_water_mark, feature_args);
        let dev = if device_exists(dm, name)? {
            let dev_info = dm.device_info(&DevId::Name(name))?;
            let dev = ThinPoolDev {
                dev_info: Box::new(dev_info),
                meta_dev: meta,
                data_dev: data,
                table,
            };
            device_match(dm, &dev, uuid)?;
            dev
        } else {
            let dev_info = device_create(dm, name, uuid, &table, DmOptions::private())?;
            ThinPoolDev {
                dev_info: Box::new(dev_info),
                meta_dev: meta,
                data_dev: data,
                table,
            }
        };
        Ok(dev)
    }
```

--------------------------------

### Constructor: ThinPoolDevTargetTable::new

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinPoolDevTargetTable.html

Creates a new ThinPoolDevTargetTable instance. Requires start and length in Sectors, and ThinPoolTargetParams.

```rust
pub fn new( start: Sectors, length: Sectors, params: ThinPoolTargetParams, ) -> ThinPoolDevTargetTable
```

--------------------------------

### Setup Thin Device Without New

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

Attempts to set up a thin device without first calling `new()`. This is expected to fail because the thin pool has not been informed about the thin device ID.

```rust
assert_matches!(ThinDev::setup(&dm, &test_name("name").expect("is valid DM name"), None, td_size, &tp, ThinDevId::new_u64(0).expect("is below limit")), Err(DmError::Core(Error::Ioctl(_, _, _, _))));
```

--------------------------------

### Setup CacheDev from existing devices

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/cachedev.rs.html

Sets up a CacheDev, either creating a new one or using an existing device. It ensures device compatibility and creates the necessary device mapping.

```rust
pub fn setup(
        dm: &DM,
        name: &DmName,
        uuid: Option<&DmUuid>,
        meta: LinearDev,
        cache: LinearDev,
        origin: LinearDev,
        cache_block_size: Sectors,
    ) -> DmResult<CacheDev> {
        let table = CacheDev::gen_default_table(&meta, &cache, &origin, cache_block_size);
        let dev = if device_exists(dm, name)? {
            let dev_info = dm.device_info(&DevId::Name(name))?;
            let dev = CacheDev {
                dev_info: Box::new(dev_info),
                meta_dev: meta,
                cache_dev: cache,
                origin_dev: origin,
                table,
            };
            device_match(dm, &dev, uuid)?;
            dev
        } else {
            let dev_info = device_create(dm, name, uuid, &table, DmOptions::private())?;
            CacheDev {
                dev_info: Box::new(dev_info),
                meta_dev: meta,
                cache_dev: cache,
                origin_dev: origin,
                table,
            }
        };

        Ok(dev)
    }
```

--------------------------------

### Setup and Verify Linear Device Table

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Sets up a linear device with multiple target lines and verifies its configuration against the kernel's table. Asserts the size of the device matches the total range of the table.

```rust
let name = test_name("name").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![
            TargetLine::new(
                Sectors(0),
                Sectors(1),
                LinearDevTargetParams::Linear(params.clone()),
            ),
            TargetLine::new(
                Sectors(1),
                Sectors(1),
                LinearDevTargetParams::Linear(params),
            ),
        ];
        let range: Sectors = table.iter().map(|s| s.length).sum();
        let count = table.len();
        let mut ld = LinearDev::setup(&dm, &name, None, table).unwrap();

        let table = LinearDev::read_kernel_table(&dm, &DevId::Name(ld.name()))
            .unwrap()
            .table;
        assert_eq!(table.len(), count);
        assert_matches!(table[0].params, LinearDevTargetParams::Linear(ref device) if device.device == dev);
        assert_matches!(table[1].params, LinearDevTargetParams::Linear(ref device) if device.device == dev);

        assert_eq!(
            blkdev_size(&OpenOptions::new().read(true).open(ld.devnode()).unwrap()).sectors(),
            range
        );

        ld.teardown(&dm).unwrap();
```

--------------------------------

### Setup Existing ThinDev

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinDev.html

Sets up a ThinDev that already belongs to a given thin pool, identified by its thin ID. Verifies existing kernel data if the device is already known.

```rust
pub fn setup( dm: &DM, name: &DmName, uuid: Option<&DmUuid>, length: Sectors, thin_pool: &ThinPoolDev, thin_id: ThinDevId, ) -> DmResult<ThinDev>
```

--------------------------------

### Setup Thin Pool

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinPoolDev.html

Sets up a thin pool using existing metadata and data devices. Precondition: The metadata device must contain well-formed and consistent metadata for the thin pool.

```rust
pub fn setup( dm: &DM, name: &DmName, uuid: Option<&DmUuid>, meta: LinearDev, data: LinearDev, data_block_size: Sectors, low_water_mark: DataBlocks, feature_args: Vec<String>, ) -> DmResult<ThinPoolDev>
```

--------------------------------

### Setup Linear Device

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.LinearDev.html

Constructs a new linear block device by concatenating segments. Verifies existing devices if they match the provided segments. Overlapping segments are permitted but result in undefined behavior.

```rust
pub fn setup( dm: &DM, name: &DmName, uuid: Option<&DmUuid>, table: Vec<TargetLine<LinearDevTargetParams>>, ) -> DmResult<LinearDev>
```

--------------------------------

### Setup Linear Device with Same Segment

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Verifies that two distinct linear devices can be successfully set up using the same segment configuration, provided they have different names.

```rust
let name = test_name("name").expect("valid format");
        let ersatz = test_name("ersatz").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params),
        )];
        let mut ld = LinearDev::setup(&dm, &name, None, table.clone()).unwrap();
        let ld2 = LinearDev::setup(&dm, &ersatz, None, table);
        assert_matches!(ld2, Ok(_));

        ld2.unwrap().teardown(&dm).unwrap();
        ld.teardown(&dm).unwrap();
```

--------------------------------

### Setup Linear Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Creates and initializes a new LinearDev. It requires a DM instance, a name, optional UUID, and a vector of target table entries. Returns an error if the initial table is empty.

```rust
LinearDev::setup(
                &DM::new().unwrap(),
                &test_name("new").expect("valid format"),
                None,
                vec![],
            ),
            Err(_)
        );
    }

    /// Verify that setting an empty table on an existing DM device fails.
    fn test_empty_table_set(paths: &[&Path]) {
        assert!(!paths.is_empty());

        let dm = DM::new().unwrap();
        let name = test_name("name").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params),
        )];
        let mut ld = LinearDev::setup(&dm, &name, None, table).unwrap();

        assert_matches!(ld.set_table(&dm, vec![]), Err(_));
        ld.resume(&dm).unwrap();
        ld.teardown(&dm).unwrap();
    }

    /// Verify that id rename succeeds.
    fn test_rename_id(paths: &[&Path]) {
        assert!(!paths.is_empty());

        let dm = DM::new().unwrap();
        let name = test_name("name").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params),
        )];
        let mut ld = LinearDev::setup(&dm, &name, None, table).unwrap();

        ld.set_name(&dm, &name).unwrap();
        assert_eq!(ld.name(), &*name);

        ld.teardown(&dm).unwrap();
    }

    /// Verify that after a rename, the device has the new name.
    fn test_rename(paths: &[&Path]) {
        assert!(!paths.is_empty());

        let dm = DM::new().unwrap();
        let name = test_name("name").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let params = LinearTargetParams::new(dev, Sectors(0));
        let table = vec![TargetLine::new(
            Sectors(0),
            Sectors(1),
            LinearDevTargetParams::Linear(params),
        )];
        let mut ld = LinearDev::setup(&dm, &name, None, table).unwrap();

        let new_name = test_name("new_name").expect("valid format");
        ld.set_name(&dm, &new_name).unwrap();
        assert_eq!(ld.name(), &*new_name);

        ld.teardown(&dm).unwrap();
    }

    /// Verify that passing the same segments two times gets two segments.
    /// Verify that the size of the devnode is the size of the sum of the
    /// ranges of the segments. Verify that the table contains entries for both
    /// segments.
    fn test_duplicate_segments(paths: &[&Path]) {
        assert!(!paths.is_empty());

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

--------------------------------

### New ThinDevTargetTable Constructor

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinDevTargetTable.html

Creates a new ThinDevTargetTable instance with specified sector start, length, and thin target parameters.

```rust
pub fn new( start: Sectors,
 length: Sectors,
 params: ThinTargetParams,
) -> ThinDevTargetTable
```

--------------------------------

### Setup Linear Device with Multiple Distinct Segments

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Configures a linear device using five distinct segments, each with a unique offset and length. Verifies that the constructed table is equivalent to the table read back from the kernel.

```rust
let name = test_name("name").expect("valid format");
        let dev = Device::from(devnode_to_devno(paths[0]).unwrap().unwrap());
        let table = (0..5)
            .map(|n| {
                TargetLine::new(
                    Sectors(n),
                    Sectors(1),
                    LinearDevTargetParams::Linear(LinearTargetParams::new(dev, Sectors(n))),
                )
            })
            .collect::<Vec<_>>();
        let mut ld = LinearDev::setup(&dm, &name, None, table.clone()).unwrap();

        let loaded_table = LinearDev::read_kernel_table(&dm, &DevId::Name(ld.name())).unwrap();
        assert!(
            LinearDev::equivalent_tables(&LinearDevTargetTable::new(table), &loaded_table).unwrap()
        );

        ld.teardown(&dm).unwrap();
```

--------------------------------

### Create or Get Thin Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

This function creates a new thin device if it doesn't exist, or retrieves information for an existing one. It generates the default table for the thin device and handles device creation or matching.

```rust
    pub fn new(dm: &DM, name: &DmName, uuid: &DmUuid, thin_pool: &ThinPoolDev, length: Sectors, thin_id: ThinDevId) -> DmResult<ThinDev> {
        let thin_pool_device = thin_pool.device();
        let table = ThinDev::gen_default_table(length, thin_pool_device, thin_id);
        let dev = if device_exists(dm, name)? {
            let dev_info = dm.device_info(&DevId::Name(name))?;
            let dev = ThinDev {
                dev_info: Box::new(dev_info),
                table,
            };
            device_match(dm, &dev, uuid)?;
            dev
        } else {
            let dev_info = device_create(dm, name, uuid, &table, DmOptions::default())?;
            ThinDev {
                dev_info: Box::new(dev_info),
                table,
            }
        };
        Ok(dev)
    }
```

--------------------------------

### Get Table Status of Created Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Creates a device with a specific UUID and then retrieves its table status. Verifies the status is empty and the UUID matches.

```rust
let dm = DM::new().unwrap();
let name = test_name("example-dev").expect("is valid DM name");
let uuid = test_uuid("uuid").expect("is valid DM UUID");
dm.device_create(&name, Some(&uuid), DmOptions::default())
    .unwrap();

let (hdr_out, status) = dm
    .table_status(&DevId::Name(&name), DmOptions::default())
    .unwrap();
assert!(status.is_empty());
assert_eq!(hdr_out.uuid(), Some(&*uuid));
dm.device_remove(&DevId::Name(&name), DmOptions::default())
    .unwrap();
```

--------------------------------

### Generate Default Thin Device Table

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

Generates a default table entry for a thin device. The table format is `<start> <length> "thin" <thinpool maj:min> <thin_id>`, with a single entry.

```rust
    fn gen_default_table(
        length: Sectors,
        thin_pool: Device,
        thin_id: ThinDevId,
    ) -> ThinDevTargetTable {
        ThinDevTargetTable::new(
            Sectors::default(),
            length,
            ThinTargetParams::new(thin_pool, thin_id, None),
        )
    }
```

--------------------------------

### Create and Manage a Thin Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

This snippet demonstrates the creation of a thin device, setting up an XFS filesystem on it, and verifying the data usage in the thin pool. It also shows the destruction of the thin device and other related components.

```rust
let data_usage_2 = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert_eq!(data_usage_2, data_usage_1);

        xfs_set_uuid(&ss.devnode(), &Uuid::new_v4()).unwrap();

        // Setting the uuid of the snapshot filesystem bumps the usage,
        // but does not increase the usage quite as much as establishing
        // the origin.
        let data_usage_3 = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert!(data_usage_3 - data_usage_2 > DataBlocks(0));
        assert!(data_usage_3 - data_usage_2 < data_usage_1);
        assert!(data_usage_3 - data_usage_2 > data_usage_1 / 2usize);

        let thin_id = ThinDevId::new_u64(2).expect("is below limit");
        let thin_name = test_name("name1").expect("is valid DM name");
        let mut td1 =
            ThinDev::new(&dm, &thin_name, None, Sectors(2 * IEC::Gi), &tp, thin_id).unwrap();
        udev_settle().unwrap();

        let data_usage_4 = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert_eq!(data_usage_4, data_usage_3);

        xfs_create_fs(&td1.devnode(), None).unwrap();

        let data_usage_5 = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert!(data_usage_5 - data_usage_4 > 32usize * data_usage_1);

        ss.destroy(&dm, &tp).unwrap();
        td1.destroy(&dm, &tp).unwrap();
        td.destroy(&dm, &tp).unwrap();
        tp.teardown(&dm).unwrap();
```

--------------------------------

### Parse Argument Pairs

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/cachedev.rs.html

Parses pairs of string arguments from a slice, starting from a given index. It expects an even number of arguments for the pairs and returns the next starting index and the collected pairs. Errors if the number of arguments is odd.

```rust
fn parse_pairs(start_index: usize, vals: &[&str]) -> DmResult<(usize, Vec<(String, String)>)> {
        let num_pairs: usize = parse_value(vals[start_index], "number of pairs")?;
        if num_pairs % 2 != 0 {
            let err_msg = format!("Number of args \"{num_pairs}\" is not even");
            return Err(DmError::Dm(ErrorEnum::Invalid, err_msg));
        }
        let next_start_index = start_index + num_pairs + 1;
        Ok((
            next_start_index,
            vals[start_index + 1..next_start_index]
                .chunks(2)
                .map(|p| (p[0].to_string(), p[1].to_string()))
                .collect(),
        ))
    }
```

--------------------------------

### Create and Validate Thin Device with XFS Filesystem

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

Demonstrates creating an XFS filesystem on a thin device, synchronizing with udev, and validating its UUID. Includes teardown and re-setup of the thin device.

```rust
let dm = DM::new().unwrap();
let mut tp = minimal_thinpool(&dm, paths[0]);
let thin_id = ThinDevId::new_u64(0).expect("is below limit");
let id = test_name("udev_test_thin_dev").expect("is valid DM name");

let mut td = ThinDev::new(&dm, &id, None, tp.size(), &tp, thin_id).unwrap();
udev_settle().unwrap();

let uuid = Uuid::new_v4();

// Create the XFS FS on top of the thin device
xfs_create_fs(&td.devnode(), Some(uuid)).unwrap();

// Synchronize with udev processing triggered by xfs_create_fs()
udev_settle().unwrap();

validate(&uuid, &td.devnode());

// Teardown the thindev, then set it back up and make sure all is well with udev
td.teardown(&dm).unwrap();
td = ThinDev::setup(&dm, &id, None, tp.size(), &tp, thin_id).unwrap();
validate(&uuid, &td.devnode());

// Create a snapshot and make sure we get correct actions in user space WRT udev
let ss_id = ThinDevId::new_u64(1).expect("is below limit");
let ss_name = test_name("snap_name").expect("is valid DM name");
let mut ss = td.snapshot(&dm, &ss_name, None, &tp, ss_id).unwrap();
udev_settle().unwrap();

let ss_new_uuid = set_new_fs_uuid(&ss.devnode());

// Validate that the symlink for original and snapshot are correct
validate(&ss_new_uuid, &ss.devnode());
validate(&uuid, &td.devnode());

// Tear everything down
ss.destroy(&dm, &tp).unwrap();
td.destroy(&dm, &tp).unwrap();
tp.teardown(&dm).unwrap();
```

--------------------------------

### DeviceInfo::uuid

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/deviceinfo.rs.html

Gets the devicemapper UUID of the device.

```APIDOC
## DeviceInfo::uuid

### Description
Returns the device's devicemapper UUID.

### Signature
```rust
pub fn uuid(&self) -> Option<&DmUuid>
```

### Returns
An `Option` containing a reference to the device's UUID (`DmUuid`) if available, otherwise `None`.
```

--------------------------------

### Get Device from CacheDevTargetTable

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDevTargetTable.html

Retrieves the Device associated with the CacheDevTargetTable.

```rust
fn device(&self) -> Device
```

--------------------------------

### DeviceInfo::open_count

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/deviceinfo.rs.html

Gets the current number of times the device is open.

```APIDOC
## DeviceInfo::open_count

### Description
Returns the number of times the device is currently open.

### Signature
```rust
pub fn open_count(&self) -> i32
```

### Returns
An `i32` representing the open count of the device.
```

--------------------------------

### Create Device with Table and Resume

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/shared.rs.html

Creates a device, loads a table, and resumes it, allowing caller to specify DmOptions for resuming. Returns DeviceInfo upon success.

```Rust
pub fn device_create<T: TargetTable>(
    dm: &DM,
    name: &DmName,
    uuid: Option<&DmUuid>,
    table: &T,
    suspend_options: DmOptions,
) -> DmResult<DeviceInfo> {
    dm.device_create(name, uuid, DmOptions::default())?;

    let id = DevId::Name(name);
    let dev_info = match dm.table_load(&id, &table.to_raw_table(), DmOptions::default()) {
        Err(e) => {

```

--------------------------------

### TargetTypeBuf::as_bytes

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.TargetTypeBuf.html

Gets the inner value of the TargetTypeBuf as a byte slice.

```APIDOC
## TargetTypeBuf::as_bytes

### Description
Get the inner value as bytes.

### Signature
`pub fn as_bytes(&self) -> &[u8]`

### Returns
A byte slice (`&[u8]`) representing the inner value.
```

--------------------------------

### Get Table from DmDevice Trait

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.LinearDevTargetTable.html

Retrieves the table that the LinearDev believes it has.

```rust
fn table(&self) -> &LinearDevTargetTable
```

--------------------------------

### DmUuid::as_bytes

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.DmUuid.html

Gets the inner value of the DmUuid as a byte slice.

```APIDOC
#### pub fn as_bytes(&self) -> &[u8]

Get the inner value as bytes

```rust
pub fn as_bytes(&self) -> &[u8]
```
```

--------------------------------

### Create and Test a Thin Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

Creates a thin device, formats it with XFS, mounts it, writes data, and then checks pool usage. Finally, it destroys the thin device and thin pool.

```rust
fn test_filesystem(paths: &[&Path]) {
        assert!(!paths.is_empty());

        let dm = DM::new().unwrap();
        let mut tp = minimal_thinpool(&dm, paths[0]);

        let thin_id = ThinDevId::new_u64(0).expect("is below limit");
        let thin_name = test_name("name").expect("is valid DM name");
        let mut td = ThinDev::new(&dm, &thin_name, None, tp.size(), &tp, thin_id).unwrap();
        udev_settle().unwrap();

        let orig_data_usage = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert_eq!(orig_data_usage, DataBlocks(0));

        xfs_create_fs(&td.devnode(), None).unwrap();

        let data_usage_1 = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert!(data_usage_1 > DataBlocks(0));

        let tmp_dir = tempfile::Builder::new()
            .prefix(&test_string("devicemapper_testing"))
            .tempdir()
            .unwrap();
        mount(
            Some(&td.devnode()),
            tmp_dir.path(),
            Some("xfs"),
            MsFlags::empty(),
            None as Option<&str>,
        )
        .unwrap();

        for i in 0..100 {
            let file_path = tmp_dir.path().join(format!("devicemapper_test{i}.txt"));
            writeln!(
                &OpenOptions::new()
                    .create(true)
                    .truncate(true)
                    .write(true)
                    .open(file_path)
                    .unwrap(),
                "data"
            )
            .unwrap();
        }
        umount2(tmp_dir.path(), MntFlags::MNT_DETACH).unwrap();

        let data_usage_2 = match tp.status(&dm, DmOptions::default()).unwrap() {
            ThinPoolStatus::Working(ref status) => status.usage.used_data,
            ThinPoolStatus::Error => panic!("devicemapper could not obtain thin pool status"),
            ThinPoolStatus::Fail => panic!("failed to get thinpool status"),
        };
        assert!(data_usage_2 > data_usage_1);

        td.destroy(&dm, &tp).unwrap();
        tp.teardown(&dm).unwrap();
    }
```

--------------------------------

### Get Table from CacheDevTargetTable

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDevTargetTable.html

Returns the internal table representation of the CacheDevTargetTable.

```rust
fn table(&self) -> &CacheDevTargetTable
```

--------------------------------

### ThinDev::setup

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinDev.html

Sets up a thin device that already belongs to a given thin pool, identified by its thin ID. It verifies existing data and returns an error if inconsistencies are found or if the thin ID is not registered with the pool.

```APIDOC
## ThinDev::setup

### Description
Set up a thin device which already belongs to the given thin_pool. The thin device is identified by the thin_id, which is already known to the pool. If the device is already known to kernel, just verify that specified data matches and return an error if it does not. If the device has no thin id already registered with the thin pool an error is returned.

### Method
`ThinDev::setup`

### Parameters
- `dm` (&DM): A reference to the DM (Device Mapper) instance.
- `name` (&DmName): The name of the thin device.
- `uuid` (Option<&DmUuid>): An optional UUID for the device.
- `length` (Sectors): The length of the device in sectors.
- `thin_pool` (&ThinPoolDev): A reference to the thin pool device.
- `thin_id` (ThinDevId): The ID of the thin device within the pool.

### Returns
- `DmResult<ThinDev>`: A `Result` containing the `ThinDev` on success, or a `DmError` on failure.
```

--------------------------------

### Get ThinDev ID

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinDev.html

Retrieves the thin ID associated with the linear device.

```rust
pub fn id(&self) -> ThinDevId
```

--------------------------------

### Get TypeId for any type

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.DmName.html

Implements the Any trait, providing runtime type information.

```rust
fn type_id(&self) -> TypeId>
```

--------------------------------

### Create Device with Empty Dependencies

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Creates a device and verifies that it initially has no dependencies. The device is then removed.

```rust
let dm = DM::new().unwrap();
let name = test_name("example-dev").expect("is valid DM name");
dm.device_create(&name, None, DmOptions::default()).unwrap();

let deps = dm
    .table_deps(&DevId::Name(&name), DmOptions::default())
    .unwrap();
assert!(deps.is_empty());
dm.device_remove(&DevId::Name(&name), DmOptions::default())
    .unwrap();
```

--------------------------------

### Get Device Name for CacheDevTargetTable

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDevTargetTable.html

Retrieves the name of the device associated with the CacheDevTargetTable.

```rust
fn name(&self) -> &DmName
```

--------------------------------

### Get Thin Device ID

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/thindev.rs.html

Retrieves the thin ID associated with the linear device.

```rust
    pub fn id(&self) -> ThinDevId {
        self.table.table.params.thin_id
    }
```

--------------------------------

### ThinPoolDev::setup

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinPoolDev.html

Sets up a thin pool using existing metadata. This function initializes a thin pool from the provided metadata and data devices. It returns an error if the `data_block_size` is out of range. Precondition: The metadata device must contain existing, well-formed, and consistent metadata for the thin pool.

```APIDOC
## ThinPoolDev::setup

### Description
Set up a thin pool from the given metadata and data device. Returns an error if data_block_size is not within required range. Precondition: There is existing metadata for this thinpool device on the metadata device. If the metadata is corrupted, subsequent errors will result, so it is expected that the metadata is well-formed and consistent with the data on the data device.

### Method
`ThinPoolDev::setup(
    dm: &DM,
    name: &DmName,
    uuid: Option<&DmUuid>,
    meta: LinearDev,
    data: LinearDev,
    data_block_size: Sectors,
    low_water_mark: DataBlocks,
    feature_args: Vec<String>,
) -> DmResult<ThinPoolDev>`

### Parameters
* `dm` (*DM) - The Device Mapper instance.
* `name` (*DmName) - The name for the thin pool device.
* `uuid` (Option<&DmUuid>) - An optional UUID for the thin pool device.
* `meta` (*LinearDev) - The LinearDev representing the metadata device.
* `data` (*LinearDev) - The LinearDev representing the data device.
* `data_block_size` (*Sectors) - The size of data blocks in sectors.
* `low_water_mark` (*DataBlocks) - The low water mark for the thin pool.
* `feature_args` (*Vec<String>) - A vector of strings representing feature arguments.

### Returns
* `DmResult<ThinPoolDev>` - A `Result` containing the new `ThinPoolDev` on success, or a `DmError` on failure.
```

--------------------------------

### Get Flakey Target Type

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.FlakeyTargetParams.html

Returns the target type identifier for the flakey target.

```rust
fn target_type(&self) -> TargetTypeBuf
```

--------------------------------

### Get DmName as bytes

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.DmName.html

Retrieves the inner value of the DmName identifier as a byte slice.

```rust
pub fn as_bytes(&self) -> &[u8]
```

--------------------------------

### Get Size of CacheDevTargetTable

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDevTargetTable.html

Returns the number of sectors available for user data in the CacheDevTargetTable.

```rust
fn size(&self) -> Sectors
```

--------------------------------

### Get Device Node Path for CacheDevTargetTable

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDevTargetTable.html

Returns the device node path for the CacheDevTargetTable.

```rust
fn devnode(&self) -> PathBuf
```

--------------------------------

### Create and Remove Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Demonstrates the creation and subsequent removal of a device. This is a basic workflow for managing devices.

```rust
dm.device_create(&third_name, None, DmOptions::default())
    .unwrap();

assert_matches!(
    dm.device_rename(&new_name, &DevId::Name(&third_name)),
    Err(DmError::Core(Error::Ioctl(op, _, _, err))) if *err == nix::errno::Errno::EBUSY && op == dmi::DM_DEV_RENAME_CMD as u8
);

dm.device_remove(&DevId::Name(&third_name), DmOptions::default())
    .unwrap();
dm.device_remove(&DevId::Name(&new_name), DmOptions::default())
    .unwrap();
```

--------------------------------

### TargetLine Constructor

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/shared.rs.html

Creates a new TargetLine struct with the specified start, length, and parameters.

```Rust
pub fn new(start: Sectors, length: Sectors, params: T) -> TargetLine<T> {
    TargetLine {
        start,
        length,
        params,
    }
}

```

--------------------------------

### LinearDev::setup

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.LinearDev.html

Constructs a new linear block device by concatenating segments. It can also verify existing device configurations against provided segments.

```APIDOC
## LinearDev::setup

### Description
Constructs a new block device by concatenating the given segments into linear space. If the device is already known to the kernel, this method verifies that the provided segments exactly match the kernel data. Overlapping segments are permitted but result in undefined behavior.

### Method
`setup`

### Parameters
- `dm`: A reference to the `DM` struct.
- `name`: The `DmName` for the new device.
- `uuid`: An optional `DmUuid` for the device.
- `table`: A `Vec<TargetLine<LinearDevTargetParams>>` representing the segments to concatenate.

### Returns
A `DmResult<LinearDev>` which is either the newly created `LinearDev` or an error.
```

--------------------------------

### DM Context Initialization

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Creates a new context for communicating with the Device Mapper. This involves opening the control device file.

```APIDOC
## DM::new()

### Description
Initializes a new `DM` context, which is required for performing subsequent Device Mapper operations. It opens the appropriate control device file based on the target operating system.

### Method
`new()`

### Parameters
None

### Returns
- `DmResult<DM>`: A `DmResult` containing the initialized `DM` context on success, or a `DmError` on failure (e.g., unable to open control device).

### Example
```rust
use devicemapper::core::dm::DM;

match DM::new() {
    Ok(dm_context) => {
        // Use dm_context for further operations
    },
    Err(e) => {
        eprintln!("Failed to initialize DM context: {}", e);
    }
}
```
```

--------------------------------

### LinearTargetParams Struct

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.LinearTargetParams.html

Represents parameters for a linear target, including the device and start offset.

```APIDOC
## Struct LinearTargetParams

### Description
Struct representing params for a linear target.

### Fields
* `device` (Device) - Device on which this segment resides.
* `start_offset` (Sectors) - Start offset in device on which this segment resides.

### Methods
#### `new(device: Device, start_offset: Sectors) -> LinearTargetParams`
Create a new LinearTargetParams struct.
```

--------------------------------

### Get Device Mapper Version

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Retrieves the version of the Device Mapper. This is useful for compatibility checks.

```rust
#[test]
/// Test that some version can be obtained.
fn sudo_test_version() {
    assert_matches!(DM::new().unwrap().version(), Ok(_));
}
```

--------------------------------

### TargetParams Implementation for LinearTargetParams

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/lineardev.rs.html

Provides methods to get the parameter string and target type for LinearTargetParams.

```rust
impl TargetParams for LinearTargetParams {
    fn param_str(&self) -> String {
        format!("{} {}", self.device, *self.start_offset)
    }

    fn target_type(&self) -> TargetTypeBuf {
        TargetTypeBuf::new(LINEAR_TARGET_NAME.into()).expect("LINEAR_TARGET_NAME is valid")
    }
}
```

--------------------------------

### DeviceInfo::new Constructor

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.DeviceInfo.html

Parses a DM ioctl structure to create a new DeviceInfo instance. This is equivalent to using DeviceInfo::try_from(hdr).

```rust
pub fn new(hdr: Struct_dm_ioctl) -> DmResult<Self>
```

--------------------------------

### Test UdevSync Begin (Non-Primary Source)

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm_udev_sync.rs.html

Tests the `UdevSync::begin` method when the source is not the primary udev source. It verifies initial state and cleanup.

```rust
let mut hdr: dmi::Struct_dm_ioctl = devicemapper_sys::dm_ioctl {
                ..Default::default()
            };
            let sync = UdevSync::begin(&mut hdr, dmi::DM_TABLE_STATUS_CMD as u8).unwrap();
            assert_eq!(sync.cookie, 0);
            assert_eq!(sync.semid, None);
            assert_eq!(hdr.event_nr, 0);
            assert!(sync.end(DmFlags::empty().bits()).is_ok())
```

--------------------------------

### DeviceInfo::device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/deviceinfo.rs.html

Gets the device's major and minor device numbers as a Device object.

```APIDOC
## DeviceInfo::device

### Description
Returns the device's major and minor device numbers, represented as a `Device`.

### Signature
```rust
pub fn device(&self) -> Device
```

### Returns
A `Device` struct containing the major and minor numbers.
```

--------------------------------

### Get ThinDev Status

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinDev.html

Retrieves the current status of the thin device, including any specified options.

```rust
pub fn status(&self, dm: &DM, options: DmOptions) -> DmResult<ThinStatus>
```

--------------------------------

### Create and Remove Device

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/core/dm.rs.html

Demonstrates the creation of a device with a name and UUID, followed by its removal. Ensures the device's name and UUID are correctly set after creation.

```rust
let dm = DM::new().unwrap();
let name = test_name("example-dev").expect("is valid DM name");
let uuid = test_uuid("example-363333333333333").expect("is valid DM uuid");
dm.device_create(&name, Some(&uuid), DmOptions::default())
.unwrap();

assert_eq!(result.name(), Some(&*name));
assert_eq!(result.uuid(), Some(&*uuid));

dm.device_remove(&DevId::Name(&name), DmOptions::default())
.unwrap();
```

--------------------------------

### Get Data Block Size

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinPoolDev.html

Retrieves the configured data block size for the thin pool.

```rust
pub fn data_block_size(&self) -> Sectors
```

--------------------------------

### Get Data Device

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinPoolDev.html

Retrieves the LinearDev representing the data device backing the thin pool.

```rust
pub fn data_dev(&self) -> &LinearDev
```

--------------------------------

### device_create Function

Source: https://docs.rs/devicemapper/0.34.7/src/devicemapper/shared.rs.html

Creates a device, loads a table, and resumes it, allowing the caller to specify DmOptions for resuming.

```APIDOC
## fn device_create<T: TargetTable>(dm: &DM, name: &DmName, uuid: Option<&DmUuid>, table: &T, suspend_options: DmOptions) -> DmResult<DeviceInfo>

### Description
Create a device, load a table, and resume it allowing the caller to specify the DmOptions for resuming.

### Parameters
- **`dm`**: A reference to the `DM` struct.
- **`name`**: The name of the device to create.
- **`uuid`**: An optional UUID for the device.
- **`table`**: The target table to load for the device.
- **`suspend_options`**: `DmOptions` to use when resuming the device.
```

--------------------------------

### Get Metadata Device

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.ThinPoolDev.html

Retrieves the LinearDev representing the metadata device backing the thin pool.

```rust
pub fn meta_dev(&self) -> &LinearDev
```

--------------------------------

### Set up a CacheDev

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDev.html

Sets up a cache device using provided metadata and data devices. This function is used to initialize a new cache device configuration.

```rust
pub fn setup( dm: &DM, name: &DmName, uuid: Option<&DmUuid>, meta: LinearDev, cache: LinearDev, origin: LinearDev, cache_block_size: Sectors, ) -> DmResult<CacheDev>
```

--------------------------------

### Get UUID for CacheDevTargetTable

Source: https://docs.rs/devicemapper/0.34.7/devicemapper/struct.CacheDevTargetTable.html

Retrieves the UUID of the device, if available. Note that the UUID is not any standard UUID format.

```rust
fn uuid(&self) -> Option<&DmUuid>
```
Tokens:
Raw