sd_path_lookup

systemd
sd_path_lookup 3
sd_path_lookup sd_path_lookup_strv Query well-known file system paths

    #include <systemd/sd-path.h>

    enum {
            SD_PATH_TEMPORARY,
            SD_PATH_TEMPORARY_LARGE,

            SD_PATH_SYSTEM_BINARIES,
            SD_PATH_SYSTEM_INCLUDE,
            SD_PATH_SYSTEM_LIBRARY_PRIVATE,
            SD_PATH_SYSTEM_LIBRARY_ARCH,
            SD_PATH_SYSTEM_SHARED,
            SD_PATH_SYSTEM_CONFIGURATION_FACTORY,
            SD_PATH_SYSTEM_STATE_FACTORY,

            SD_PATH_SYSTEM_CONFIGURATION,
            SD_PATH_SYSTEM_RUNTIME,
            SD_PATH_SYSTEM_RUNTIME_LOGS,
            SD_PATH_SYSTEM_STATE_PRIVATE,
            SD_PATH_SYSTEM_STATE_LOGS,
            SD_PATH_SYSTEM_STATE_CACHE,
            SD_PATH_SYSTEM_STATE_SPOOL,

            SD_PATH_USER_BINARIES,
            SD_PATH_USER_LIBRARY_PRIVATE,
            SD_PATH_USER_LIBRARY_ARCH,
            SD_PATH_USER_SHARED,

            SD_PATH_USER_CONFIGURATION,
            SD_PATH_USER_RUNTIME,
            SD_PATH_USER_STATE_CACHE,

            SD_PATH_USER,
            SD_PATH_USER_DOCUMENTS,
            SD_PATH_USER_MUSIC,
            SD_PATH_USER_PICTURES,
            SD_PATH_USER_VIDEOS,
            SD_PATH_USER_DOWNLOAD,
            SD_PATH_USER_PUBLIC,
            SD_PATH_USER_TEMPLATES,
            SD_PATH_USER_DESKTOP,

            SD_PATH_SEARCH_BINARIES,
            SD_PATH_SEARCH_BINARIES_DEFAULT,
            SD_PATH_SEARCH_LIBRARY_PRIVATE,
            SD_PATH_SEARCH_LIBRARY_ARCH,
            SD_PATH_SEARCH_SHARED,
            SD_PATH_SEARCH_CONFIGURATION_FACTORY,
            SD_PATH_SEARCH_STATE_FACTORY,
            SD_PATH_SEARCH_CONFIGURATION,

            SD_PATH_SYSTEMD_UTIL,
            SD_PATH_SYSTEMD_SYSTEM_UNIT,
            SD_PATH_SYSTEMD_SYSTEM_PRESET,
            SD_PATH_SYSTEMD_USER_UNIT,
            SD_PATH_SYSTEMD_USER_PRESET,
            SD_PATH_SYSTEMD_SYSTEM_CONF,
            SD_PATH_SYSTEMD_USER_CONF,
            SD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT,
            SD_PATH_SYSTEMD_SEARCH_USER_UNIT,
            SD_PATH_SYSTEMD_SYSTEM_GENERATOR,
            SD_PATH_SYSTEMD_USER_GENERATOR,
            SD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR,
            SD_PATH_SYSTEMD_SEARCH_USER_GENERATOR,
            SD_PATH_SYSTEMD_SLEEP,
            SD_PATH_SYSTEMD_SHUTDOWN,

            SD_PATH_TMPFILES,
            SD_PATH_SYSUSERS,
            SD_PATH_SYSCTL,
            SD_PATH_BINFMT,
            SD_PATH_MODULES_LOAD,
            SD_PATH_CATALOG,

            SD_PATH_SYSTEMD_SEARCH_NETWORK,
    };

int `sd_path_lookup` uint64_t type const char *suffix char **paths int `sd_path_lookup_strv` uint64_t type const char *suffix char ***paths

## Description

`sd_path_lookup()` and `sd_bus_path_lookup_strv()` return a single path or set of file system paths specified by the argument type. In case of `sd_path_lookup()` a single `NUL`-terminated string is returned. When type specifies a set of paths, they are concatenated using `:` as a separator (as is traditionally done for e.g. `$PATH` or `$LD_LIBRARY_PATH`). In case of `sd_path_lookup_strv()` a `NULL`-terminated array of strings is returned (strv). If suffix suffix is given, it is concatenated to each of the paths after a slash (`/`). All returned paths are absolute.

For paths which refer to user directories, the relevant XDG standard is followed, with support for environment variables like `$XDG_DOCUMENTS_DIR`, `$XDG_DESKTOP_DIR`, ..., and explicit configuration in `/etc/xdg/user-dirs.conf` or `${XDG_CONFIG_HOME}/user-dirs.dirs`. See XDG Base Directory Specification for details.

systemd-path 1 is a wrapper around `sd_path_lookup()` and allows the same set of paths to be queried.

## Return Value

On success, `sd_path_lookup()` and `sd_path_lookup_strv()` return a non-negative integer. On failure, a negative errno-style error number is returned by either function.

The returned string or string array (strv) must be free 3'd by the caller.

### Errors

Returned errors may indicate the following problems:

`-EOPNOTSUPP`

  Unknown identifier type.

`-EINVAL`

  Output argument is `NULL`.

`-ENXIO`

  Query failed because of an undefined environment variable (e.g. for `SD_PATH_USER_RUNTIME` when `$XDG_RUNTIME_DIR` is not defined).

`-ENOMEM`

  Memory allocation failed.

## Examples

### Look up the location of ~/Documents

Note that the default answer of `$HOME/Documents` may be overridden by `user-dirs.conf` or `$XDG_DOCUMENTS_DIR`.

## See Also

systemd-path 1