Trait HomeDirsExt 

pub trait HomeDirsExt: Sized {
    // Required methods
    fn xdg() -> Result<Self>;
    fn runtime_home(&self) -> Option<&Path>;
    fn config_dirs(&self) -> Option<XdgDirs<'_>>;
    fn data_dirs(&self) -> Option<XdgDirs<'_>>;
    fn set_runtime_home(&mut self, path: PathBuf) -> &mut Self;
    fn set_config_dirs(&mut self, paths: OsString) -> &mut Self;
    fn set_data_dirs(&mut self, paths: OsString) -> &mut Self;
}

ⓘ This trait cannot be implemented outside std.

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Available on Unix only.

XDG-specific extensions to fs::HomeDirs.

The XDG conventions are defined by the Freedesktop.org project in the XDG Base Directory Specification. These conventions have been largely adopted by Linux distributions.

The XDG conventions are written to be usable on any Unix-like filesystem, thus this extension being provided in os::unix rather than os::linux. However, while some tooling does use XDG conventions on macOS, note that macOS has its own separate conventions for user directories. Consider carefully what conventions your users will expect your application to follow along with any legacy path compatibility you might need to support.

Required Methods

fn xdg() -> Result<Self>

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Load the user directory paths according to the XDG Base Directory Specification.

Each base directory path is set to the value of its corresponding XDG_* environment variable (if it is set and non-empty), else to the default value defined by the specification.

Field	Environment Variable	Default Value
cache_home	XDG_CACHE_HOME	$HOME/.cache
config_home	XDG_CONFIG_HOME	$HOME/.config
data_home	XDG_DATA_HOME	$HOME/.local/share
state_home	XDG_STATE_HOME	$HOME/.local/state
runtime_home	XDG_RUNTIME_DIR	(see method docs)
config_dirs	XDG_CONFIG_DIRS	/etc/xdg
data_dirs	XDG_DATA_DIRS	/usr/local/share/, /usr/share/

Note that $HOME here means env::home_dir, which uses $HOME if set and non-empty, but falls back to the system password database if it isn’t set.

All paths are required to be absolute. If a relative path is configured by the environment, it is ignored and the default value is used instead.

config_dirs and data_dirs are a list of delimited paths using the env::split_paths delimiter. If some but not all paths in the list are relative, those relative paths are ignored and the remaining absolute paths are used. If there are no valid absolute paths, the default value is used instead.

Errors

Errors if the user’s home directory cannot be determined.

fn runtime_home(&self) -> Option<&Path>

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

A base directory relative to which user-specific runtime files (such as sockets, named pipes, etc) should be stored.

Files in this directory may be subjected to periodic clean-up. Larger files should not be placed here, since it might reside in runtime memory and cannot necessarily be swapped out to disk.

This path does not have a default if not set. If it isn’t set, applications should fall back to a replacement directory with similar capabilities and print a warning message.

fn config_dirs(&self) -> Option<XdgDirs<'_>>

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

A preference-ordered list of base directories to search for config files in addition to config_home.

The order of directories denotes their importance; the first directory is the most important. Information defined relative to the more important base directory takes precedent. config_home is not necessarily present in this list, and is considered more important than any base directory in this list.

fn data_dirs(&self) -> Option<XdgDirs<'_>>

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

A preference-ordered list of base directories to search for data files in addition to data_home.

The order of directories denotes their importance; the first directory is the most important. Information defined relative to the more important base directory takes precedent. data_home is not necessarily present in this list, and is considered more important than any base directory in this list.

fn set_runtime_home(&mut self, path: PathBuf) -> &mut Self

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Set the path for Self::runtime_home.

Panics

Panics if the provided path is not absolute.

fn set_config_dirs(&mut self, paths: OsString) -> &mut Self

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Set the paths for Self::config_dirs.

Takes one or more paths joined appropriately for the PATH environment variable, as by env::join_paths.

Panics

Panics if any of the provided paths are not absolute.

fn set_data_dirs(&mut self, paths: OsString) -> &mut Self

🔬This is a nightly-only experimental API. (fs_home_dirs #162082)

Set the paths for Self::data_dirs.

Takes one or more paths joined appropriately for the PATH environment variable, as by env::join_paths.

Panics

Panics if any of the provided paths are not absolute.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl HomeDirsExt for HomeDirs