Coverage Report

Created: 2025-07-18 06:03

/rust/registry/src/index.crates.io-6f17d22bba15001f/rustix-1.0.8/src/fs/xattr.rs
Line
Count
Source (jump to first uncovered line)
1
//! Extended attribute functions.
2
3
#![allow(unsafe_code)]
4
5
use crate::buffer::Buffer;
6
use crate::{backend, ffi, io, path};
7
use backend::c;
8
use backend::fd::AsFd;
9
use bitflags::bitflags;
10
11
bitflags! {
12
    /// `XATTR_*` constants for use with [`setxattr`], and other `*setxattr`
13
    /// functions.
14
    #[repr(transparent)]
15
    #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
16
    pub struct XattrFlags: ffi::c_uint {
17
        /// `XATTR_CREATE`
18
        const CREATE = c::XATTR_CREATE as c::c_uint;
19
20
        /// `XATTR_REPLACE`
21
        const REPLACE = c::XATTR_REPLACE as c::c_uint;
22
23
        /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
24
        const _ = !0;
25
    }
26
}
27
28
/// `getxattr(path, name, value)`—Get extended filesystem attributes.
29
///
30
/// For a higher-level API to xattr functionality, see the [xattr] crate.
31
///
32
/// [xattr]: https://crates.io/crates/xattr
33
///
34
/// # References
35
///  - [Linux]
36
///  - [Apple]
37
///
38
/// [Linux]: https://man7.org/linux/man-pages/man2/getxattr.2.html
39
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getxattr.2.html
40
#[inline]
41
0
pub fn getxattr<P: path::Arg, Name: path::Arg, Buf: Buffer<u8>>(
42
0
    path: P,
43
0
    name: Name,
44
0
    mut value: Buf,
45
0
) -> io::Result<Buf::Output> {
46
0
    path.into_with_c_str(|path| {
47
0
        name.into_with_c_str(|name| {
48
            // SAFETY: `getxattr` behaves.
49
0
            let len = unsafe { backend::fs::syscalls::getxattr(path, name, value.parts_mut())? };
50
            // SAFETY: `getxattr` behaves.
51
0
            unsafe { Ok(value.assume_init(len)) }
52
0
        })
Unexecuted instantiation: rustix::fs::xattr::getxattr::<&std::path::Path, &std::ffi::os_str::OsStr, &mut [u8]>::{closure#0}::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::getxattr::<_, _, _>::{closure#0}::{closure#0}
53
0
    })
Unexecuted instantiation: rustix::fs::xattr::getxattr::<&std::path::Path, &std::ffi::os_str::OsStr, &mut [u8]>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::getxattr::<_, _, _>::{closure#0}
54
0
}
Unexecuted instantiation: rustix::fs::xattr::getxattr::<&std::path::Path, &std::ffi::os_str::OsStr, &mut [u8]>
Unexecuted instantiation: rustix::fs::xattr::getxattr::<_, _, _>
55
56
/// `lgetxattr(path, name, value.as_ptr(), value.len())`—Get extended
57
/// filesystem attributes, without following symlinks in the last path
58
/// component.
59
///
60
/// # References
61
///  - [Linux]
62
///
63
/// [Linux]: https://man7.org/linux/man-pages/man2/lgetxattr.2.html
64
#[inline]
65
0
pub fn lgetxattr<P: path::Arg, Name: path::Arg, Buf: Buffer<u8>>(
66
0
    path: P,
67
0
    name: Name,
68
0
    mut value: Buf,
69
0
) -> io::Result<Buf::Output> {
70
0
    path.into_with_c_str(|path| {
71
0
        name.into_with_c_str(|name| {
72
            // SAFETY: `lgetxattr` behaves.
73
0
            let len = unsafe { backend::fs::syscalls::lgetxattr(path, name, value.parts_mut())? };
74
            // SAFETY: `lgetxattr` behaves.
75
0
            unsafe { Ok(value.assume_init(len)) }
76
0
        })
Unexecuted instantiation: rustix::fs::xattr::lgetxattr::<&std::path::Path, &std::ffi::os_str::OsStr, &mut [u8]>::{closure#0}::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::lgetxattr::<_, _, _>::{closure#0}::{closure#0}
77
0
    })
Unexecuted instantiation: rustix::fs::xattr::lgetxattr::<&std::path::Path, &std::ffi::os_str::OsStr, &mut [u8]>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::lgetxattr::<_, _, _>::{closure#0}
78
0
}
Unexecuted instantiation: rustix::fs::xattr::lgetxattr::<&std::path::Path, &std::ffi::os_str::OsStr, &mut [u8]>
Unexecuted instantiation: rustix::fs::xattr::lgetxattr::<_, _, _>
79
80
/// `fgetxattr(fd, name, value.as_ptr(), value.len())`—Get extended
81
/// filesystem attributes on an open file descriptor.
82
///
83
/// # References
84
///  - [Linux]
85
///  - [Apple]
86
///
87
/// [Linux]: https://man7.org/linux/man-pages/man2/fgetxattr.2.html
88
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fgetxattr.2.html
89
#[inline]
90
0
pub fn fgetxattr<Fd: AsFd, Name: path::Arg, Buf: Buffer<u8>>(
91
0
    fd: Fd,
92
0
    name: Name,
93
0
    mut value: Buf,
94
0
) -> io::Result<Buf::Output> {
95
0
    name.into_with_c_str(|name| {
96
        // SAFETY: `fgetxattr` behaves.
97
0
        let len = unsafe { backend::fs::syscalls::fgetxattr(fd.as_fd(), name, value.parts_mut())? };
98
        // SAFETY: `fgetxattr` behaves.
99
0
        unsafe { Ok(value.assume_init(len)) }
100
0
    })
Unexecuted instantiation: rustix::fs::xattr::fgetxattr::<std::os::fd::owned::BorrowedFd, &std::ffi::os_str::OsStr, &mut [u8]>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::fgetxattr::<_, _, _>::{closure#0}
101
0
}
Unexecuted instantiation: rustix::fs::xattr::fgetxattr::<std::os::fd::owned::BorrowedFd, &std::ffi::os_str::OsStr, &mut [u8]>
Unexecuted instantiation: rustix::fs::xattr::fgetxattr::<_, _, _>
102
103
/// `setxattr(path, name, value.as_ptr(), value.len(), flags)`—Set extended
104
/// filesystem attributes.
105
///
106
/// # References
107
///  - [Linux]
108
///  - [Apple]
109
///
110
/// [Linux]: https://man7.org/linux/man-pages/man2/setxattr.2.html
111
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/setxattr.2.html
112
#[inline]
113
0
pub fn setxattr<P: path::Arg, Name: path::Arg>(
114
0
    path: P,
115
0
    name: Name,
116
0
    value: &[u8],
117
0
    flags: XattrFlags,
118
0
) -> io::Result<()> {
119
0
    path.into_with_c_str(|path| {
120
0
        name.into_with_c_str(|name| backend::fs::syscalls::setxattr(path, name, value, flags))
Unexecuted instantiation: rustix::fs::xattr::setxattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::setxattr::<_, _>::{closure#0}::{closure#0}
121
0
    })
Unexecuted instantiation: rustix::fs::xattr::setxattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::setxattr::<_, _>::{closure#0}
122
0
}
Unexecuted instantiation: rustix::fs::xattr::setxattr::<&std::path::Path, &std::ffi::os_str::OsStr>
Unexecuted instantiation: rustix::fs::xattr::setxattr::<_, _>
123
124
/// `setxattr(path, name, value.as_ptr(), value.len(), flags)`—Set extended
125
/// filesystem attributes, without following symlinks in the last path
126
/// component.
127
///
128
/// # References
129
///  - [Linux]
130
///
131
/// [Linux]: https://man7.org/linux/man-pages/man2/lsetxattr.2.html
132
#[inline]
133
0
pub fn lsetxattr<P: path::Arg, Name: path::Arg>(
134
0
    path: P,
135
0
    name: Name,
136
0
    value: &[u8],
137
0
    flags: XattrFlags,
138
0
) -> io::Result<()> {
139
0
    path.into_with_c_str(|path| {
140
0
        name.into_with_c_str(|name| backend::fs::syscalls::lsetxattr(path, name, value, flags))
Unexecuted instantiation: rustix::fs::xattr::lsetxattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::lsetxattr::<_, _>::{closure#0}::{closure#0}
141
0
    })
Unexecuted instantiation: rustix::fs::xattr::lsetxattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::lsetxattr::<_, _>::{closure#0}
142
0
}
Unexecuted instantiation: rustix::fs::xattr::lsetxattr::<&std::path::Path, &std::ffi::os_str::OsStr>
Unexecuted instantiation: rustix::fs::xattr::lsetxattr::<_, _>
143
144
/// `fsetxattr(fd, name, value.as_ptr(), value.len(), flags)`—Set extended
145
/// filesystem attributes on an open file descriptor.
146
///
147
/// # References
148
///  - [Linux]
149
///  - [Apple]
150
///
151
/// [Linux]: https://man7.org/linux/man-pages/man2/fsetxattr.2.html
152
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fsetxattr.2.html
153
#[inline]
154
0
pub fn fsetxattr<Fd: AsFd, Name: path::Arg>(
155
0
    fd: Fd,
156
0
    name: Name,
157
0
    value: &[u8],
158
0
    flags: XattrFlags,
159
0
) -> io::Result<()> {
160
0
    name.into_with_c_str(|name| backend::fs::syscalls::fsetxattr(fd.as_fd(), name, value, flags))
Unexecuted instantiation: rustix::fs::xattr::fsetxattr::<std::os::fd::owned::BorrowedFd, &std::ffi::os_str::OsStr>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::fsetxattr::<_, _>::{closure#0}
161
0
}
Unexecuted instantiation: rustix::fs::xattr::fsetxattr::<std::os::fd::owned::BorrowedFd, &std::ffi::os_str::OsStr>
Unexecuted instantiation: rustix::fs::xattr::fsetxattr::<_, _>
162
163
/// `listxattr(path, list.as_ptr(), list.len())`—List extended filesystem
164
/// attributes.
165
///
166
/// # References
167
///  - [Linux]
168
///
169
/// [Linux]: https://man7.org/linux/man-pages/man2/listxattr.2.html
170
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/listxattr.2.html
171
#[inline]
172
0
pub fn listxattr<P: path::Arg, Buf: Buffer<u8>>(path: P, mut list: Buf) -> io::Result<Buf::Output> {
173
0
    path.into_with_c_str(|path| {
174
        // SAFETY: `listxattr` behaves.
175
0
        let len = unsafe { backend::fs::syscalls::listxattr(path, list.parts_mut())? };
176
        // SAFETY: `listxattr` behaves.
177
0
        unsafe { Ok(list.assume_init(len)) }
178
0
    })
Unexecuted instantiation: rustix::fs::xattr::listxattr::<&std::path::Path, &mut [u8]>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::listxattr::<_, _>::{closure#0}
179
0
}
Unexecuted instantiation: rustix::fs::xattr::listxattr::<&std::path::Path, &mut [u8]>
Unexecuted instantiation: rustix::fs::xattr::listxattr::<_, _>
180
181
/// `llistxattr(path, list.as_ptr(), list.len())`—List extended filesystem
182
/// attributes, without following symlinks in the last path component.
183
///
184
/// # References
185
///  - [Linux]
186
///
187
/// [Linux]: https://man7.org/linux/man-pages/man2/llistxattr.2.html
188
#[inline]
189
0
pub fn llistxattr<P: path::Arg, Buf: Buffer<u8>>(
190
0
    path: P,
191
0
    mut list: Buf,
192
0
) -> io::Result<Buf::Output> {
193
0
    path.into_with_c_str(|path| {
194
        // SAFETY: `flistxattr` behaves.
195
0
        let len = unsafe { backend::fs::syscalls::llistxattr(path, list.parts_mut())? };
196
        // SAFETY: `flistxattr` behaves.
197
0
        unsafe { Ok(list.assume_init(len)) }
198
0
    })
Unexecuted instantiation: rustix::fs::xattr::llistxattr::<&std::path::Path, &mut [u8]>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::llistxattr::<_, _>::{closure#0}
199
0
}
Unexecuted instantiation: rustix::fs::xattr::llistxattr::<&std::path::Path, &mut [u8]>
Unexecuted instantiation: rustix::fs::xattr::llistxattr::<_, _>
200
201
/// `flistxattr(fd, list.as_ptr(), list.len())`—List extended filesystem
202
/// attributes on an open file descriptor.
203
///
204
/// # References
205
///  - [Linux]
206
///  - [Apple]
207
///
208
/// [Linux]: https://man7.org/linux/man-pages/man2/flistxattr.2.html
209
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/flistxattr.2.html
210
#[inline]
211
0
pub fn flistxattr<Fd: AsFd, Buf: Buffer<u8>>(fd: Fd, mut list: Buf) -> io::Result<Buf::Output> {
212
    // SAFETY: `flistxattr` behaves.
213
0
    let len = unsafe { backend::fs::syscalls::flistxattr(fd.as_fd(), list.parts_mut())? };
214
    // SAFETY: `flistxattr` behaves.
215
0
    unsafe { Ok(list.assume_init(len)) }
216
0
}
Unexecuted instantiation: rustix::fs::xattr::flistxattr::<std::os::fd::owned::BorrowedFd, &mut [u8]>
Unexecuted instantiation: rustix::fs::xattr::flistxattr::<_, _>
217
218
/// `removexattr(path, name)`—Remove an extended filesystem attribute.
219
///
220
/// # References
221
///  - [Linux]
222
///  - [Apple]
223
///
224
/// [Linux]: https://man7.org/linux/man-pages/man2/removexattr.2.html
225
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/removexattr.2.html
226
0
pub fn removexattr<P: path::Arg, Name: path::Arg>(path: P, name: Name) -> io::Result<()> {
227
0
    path.into_with_c_str(|path| {
228
0
        name.into_with_c_str(|name| backend::fs::syscalls::removexattr(path, name))
Unexecuted instantiation: rustix::fs::xattr::removexattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::removexattr::<_, _>::{closure#0}::{closure#0}
229
0
    })
Unexecuted instantiation: rustix::fs::xattr::removexattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::removexattr::<_, _>::{closure#0}
230
0
}
Unexecuted instantiation: rustix::fs::xattr::removexattr::<&std::path::Path, &std::ffi::os_str::OsStr>
Unexecuted instantiation: rustix::fs::xattr::removexattr::<_, _>
231
232
/// `lremovexattr(path, name)`—Remove an extended filesystem attribute,
233
/// without following symlinks in the last path component.
234
///
235
/// # References
236
///  - [Linux]
237
///
238
/// [Linux]: https://man7.org/linux/man-pages/man2/lremovexattr.2.html
239
0
pub fn lremovexattr<P: path::Arg, Name: path::Arg>(path: P, name: Name) -> io::Result<()> {
240
0
    path.into_with_c_str(|path| {
241
0
        name.into_with_c_str(|name| backend::fs::syscalls::lremovexattr(path, name))
Unexecuted instantiation: rustix::fs::xattr::lremovexattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::lremovexattr::<_, _>::{closure#0}::{closure#0}
242
0
    })
Unexecuted instantiation: rustix::fs::xattr::lremovexattr::<&std::path::Path, &std::ffi::os_str::OsStr>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::lremovexattr::<_, _>::{closure#0}
243
0
}
Unexecuted instantiation: rustix::fs::xattr::lremovexattr::<&std::path::Path, &std::ffi::os_str::OsStr>
Unexecuted instantiation: rustix::fs::xattr::lremovexattr::<_, _>
244
245
/// `fremovexattr(fd, name)`—Remove an extended filesystem attribute on an
246
/// open file descriptor.
247
///
248
/// # References
249
///  - [Linux]
250
///  - [Apple]
251
///
252
/// [Linux]: https://man7.org/linux/man-pages/man2/fremovexattr.2.html
253
/// [Apple]: https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fremovexattr.2.html
254
0
pub fn fremovexattr<Fd: AsFd, Name: path::Arg>(fd: Fd, name: Name) -> io::Result<()> {
255
0
    name.into_with_c_str(|name| backend::fs::syscalls::fremovexattr(fd.as_fd(), name))
Unexecuted instantiation: rustix::fs::xattr::fremovexattr::<std::os::fd::owned::BorrowedFd, &std::ffi::os_str::OsStr>::{closure#0}
Unexecuted instantiation: rustix::fs::xattr::fremovexattr::<_, _>::{closure#0}
256
0
}
Unexecuted instantiation: rustix::fs::xattr::fremovexattr::<std::os::fd::owned::BorrowedFd, &std::ffi::os_str::OsStr>
Unexecuted instantiation: rustix::fs::xattr::fremovexattr::<_, _>