This implements the XDG Base Directory Specification with a few adjustments.
| #define CUOS_PKG_USER_DIRS_INITZ | ( | pkg_name, | |||
| var_prefix, | |||||
| app_installdirs | ) | { pkg_name, var_prefix, app_installdirs, 0, CU_MUTEX_INITIALISER } |
A static initialiser for cuos_pkg_user_dirs to be used as
struct cuos_pkg_user_dirs foo_user_dirs = CUOS_PKG_USER_DIRS_INITZ("foo", "FOO", foo_installdirs);
after which cuos_pkg_user_config_dir(&foo_user_dirs) would give something like /home/jdoe/.config/foo. If you prefer to skip the installdirs initialisation, you can pass NULL as the last parameter and instead call cuos_pkg_user_dirs_init on program start-up.
This initialises part of the structure. The rest is initialised on demand when calling the cuos_pkg_* functions. The on-demand initalisation will look for environment variables starting with var_prefix, in particular if var_prefix is "FOO", then
$FOO_CONFIG_HOME is the primary user config directory,$FOO_DATA_HOME is the primary user data directory, and$FOO_CACHE_HOME is the primary user cache diretoryfor this package. If either of these are not set the subdirectory pkg_name under the corresponding XDG base directory is used instead.
Finally, foo_installdirs is used to set up additional paths for searching for package-installed files with cuos_pkg_user_config_search and cuos_pkg_user_data_search. You may pass NULL for foo_installdirs, but that means that if your package is installed under a prefix other than /usr/local or usr, installed files will not be found unless the user includes the location in the corresponding variables
$FOO_CONFIG_DIRS or $XDG_CONFIG_DIRS, and$FOO_DATA_DIRS or $XDG_DATA_DIRS.See cuos_pkg_user_config_search and cuos_pkg_user_data_search for the search order.
| cu_str_t cuos_pkg_user_cache_dir | ( | cuos_pkg_user_dirs_t | udirs | ) |
The user cache path from udirs.
| cu_str_t cuos_pkg_user_cache_path | ( | cuos_pkg_user_dirs_t | udirs, | |
| cu_str_t | path | |||
| ) |
Resolve a relative path under the cache home of udirs.
| cu_str_t cuos_pkg_user_config_dir | ( | cuos_pkg_user_dirs_t | udirs | ) |
The user config path from udirs.
| cu_str_t cuos_pkg_user_config_path | ( | cuos_pkg_user_dirs_t | udirs, | |
| cu_str_t | path | |||
| ) |
Resolve a relative path under the config home of udirs.
| cu_str_t cuos_pkg_user_config_search | ( | cuos_pkg_user_dirs_t | udirs, | |
| cu_str_t | path | |||
| ) |
Locate path in the list of config search directories of udirs. This returns the first existing match under
$FOO_CONFIG_DIRS is set, any of this colon separated list of directories in order.$XDG_CONFIG_DIRS is set, any subdirectory pkg_name under that colon separated list in order./etc/xdg/pkg_name, then /etc/pkg_name. | cu_str_t cuos_pkg_user_data_dir | ( | cuos_pkg_user_dirs_t | udirs | ) |
The user data path from udirs.
| cu_str_t cuos_pkg_user_data_path | ( | cuos_pkg_user_dirs_t | udirs, | |
| cu_str_t | path | |||
| ) |
Reslove a relative path under the data home of udirs.
| cu_str_t cuos_pkg_user_data_search | ( | cuos_pkg_user_dirs_t | udirs, | |
| cu_str_t | path | |||
| ) |
Locate path in the list of data search directories of udirs. This returns the first existing match under
$FOO_DATA_DIRS is set, any of this colon separated list of directories in order.$XDG_DATA_DIRS is set, any subdirectory pkg_name under that colon separated list in order./usr/local/pkg_name then /usr/pkg_name. | void cuos_pkg_user_dirs_ensure_init | ( | cuos_pkg_user_dirs_t | udirs | ) |
Finish initialisation of udirs if not already done. This is called by the other cuos_pkg_* functions, so you normally don't need to call it explicitely. udirs must be statically initalised with CUOS_PKG_USER_DIRS_INITZ in advance.
| void cuos_pkg_user_dirs_init | ( | cuos_pkg_user_dirs_t | udirs, | |
| char const * | sysconfdir, | |||
| char const * | datadir | |||
| ) |
Optionally call this on start-up to initialize udirs with the given package-specific installation directories. You only need to do this if you want to skip the initialization of a cu_installdirs_t array.
| void cuos_reset_user_dirs | ( | void | ) |
This functions forces re-probing of the user directories. The may be useful if directories where created or the XDG_* environment variables where changed with setenv(3), unsetenv(3), etc.
| cu_str_t cuos_user_cache_home | ( | void | ) |
The parent of per-application user cache directories. This is the environment variable $XDG_CACHE_HOME if set, otherwise $HOME/.cache.
| cu_str_t cuos_user_config_home | ( | void | ) |
The parent of the per-application user configuration directories. This is the environment variable $XDG_CONFIG_HOME if set, otherwise $HOME/.config.
| cu_str_t cuos_user_data_home | ( | void | ) |
The parent of the per-application user data directories. This is the environment variable $XDG_DATA_HOME if set, otherwise $HOME/.local/share.