public static partial class Environment
private static string GetFolderPathCore(SpecialFolder folder, SpecialFolderOption option)
// Get the path for the SpecialFolder
string path = GetFolderPathCoreWithoutValidation(folder) ?? string.Empty;
Debug.Assert(path != null);
// If we didn't get one, or if we got one but we're not supposed to verify it,
// or if we're supposed to verify it and it passes verification, return the path.
option == SpecialFolderOption.DoNotVerify ||
Interop.Sys.Access(path, Interop.Sys.AccessMode.R_OK) == 0)
// Failed verification. If None, then we're supposed to return an empty string.
// If Create, we're supposed to create it and then return the path.
if (option == SpecialFolderOption.None)
Debug.Assert(option == SpecialFolderOption.Create);
Directory.CreateDirectory(path);
private static string? GetFolderPathCoreWithoutValidation(SpecialFolder folder)
// First handle any paths that involve only static paths, avoiding the overheads of getting user-local paths.
// https://www.freedesktop.org/software/systemd/man/file-hierarchy.html
case SpecialFolder.CommonApplicationData: return "/usr/share";
case SpecialFolder.CommonTemplates: return "/usr/share/templates";
case SpecialFolder.ProgramFiles: return "/Applications";
case SpecialFolder.System: return "/System";
// All other paths are based on the XDG Base Directory Specification:
// https://specifications.freedesktop.org/basedir-spec/latest/
home = PersistedFiles.GetHomeDirectory();
Debug.Fail($"Unable to get home directory: {exc}");
// Fall back to '/' when we can't determine the home directory.
// This location isn't writable by non-root users which provides some safeguard
// that the application doesn't write data which is meant to be private.
if (string.IsNullOrEmpty(home))
// TODO: Consider caching (or precomputing and caching) all subsequent results.
// This would significantly improve performance for repeated access, at the expense
// of not being responsive to changes in the underlying environment variables,
// configuration files, etc.
case SpecialFolder.UserProfile:
case SpecialFolder.Templates:
return ReadXdgDirectory(home, "XDG_TEMPLATES_DIR", "Templates");
// TODO: Consider merging the OSX path with the rest of the Apple systems here:
// https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Environment.iOS.cs
case SpecialFolder.Desktop:
case SpecialFolder.DesktopDirectory:
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSDesktopDirectory);
case SpecialFolder.ApplicationData:
case SpecialFolder.LocalApplicationData:
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSApplicationSupportDirectory);
case SpecialFolder.MyDocuments: // same value as Personal
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSDocumentDirectory);
case SpecialFolder.MyMusic:
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSMusicDirectory);
case SpecialFolder.MyVideos:
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSMoviesDirectory);
case SpecialFolder.MyPictures:
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSPicturesDirectory);
case SpecialFolder.Fonts:
return Path.Combine(home, "Library", "Fonts");
case SpecialFolder.Favorites:
return Path.Combine(home, "Library", "Favorites");
case SpecialFolder.InternetCache:
return Interop.Sys.SearchPath(NSSearchPathDirectory.NSCachesDirectory);
case SpecialFolder.Desktop:
case SpecialFolder.DesktopDirectory:
return ReadXdgDirectory(home, "XDG_DESKTOP_DIR", "Desktop");
case SpecialFolder.ApplicationData:
return GetXdgConfig(home);
case SpecialFolder.LocalApplicationData:
// "$XDG_DATA_HOME defines the base directory relative to which user specific data files should be stored."
// "If $XDG_DATA_HOME is either not set or empty, a default equal to $HOME/.local/share should be used."
string? data = GetEnvironmentVariable("XDG_DATA_HOME");
if (data is null || !data.StartsWith('/'))
data = Path.Combine(home, ".local", "share");
case SpecialFolder.MyDocuments: // same value as Personal
return ReadXdgDirectory(home, "XDG_DOCUMENTS_DIR", "Documents");
case SpecialFolder.MyMusic:
return ReadXdgDirectory(home, "XDG_MUSIC_DIR", "Music");
case SpecialFolder.MyVideos:
return ReadXdgDirectory(home, "XDG_VIDEOS_DIR", "Videos");
case SpecialFolder.MyPictures:
return ReadXdgDirectory(home, "XDG_PICTURES_DIR", "Pictures");
case SpecialFolder.Fonts:
return Path.Combine(home, ".fonts");
// No known path for the SpecialFolder
private static string GetXdgConfig(string home)
// "$XDG_CONFIG_HOME defines the base directory relative to which user specific configuration files should be stored."
// "If $XDG_CONFIG_HOME is either not set or empty, a default equal to $HOME/.config should be used."
string? config = GetEnvironmentVariable("XDG_CONFIG_HOME");
if (config is null || !config.StartsWith('/'))
config = Path.Combine(home, ".config");
private static string ReadXdgDirectory(string homeDir, string key, string fallback)
Debug.Assert(!string.IsNullOrEmpty(homeDir), $"Expected non-empty homeDir");
Debug.Assert(!string.IsNullOrEmpty(key), $"Expected non-empty key");
Debug.Assert(!string.IsNullOrEmpty(fallback), $"Expected non-empty fallback");
string? envPath = GetEnvironmentVariable(key);
if (envPath is not null && envPath.StartsWith('/'))
// Use the user-dirs.dirs file to look up the right config.
// Note that the docs also highlight a list of directories in which to look for this file:
// "$XDG_CONFIG_DIRS defines the preference-ordered set of base directories to search for configuration files in addition
// to the $XDG_CONFIG_HOME base directory. The directories in $XDG_CONFIG_DIRS should be separated with a colon ':'. If
// $XDG_CONFIG_DIRS is either not set or empty, a value equal to / etc / xdg should be used."
// For simplicity, we don't currently do that. We can add it if/when necessary.
string userDirsPath = Path.Combine(GetXdgConfig(homeDir), "user-dirs.dirs");
if (Interop.Sys.Access(userDirsPath, Interop.Sys.AccessMode.R_OK) == 0)
using (var reader = new StreamReader(userDirsPath))
while ((line = reader.ReadLine()) != null)
// XDG_DESKTOP_DIR="$HOME/Desktop"
// XDG_PICTURES_DIR = "/absolute/path"
// Skip past whitespace at beginning of line
SkipWhitespace(line, ref pos);
if (pos >= line.Length) continue;
// Skip past requested key name
if (string.CompareOrdinal(line, pos, key, 0, key.Length) != 0) continue;
// Skip past whitespace and past '='
SkipWhitespace(line, ref pos);
if (pos >= line.Length - 4 || line[pos] != '=') continue; // 4 for ="" and at least one char between quotes
// Skip past whitespace and past first quote
SkipWhitespace(line, ref pos);
if (pos >= line.Length - 3 || line[pos] != '"') continue; // 3 for "" and at least one char between quotes
pos++; // skip past opening '"'
// Skip past relative prefix if one exists
bool relativeToHome = false;
const string RelativeToHomePrefix = "$HOME/";
if (string.CompareOrdinal(line, pos, RelativeToHomePrefix, 0, RelativeToHomePrefix.Length) == 0)
pos += RelativeToHomePrefix.Length;
else if (line[pos] != '/') // if not relative to home, must be absolute path
int endPos = line.IndexOf('"', pos);
if (endPos <= pos) continue;
// Got we need. Now extract it.
string path = line.Substring(pos, endPos - pos);
Path.Combine(homeDir, path) :
// assembly not found, file not found, errors reading file, etc. Just eat everything.
Debug.Fail($"Failed reading {userDirsPath}: {exc}");
return Path.Combine(homeDir, fallback);
private static void SkipWhitespace(string line, ref int pos)
while (pos < line.Length && char.IsWhiteSpace(line[pos])) pos++;