Struct directories::BaseDirs

pub struct BaseDirs { /* fields omitted */ }

BaseDirs provides paths of user-invisible standard directories, following the conventions of the operating system the library is running on.

To compute the location of cache, config or data directories for individual projects or applications, use ProjectDirs instead.

Examples

All examples on this page are computed with a user named Alice.

use directories::BaseDirs;
if let Some(base_dirs) = BaseDirs::new() {
    base_dirs.config_dir();
    // Linux:   /home/alice/.config
    // Windows: C:\Users\Alice\AppData\Roaming
    // macOS:   /Users/Alice/Library/Application Support
}

Implementations

impl BaseDirs

pub fn new() -> Option<BaseDirs>

Creates a BaseDirs struct which holds the paths to user-invisible directories for cache, config, etc. data on the system.

The returned value depends on the operating system and is either

• Some, containing a snapshot of the state of the system’s paths at the time new() was invoked, or
• None, if no valid home directory path could be retrieved from the operating system.

To determine whether a system provides a valid $HOME path, the following rules are applied:

Linux and macOS:

• Use $HOME if it is set and not empty.
• If $HOME is not set or empty, then the function getpwuid_r is used to determine the home directory of the current user.
• If getpwuid_r lacks an entry for the current user id or the home directory field is empty, then the function returns None.

Windows:

• Retrieve the user profile folder using SHGetKnownFolderPath.
• If this fails, then the function returns None.

Note: This logic differs from std::env::home_dir, which works incorrectly on Linux, macOS and Windows.

pub fn home_dir(&self) -> &Path

Returns the path to the user’s home directory.

Platform	Value	Example
Linux	$HOME	/home/alice
macOS	$HOME	/Users/Alice
Windows	{FOLDERID_Profile}	C:\Users\Alice

pub fn cache_dir(&self) -> &Path

Returns the path to the user’s cache directory.

Platform	Value	Example
Linux	$XDG_CACHE_HOME or $HOME/.cache	/home/alice/.cache
macOS	$HOME/Library/Caches	/Users/Alice/Library/Caches
Windows	{FOLDERID_LocalAppData}	C:\Users\Alice\AppData\Local

pub fn config_dir(&self) -> &Path

Returns the path to the user’s config directory.

Platform	Value	Example
Linux	$XDG_CONFIG_HOME or $HOME/.config	/home/alice/.config
macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support
Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming

pub fn data_dir(&self) -> &Path

Returns the path to the user’s data directory.

Platform	Value	Example
Linux	$XDG_DATA_HOME or $HOME/.local/share	/home/alice/.local/share
macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support
Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming

pub fn data_local_dir(&self) -> &Path

Returns the path to the user’s local data directory.

Platform	Value	Example
Linux	$XDG_DATA_HOME or $HOME/.local/share	/home/alice/.local/share
macOS	$HOME/Library/Application Support	/Users/Alice/Library/Application Support
Windows	{FOLDERID_LocalAppData}	C:\Users\Alice\AppData\Local

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

Returns the path to the user’s executable directory.

Platform	Value	Example
Linux	$XDG_BIN_HOME or $XDG_DATA_HOME/../bin or $HOME/.local/bin	/home/alice/.local/bin
macOS	–	–
Windows	–	–

pub fn preference_dir(&self) -> &Path

Returns the path to the user’s preference directory.

Platform	Value	Example
Linux	$XDG_CONFIG_HOME or $HOME/.config	/home/alice/.config
macOS	$HOME/Library/Preferences	/Users/Alice/Library/Preferences
Windows	{FOLDERID_RoamingAppData}	C:\Users\Alice\AppData\Roaming

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

Returns the path to the user’s runtime directory.

Platform	Value	Example
Linux	$XDG_RUNTIME_DIR	/run/user/1001/
macOS	–	–
Windows	–	–

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

Returns the path to the user’s state directory.

The state directory contains data that should be retained between sessions (unlike the runtime directory), but may not be important/portable enough to be synchronized across machines (unlike the config/preferences/data directories).

The returned value depends on the operating system and is either a Some, containing a value from the following table, or a None.

Platform	Value	Example
Linux	$XDG_STATE_HOME or $HOME/.local/state	/home/alice/.local/state
macOS	–	–
Windows	–	–

Trait Implementations

impl Clone for BaseDirs

fn clone(&self) -> BaseDirs

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BaseDirs

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

Formats the value using the given formatter.