Crate xattrs

Expand description

§Extended file attributes (aka “xattrs”) operations

This crate provides a cross-platform way to access xattrs. If you are unfamiliar with xattrs, a general overview can be found in manual. The supported platforms are currently Linux, NetBSD, FreeBSD and MacOS.

Normally you will only be interested in user xattrs. There is a high-level API in user which includes extension traits that add xattr-related operations to paths and file descriptors:

use std::path::Path;
use xattrs::PathExt as _;

fn dump_xattrs(path: &Path) -> xattrs::Result<()> {
    let xattrs = path.read_xattrs()?; // Reading attribute list can fail on I/O
    for kv in &xattrs {
        let (name, value) = kv?; // reading an attribute can fail on I/O
        println!("{name:?} -> {value:?}");
    }
    Ok(())
}

For advanced use, such as operations on non-user xattrs, or where you want to minimise allocations and copies, there is the “plumbing” module [pb]. Note that non-user xattrs tend to be very platform specific and so your code will not be directly portable without #[cfg(target_os=…)]. The benefit of this crate in such cases is mainly to provide a safe checked API atop the underlying unsafe libc calls.

There is also an xattr crate. I started writing (but did not release) xattrs before that one was released, but have decided to release this anyway as it has a lot more functionality and supports more platforms, and automatically handles prepending “user.” to xattr names on Linux but omits it on other platforms. However, if you are happy with xattr then there’s no need to switch.

Modules§

manual: FAQ about extended file attributes.
prelude: Useful re-exports from this crate.
types: Basic data types and conversions.
user: User-friendly extension traits and types.

Enums§

Error: xattrs’ error type.

Traits§

FileExt: Extension trait which adds xattr-related methods to file handle types.
PathExt: Extension trait which adds xattr-related methods to path types.

Functions§

file_get_xattr: Gets an xattr’s value for a file handle.
file_list_xattr: Gets the xattr names for a file handle.
file_remove_xattr: Removes an xattr from a file handle.
file_set_xattr: Sets an xattr on a file handle.
get_xattr: Gets an xattr’s value for a path, following symlinks.
list_xattr: Gets the xattr names for a path, following symlinks.
path_fd: Gets a file descriptor for the path, following symlinks. This file descriptor is opened with special flags and is only useful for xattr-related operations.
remove_xattr: Removes an xattr from a path, following symlinks.
set_xattr: Sets an xattr on a path, following symlinks.
symlink_get_xattr: Gets an xattr’s value for a path, without following symlinks.
symlink_list_xattr: Gets the xattr names for a path, without following symlinks.
symlink_path_fd: Gets a file descriptor for the path, without following symlinks. This file descriptor is opened with special flags and is only useful for xattr-related operations.
symlink_remove_xattr: Removes an xattr from a path, without following symlinks.
symlink_set_xattr: Sets an xattr on a path, without following symlinks.

Type Aliases§

Result: xattrs’ result type.