rsblkid 0.4.1

Safe Rust wrapper around the `util-linux/libblkid` C library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

// Copyright (c) 2023 Nick Piaddo
// SPDX-License-Identifier: Apache-2.0 OR MIT

// From dependency library

// From standard library
use std::mem::MaybeUninit;
use std::path::PathBuf;

// From this library
use crate::core::utils::misc::{Disk, MiscError};
use crate::ffi_utils;

// On Linux a file path cannot exceed 4096 characters (not accounting for the '\0' C-string terminating character).
const MAX_FILE_PATH_LENGTH: usize = 4097;

/// Returns the pathname to a block device with a given device number.
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use std::path::PathBuf;
/// use rsblkid::utils::misc;
///
/// fn main() -> rsblkid::Result<()> {
///     // Assuming we have the following devices
///     //
///     // NAME              MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
///     // vda                 8:16   1  14.7G  0 disk
///     // └─vda1              8:17   1     2G  0 part
///     //
///     let device_number_vda   = 0x0810; // concatenation in hexadecimal of MAJ:MIN
///     let actual = misc::device_path_from_number(device_number_vda)?;
///     let path = PathBuf::from("/dev/vda");
///     let expected = Some(path);
///     assert_eq!(actual, expected);
///
///     let device_number_vda1  = 0x0811;
///     let actual = misc::device_path_from_number(device_number_vda1)?;
///     let path = PathBuf::from("/dev/vda1");
///     let expected = "vda";
///     assert_eq!(actual, expected);
///
///     Ok(())
/// }
/// ```
pub fn device_path_from_number(device_number: u64) -> Option<PathBuf> {
    log::debug!(
        "misc::device_path_from_number getting device path from device number {:?}",
        device_number
    );

    let mut ptr = MaybeUninit::<*mut libc::c_char>::zeroed();
    unsafe {
        ptr.write(libblkid::blkid_devno_to_devname(device_number));
    }

    match unsafe { ptr.assume_init() } {
        path if path.is_null() => {
            log::debug!(
                    "misc::device_path_from_number found no device path from device number {:?}. libblkid::blkid_devno_to_devname returned a NULL pointer",
                    device_number
                );

            None
        }
        path => {
            let dev_path = ffi_utils::const_c_char_array_to_path_buf(path);
            // release memory allocated by `libblkid` to avoid memory leaks.
            unsafe {
                libc::free(path as *mut _);
            }
            log::debug!(
                "misc::device_path_from_number found device path {:?} from device number {:?}",
                dev_path,
                device_number
            );

            Some(dev_path)
        }
    }
}

/// Returns a device's base name given its device number. For a partition, this function returns
/// the base name of device the partition is on.
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use rsblkid::utils::misc;
///
/// fn main() -> rsblkid::Result<()> {
///     // Assuming we have the following devices
///     //
///     // NAME              MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINTS
///     // vda                 8:16   1  14.7G  0 disk
///     // └─vda1              8:17   1     2G  0 part
///     //
///     let device_number_vda   = 0x0810; // concatenation in hexadecimal of MAJ:MIN
///     let disk = misc::device_base_name_from_number(device_number_vda)?;
///     let actual = disk.name();
///     let expected = "vda";
///     assert_eq!(actual, expected);
///
///     let device_number_vda1  = 0x0811;
///     let disk = misc::device_base_name_from_number(device_number_vda1)?;
///     let actual = disk.name();
///     let expected = "vda";
///     assert_eq!(actual, expected);
///
///     Ok(())
/// }
/// ```
pub fn device_base_name_from_number(device_number: u64) -> Result<Disk, MiscError> {
    log::debug!(
        "misc::device_base_name_from_number getting whole disk name from device number {:?}",
        device_number
    );

    let mut disk_name_buffer: Vec<libc::c_char> = vec![0; MAX_FILE_PATH_LENGTH];
    let mut disk_device_number = MaybeUninit::<u64>::zeroed();

    let result = unsafe {
        libblkid::blkid_devno_to_wholedisk(
            device_number,
            disk_name_buffer.as_mut_ptr(),
            MAX_FILE_PATH_LENGTH,
            disk_device_number.as_mut_ptr(),
        )
    };

    match result {
        0 => {
            let disk_name = ffi_utils::c_char_array_to_string(disk_name_buffer.as_ptr());
            let disk_device_number = unsafe { disk_device_number.assume_init() };

            log::debug!(
                "misc::device_base_name_from_number got whole disk name {:?}",
                disk_name
            );

            Ok(Disk::new(disk_name, disk_device_number))
        }
        code => {
            let err_msg = format!(
                "error getting whole disk name from device number: {}",
                device_number
            );
            log::debug!("misc::device_base_name_from_number {}. libblkid::blkid_devno_to_wholedisk returned error code {:?}", err_msg, code);

            Err(MiscError::Conversion(err_msg))
        }
    }
}