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. |
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(result:sys::get_path(path.as_ref(), name.as_ref())) |
50 | } |
51 | |
52 | /// Set an extended attribute on the specified file. |
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. |
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. |
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. |
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 | |
116 | impl FileExt for File {} |
117 | |