1//! A pure-Rust library to manage extended attributes.
2//!
3//! It provides support for manipulating extended attributes
4//! (`xattrs`) on modern Unix filesystems. See the `attr(5)`
5//! manpage for more details.
6//!
7//! An extension trait [`FileExt`](::FileExt) is provided to directly work with
8//! standard `File` objects and file descriptors.
9//!
10//! NOTE: In case of a symlink as path argument, all methods
11//! in this library work on the symlink itself **without**
12//! de-referencing it.
13//!
14//! ```rust
15//! let mut xattrs = xattr::list("/").unwrap().peekable();
16//!
17//! if xattrs.peek().is_none() {
18//! println!("no xattr set on root");
19//! return;
20//! }
21//!
22//! println!("Extended attributes:");
23//! for attr in xattrs {
24//! println!(" - {:?}", attr);
25//! }
26//! ```
27
28extern crate libc;
29
30mod error;
31mod sys;
32mod util;
33
34use std::ffi::OsStr;
35use std::fs::File;
36use std::io;
37use std::os::unix::io::AsRawFd;
38use std::path::Path;
39
40pub use error::UnsupportedPlatformError;
41pub use sys::{XAttrs, SUPPORTED_PLATFORM};
42
43/// Get an extended attribute for the specified file.
44pub fn get<N, P>(path: P, name: N) -> io::Result<Option<Vec<u8>>>
45where
46 P: AsRef<Path>,
47 N: AsRef<OsStr>,
48{
49 util::extract_noattr(result:sys::get_path(path.as_ref(), name.as_ref()))
50}
51
52/// Set an extended attribute on the specified file.
53pub fn set<N, P>(path: P, name: N, value: &[u8]) -> io::Result<()>
54where
55 P: AsRef<Path>,
56 N: AsRef<OsStr>,
57{
58 sys::set_path(path.as_ref(), name.as_ref(), value)
59}
60
61/// Remove an extended attribute from the specified file.
62pub fn remove<N, P>(path: P, name: N) -> io::Result<()>
63where
64 P: AsRef<Path>,
65 N: AsRef<OsStr>,
66{
67 sys::remove_path(path.as_ref(), name.as_ref())
68}
69
70/// List extended attributes attached to the specified file.
71///
72/// Note: this may not list *all* attributes. Speficially, it definitely won't list any trusted
73/// attributes unless you are root and it may not list system attributes.
74pub fn list<P>(path: P) -> io::Result<XAttrs>
75where
76 P: AsRef<Path>,
77{
78 sys::list_path(path.as_ref())
79}
80
81/// Extension trait to manipulate extended attributes on `File`-like objects.
82pub trait FileExt: AsRawFd {
83 /// Get an extended attribute for the specified file.
84 fn get_xattr<N>(&self, name: N) -> io::Result<Option<Vec<u8>>>
85 where
86 N: AsRef<OsStr>,
87 {
88 util::extract_noattr(sys::get_fd(self.as_raw_fd(), name.as_ref()))
89 }
90
91 /// Set an extended attribute on the specified file.
92 fn set_xattr<N>(&self, name: N, value: &[u8]) -> io::Result<()>
93 where
94 N: AsRef<OsStr>,
95 {
96 sys::set_fd(self.as_raw_fd(), name.as_ref(), value)
97 }
98
99 /// Remove an extended attribute from the specified file.
100 fn remove_xattr<N>(&self, name: N) -> io::Result<()>
101 where
102 N: AsRef<OsStr>,
103 {
104 sys::remove_fd(self.as_raw_fd(), name.as_ref())
105 }
106
107 /// List extended attributes attached to the specified file.
108 ///
109 /// Note: this may not list *all* attributes. Speficially, it definitely won't list any trusted
110 /// attributes unless you are root and it may not list system attributes.
111 fn list_xattr(&self) -> io::Result<XAttrs> {
112 sys::list_fd(self.as_raw_fd())
113 }
114}
115
116impl FileExt for File {}
117