basedir

Documentation

Overview

Package basedir implements basedir-spec version 0.8. The specification can be read at: https://specifications.freedesktop.org/basedir-spec/0.8/

Index

• Constants
• func AllConfigDirs() ([]string, error)
• func AllDataDirs() ([]string, error)
• func CacheHome() (string, error)
• func ConfigDirs() ([]string, error)
• func ConfigHome() (string, error)
• func DataDirs() ([]string, error)
• func DataHome() (string, error)
• func ExecutableHome() (string, error)
• func RuntimeDir() (string, error)
• func StateHome() (string, error)
• func Valid(path string) error
• type Var
  • func (v Var) Value() string

Constants

const (
	// ErrEmpty indicaties a path is empty.
	ErrEmpty = basedirError("path is empty")
	// ErrNotAbs indicates a path is not absolute.
	ErrNotAbs = basedirError("path is not absolute")
)

Functions

func AllConfigDirs

func AllConfigDirs() ([]string, error)

AllConfigDirs returns the result of ConfigHome in front of ConfigDirs.

func AllDataDirs

func AllDataDirs() ([]string, error)

AllDataDirs returns the result of DataHome in front of DataDirs.

func CacheHome

func CacheHome() (string, error)

CacheHome returns the single base directory relative to which user-specific non-essential (cached) data should be written.

$XDG_CACHE_HOME defines the base directory relative to which user-specific non-essential data files should be stored. If $XDG_CACHE_HOME is either not set or empty, a default equal to $HOME/.cache is used.

func ConfigDirs

func ConfigDirs() ([]string, error)

ConfigDirs returns set of preference ordered base directories relative to which configuration files should be searched.

$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 seperated with a colon ':'. If $XDG_CONFIG_DIRS is either not set or empty, a value equal to /etc/xdg is used.

It is reccomended to call AllConfigDirs instead of ConfigDirs for most use cases.

func ConfigHome

func ConfigHome() (string, error)

ConfigHome returns the single base directory relative to which user-specific configuration files should be written.

$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 is used.

func DataDirs

func DataDirs() ([]string, error)

DataDirs returns the set of preference ordered base directories relative to which data files should be searched.

$XDG_DATA_DIRS defines the preference-ordered set of base directories to search for data files in addition to the $XDG_DATA_HOME base directory. The directories in $XDG_DATA_DIRS should be seperated with a colon ':'. If $XDG_DATA_DIRS is either not set or empty, a value equal to /usr/local/share/:/usr/share/ is used.

It is reccomended to call AllDataDirs instead of DataDirs for most use cases.

func DataHome

func DataHome() (string, error)

DataHome returns the single base directory relative to which user-specific data files should be written.

$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 is used.

func ExecutableHome

func ExecutableHome() (string, error)

ExecutableHome returns the directory in which user-specific executables may be stored, which is $HOME/.local/bin.

func RuntimeDir

func RuntimeDir() (string, error)

RuntimeDir returns the single base directory relative to which user-specific runtime files and other file objects should be placed.

$XDG_RUNTIME_DIR defines the base directory relative to which user-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...) should be stored. The directory MUST be owned by the user, and they MUST be the only one having read and write access to it. Its Unix access mode MUST be 0700.

The lifetime of the directory MUST be bound to the user being logged in. It MUST be created when the user first logs in and if the user fully logs out the directory MUST be removed. If the user logs in more than once they should get pointed to the same directory, and it is mandatory that the directory continues to exist from their first login to their last logout on the system, and not removed in between. Files in the directory MUST not survive reboot or a full logout/login cycle.

The directory MUST be on a local file system and not shared with any other system. The directory MUST by fully-featured by the standards of the operating system. More specifically, on Unix-like operating systems AF_UNIX sockets, symbolic links, hard links, proper permissions, file locking, sparse files, memory mapping, file change notifications, a reliable hard link count must be supported, and no restrictions on the file name character set should be imposed. Files in this directory MAY be subjected to periodic clean-up. To ensure that your files are not removed, they should have their access time timestamp modified at least once every 6 hours of monotonic time or the 'sticky' bit should be set on the file.

If this function returns an error, applications should fall back to a replacement directory with similar capabilities and print a warning message. Applications should use this directory for communication and synchronization purposes and should not place larger files in it, since it might reside in runtime memory and cannot necessarily be swapped out to disk.

func StateHome

func StateHome() (string, error)

StateHome returns the single base directory relative to which user-specific state data should be written.

The $XDG_STATE_HOME contains state data that should persist between (application) restarts, but that is not important or portable enough to the user that it should be stored in $XDG_DATA_HOME. It may contain:

• actions history (logs, history, recently used files, …)
• current state of the application that can be reused on a restart (view, layout, open files, undo history, …)

func Valid

func Valid(path string) error

Valid returns an error if the path is not absolute (beginning from '/') or if it is otherwise invalid.

Types

type Var

type Var string

Var is an XDG environment variable.

const (
	VarDataHome   Var = "XDG_DATA_HOME"
	VarConfigHome Var = "XDG_CONFIG_HOME"
	VarStateHome  Var = "XDG_STATE_HOME"
	VarDataDirs   Var = "XDG_DATA_DIRS"
	VarConfigDirs Var = "XDG_CONFIG_DIRS"
	VarCacheHome  Var = "XDG_CACHE_HOME"
	VarRuntimeDir Var = "XDG_RUNTIME_DIR"
)

func (Var) Value

func (v Var) Value() string

Value returns the value of the environment variable.