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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219

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

//! Top-level API for `LABEL` and `UUID` evaluation.

// From dependency library

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

// From this library
use crate::core::device::Tag;
use crate::core::device::TagName;
use crate::ffi_utils;

/// Returns the name of the first device with a matching `tag`. This function returns `None`,
/// if no device matching the given `tag` was found.
///
/// **Note:** Only [`Tag`]s with tag name [`TagName::Label`] and [`TagName::Uuid`] are
/// accepted; this method will return `None` if provided any other type of tag.
///
/// # Examples
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use std::path::PathBuf;
/// use rsblkid::device::Tag;
/// use rsblkid::utils::evaluation;
///
/// fn main() -> rsblkid::Result<()> {
///
///     let label: Tag = "LABEL='nixos'".parse()?;
///     let actual = evaluation::find_device_name_from_tag(&label);
///     let device_name = PathBuf::from("/dev/vda");
///     let expected = Some(device_name);
///
///     assert_eq!(actual, expected);
///
///     Ok(())
/// }
/// ```
pub fn find_device_name_from_tag(tag: &Tag) -> Option<PathBuf> {
    // Only the `LABEL` and `UUID` tags are supported.
    if !matches!(tag.name(), TagName::Label) && !matches!(tag.name(), TagName::Uuid) {
        return None;
    }

    let key_cstr = tag.name().to_c_string();
    let value_cstr = tag.value_to_c_string().ok()?;

    log::debug!(
        "core::utils::evaluation::find_device_name_from_tag getting device name from tag: {:?}",
        tag
    );

    let mut device_name_ptr = MaybeUninit::<*mut libc::c_char>::zeroed();

    unsafe {
        device_name_ptr.write(libblkid::blkid_evaluate_tag(
            key_cstr.as_ptr(),
            value_cstr.as_ptr(),
            std::ptr::null_mut(),
        ));
    }

    match unsafe { device_name_ptr.assume_init() } {
        ptr if ptr.is_null() => {
            let err_msg = format!("failed to get device name from matching tag: {:?}", tag);
            log::debug!("core::utils::evaluation::find_device_name_from_tag {}. libblkid::blkid_evaluate_tag returned a NULL pointer", err_msg);

            None
        }
        ptr => {
            let name = ffi_utils::const_c_char_array_to_path_buf(ptr);
            log::debug!(
                "core::utils::evaluation::find_device_name_from_tag found device named {:?}",
                name
            );

            // Release memory allocated by `libblkid` to avoid memory leaks.
            unsafe {
                libc::free(ptr as *mut _);
            }

            Some(name)
        }
    }
}

#[doc(hidden)]
/// Returns the canonical name of the first device matching the given `spec`, which is
/// either a [`Tag`] or a [`Path`] as a [`CString`]. A canonicalized device name is an absolute
/// path to the device where all symlinks are resolved; device-mapper paths are converted to
/// the `/dev/mapper/name` format.
fn device_name_from_spec(spec: CString) -> Option<PathBuf> {
    log::debug!(
        "core::utils::evaluation::device_name_from_spec getting device name from spec {:?}",
        spec
    );

    let mut device_name_ptr = MaybeUninit::<*mut libc::c_char>::zeroed();

    unsafe {
        device_name_ptr.write(libblkid::blkid_evaluate_spec(
            spec.as_ptr(),
            std::ptr::null_mut(),
        ));
    };

    match unsafe { device_name_ptr.assume_init() } {
        ptr if ptr.is_null() => {
            let err_msg = format!("failed to get device name from spec {:?}", spec);
            log::debug!("core::utils::evaluation::device_name_from_spec {}. libblkid::blkid_evaluate_spec returned a NULL pointer", err_msg);

            None
        }
        ptr => {
            let name = ffi_utils::const_c_char_array_to_path_buf(ptr);
            // Release memory allocated by `libblkid` to avoid memory leaks.
            unsafe {
                libc::free(ptr as *mut _);
            }

            log::debug!(
                "core::utils::evaluation::device_name_from_spec found device named {:?}",
                name
            );

            Some(name)
        }
    }
}

/// Returns the canonical name of the first device with a matching `tag`. A canonicalized
/// device name is an absolute path to the device where all symlinks are resolved;
/// device-mapper paths are converted to the `/dev/mapper/name` format. This function returns
/// `None`, if no device matching the given `tag` was found.
///
/// **Note:** Only [`Tag`]s with tag name [`TagName::Label`] and [`TagName::Uuid`] are
/// accepted; this method will return `None` if provided any other type of tag.
///
/// # Examples
/// ----
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use std::path::PathBuf;
/// use rsblkid::device::Tag;
/// use rsblkid::utils::evaluation;
///
/// fn main() -> rsblkid::Result<()> {
///     let label: Tag = r#"UUID="ac4f36bf-191b-4fb0-b808-6d7fc9fc88be""#.parse()?;
///     let actual = evaluation::find_canonical_device_name_from_tag(&label);
///     let device_name = PathBuf::from("/dev/vda");
///     let expected = Some(device_name);
///
///     assert_eq!(actual, expected);
///
///     Ok(())
/// }
/// ```
pub fn find_canonical_device_name_from_tag(tag: &Tag) -> Option<PathBuf> {
    log::debug!(
        "Cache::find_canonical_device_name_from_tag getting device name matching tag {:?}",
        tag
    );

    // Only the `LABEL` and `UUID` tags are supported.
    if !matches!(tag.name(), TagName::Label) && !matches!(tag.name(), TagName::Uuid) {
        return None;
    }

    let tag_cstr = tag.to_c_string().ok()?;

    device_name_from_spec(tag_cstr)
}

/// Returns the canonical name of the first device matching the given `path`. A canonicalized
/// device name is an absolute path to the device where all symlinks are resolved;
/// device-mapper paths are converted to the `/dev/mapper/name` format. This function returns
/// `None`, if no device matching the given `path` was found.
///
/// # Examples
/// ----
///
/// ```ignore
/// # use pretty_assertions::assert_eq;
/// use std::path::PathBuf;
/// use rsblkid::device::Tag;
/// use rsblkid::utils::evaluation;
///
/// fn main() -> rsblkid::Result<()> {
///     let path = "/dev/disk/by-uuid/ac4f36bf-191b-4fb0-b808-6d7fc9fc88be";
///     let actual = evaluation::find_canonical_device_name_from_path(path);
///     let device_name = PathBuf::from("/dev/vda");
///     let expected = Some(device_name);
///
///     assert_eq!(actual, expected);
///
///     Ok(())
/// }
/// ```
pub fn find_canonical_device_name_from_path<T>(path: T) -> Option<PathBuf>
where
    T: AsRef<Path>,
{
    let path = path.as_ref();
    log::debug!(
            "core::utils::evaluation::find_canonical_device_name_from_path getting device name from path {:?}",
            path
        );

    let path_cstr = ffi_utils::as_ref_path_to_c_string(path).ok()?;

    device_name_from_spec(path_cstr)
}