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
28 extern crate libc;
29
30 mod error;
31 mod sys;
32 mod util;
33
34 use std::ffi::OsStr;
35 use std::fs::File;
36 use std::io;
37 use std::os::unix::io::AsRawFd;
38 use std::path::Path;
39
40 pub use error::UnsupportedPlatformError;
41 pub use sys::{XAttrs, SUPPORTED_PLATFORM};
42
43 /// Get an extended attribute for the specified file.
get<N, P>(path: P, name: N) -> io::Result<Option<Vec<u8>>> where P: AsRef<Path>, N: AsRef<OsStr>,44 pub fn get<N, P>(path: P, name: N) -> io::Result<Option<Vec<u8>>>
45 where
46 P: AsRef<Path>,
47 N: AsRef<OsStr>,
48 {
49 util::extract_noattr(sys::get_path(path.as_ref(), name.as_ref()))
50 }
51
52 /// Set an extended attribute on the specified file.
set<N, P>(path: P, name: N, value: &[u8]) -> io::Result<()> where P: AsRef<Path>, N: AsRef<OsStr>,53 pub fn set<N, P>(path: P, name: N, value: &[u8]) -> io::Result<()>
54 where
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.
remove<N, P>(path: P, name: N) -> io::Result<()> where P: AsRef<Path>, N: AsRef<OsStr>,62 pub fn remove<N, P>(path: P, name: N) -> io::Result<()>
63 where
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.
list<P>(path: P) -> io::Result<XAttrs> where P: AsRef<Path>,74 pub fn list<P>(path: P) -> io::Result<XAttrs>
75 where
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.
82 pub trait FileExt: AsRawFd {
83 /// Get an extended attribute for the specified file.
get_xattr<N>(&self, name: N) -> io::Result<Option<Vec<u8>>> where N: AsRef<OsStr>,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.
set_xattr<N>(&self, name: N, value: &[u8]) -> io::Result<()> where N: AsRef<OsStr>,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.
remove_xattr<N>(&self, name: N) -> io::Result<()> where N: AsRef<OsStr>,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.
list_xattr(&self) -> io::Result<XAttrs>111 fn list_xattr(&self) -> io::Result<XAttrs> {
112 sys::list_fd(self.as_raw_fd())
113 }
114 }
115
116 impl FileExt for File {}
117