Struct HomeDirs 

pub struct HomeDirs { /* private fields */ }

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

Common user directory paths used for user-specific application files.

It is not required that the user directories are accessible by the current user, nor that there is a directory at that path. A robust application should handle the case where user directories are incorrectly configured.

Even when configured correctly, multiple paths may point to the same location. You should not assume that a file written relative to one directory will not conflict with the same relative path in a different home directory.

Platform-specific behavior

As the filesystem conventions for discovering directories varies between operating systems, constructors for HomeDirs that use the host platform’s conventions are provided as extension traits under the std::os module.

Implementations

impl HomeDirs

pub fn empty() -> Self

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

Create a known user directory set with no known directories.

This is useful with the builder set_* methods to create a HomeDirs with exactly the directories you want, without any other defaults.

pub fn cache_home(&self) -> Option<&Path>

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

A base directory relative to which user-specific non-essential cache data files should be stored.

“Cache” files are temporary data that can be used to cache redundant work of an application, but which can be discarded arbitrarily and recreated as necessary. Files in this directory may potentially be automatically purged any time they are not currently open, or they may not, depending on system configuration. A robust application should ensure that its caches do not grow without a reasonable bound.

This is the same directory for all applications. Applications should use a subdirectory for application-specific cache files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	${XDG_CACHE_HOME:-$HOME/.cache}
Darwin (macOS)	NSCachesDirectory ($HOME/Library/Caches)
Windows	{FOLDERID_LocalAppData} (%LOCALAPPDATA%)

Other paths can be configured via set_cache_home.

pub fn config_home(&self) -> Option<&Path>

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

A base directory relative to which user-specific configuration files should be stored.

“Config” files are configuration managed by the user, either by editing the files directly or through a managing application. Configuration is generally expected to be meaningful to the user and portable enough to back up and synchronize across the same user’s account on multiple systems.

This is the same directory for all applications. Applications should use a subdirectory for application-specific configuration files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	${XDG_CONFIG_HOME:-$HOME/.config}
Darwin (macOS)	NSApplicationSupportDirectory ($HOME/Library/Application Support)
Windows	{FOLDERID_RoamingAppData} (%APPDATA%)

Other paths can be configured via set_config_home.

pub fn data_home(&self) -> Option<&Path>

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

A base directory relative to which user-specific data files should be stored.

“Data” files are application-specific data that is meaningful to the user in some way and does not implicitly rely on system configuration or details of how the application is installed otherwise irrelevant to the user. As such, data makes sense to back up and synchronize between the same user’s account on multiple systems. If a file is specific to a single machine, it’s probably state.

This is the same directory for all applications. Applications should use a subdirectory for application-specific data files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	${XDG_DATA_HOME:-$HOME/.local/share}
Darwin (macOS)	NSApplicationSupportDirectory ($HOME/Library/Application Support)
Windows	{FOLDERID_RoamingAppData} (%APPDATA%)

Other paths can be configured via set_data_home.

pub fn state_home(&self) -> Option<&Path>

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

A base directory relative to which user-specific state files should be stored.

“State” files are data that should persist between application restarts, but which is not important nor portable enough to the user to synchronize between multiple systems like data are. Common examples include history (such as logs, recently used files, etc) and any current state of the application that should be reused (such as view, layout, open files, undo history, etc).

This is the same directory for all applications. Applications should use a subdirectory for application-specific state files.

Platform-specific behavior

When constructed using platform-specific conventions, the value is:

OS	Path
XDG (Linux)	${XDG_STATE_HOME:-$HOME/.local/state}
Darwin (macOS)	NSApplicationSupportDirectory ($HOME/Library/Application Support)
Windows	{FOLDERID_LocalAppData} (%LOCALAPPDATA%)

Other paths can be configured via set_state_home.

impl HomeDirs

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

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

Set the path for Self::cache_home.

Panics

Panics if the provided path is not absolute.

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

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

Set the path for Self::config_home.

Panics

Panics if the provided path is not absolute.

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

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

Set the path for Self::data_home.

Panics

Panics if the provided path is not absolute.

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

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

Set the path for Self::state_home.

Panics

Panics if the provided path is not absolute.

Trait Implementations

impl Clone for HomeDirs

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for HomeDirs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HomeDirsExt for HomeDirs

Available on Unix only.

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.

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.

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.

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.

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.

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.

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.