SD_PATH_LOOKUP(3)

💖 NAME 💖

okay bestie, this is SD_PATH_LOOKUP(3) — the page for sd_path_lookup, sd_path_lookup_strv, and their whole “where do well-known file system paths actually live?” situation. ✨

🌸 SYNOPSIS 🌸

#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_SEARCH_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_PRIVATE,
        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_USER_PROJECTS,

        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,

        SD_PATH_SYSTEMD_SYSTEM_ENVIRONMENT_GENERATOR,
        SD_PATH_SYSTEMD_USER_ENVIRONMENT_GENERATOR,
        SD_PATH_SYSTEMD_SEARCH_SYSTEM_ENVIRONMENT_GENERATOR,
        SD_PATH_SYSTEMD_SEARCH_USER_ENVIRONMENT_GENERATOR,
};

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 🦋

so basically sd_path_lookup() and sd_bus_path_lookup_strv() return a single path or a set of file system paths specified by the argument type. no cap, that’s the whole vibe.

With sd_path_lookup(), you get one single NUL-terminated string. If type specifies a set of paths, they get concatenated using ":" as the separator — yes, like the traditional $PATH or $LD_LIBRARY_PATH situation. iconic behavior, honestly.

With sd_path_lookup_strv(), you get a NULL-terminated array of strings (a strv). if a suffix is given, it gets concatenated to each of the paths after a slash (/). and all returned paths are absolute. periodt.

For paths that 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[1] for details. 💅

Also: systemd-path(1) is a wrapper around sd_path_lookup() and allows the same set of paths to be queried. cute little shortcut, iykyk.

🎀 RETURN VALUE 🎀

On success, sd_path_lookup() and sd_path_lookup_strv() return a non-negative integer. slay.

On failure, a negative errno-style error number is returned by either function. not slay, but informative.

The returned string or string array (strv) must be free(3)'d by the caller. don’t forget, bestie, that’s your cleanup era. 🧹

💀 Errors 💀

Returned errors may indicate the following problems:

• -EOPNOTSUPP — Unknown identifier type. Added in version 246.
• -EINVAL — Output argument is NULL. Added in version 246.
• -ENXIO — Query failed because of an undefined environment variable (e.g. for SD_PATH_USER_RUNTIME when $XDG_RUNTIME_DIR is not defined). Added in version 246.
• -ENOMEM — Memory allocation failed. Added in version 246.

🍓 EXAMPLES 🍓

🌈 Look up the location of ~/Documents 🌈

/* SPDX-License-Identifier: MIT-0 */

#include <stdio.h>
#include <stdlib.h>
#include <systemd/sd-path.h>

int main(void) {
  int r;
  char *t;

  r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
  if (r < 0)
    return EXIT_FAILURE;

  printf("~/Documents: %s\n", t);
  free(t);

  return EXIT_SUCCESS;
}

Note that the default answer of $HOME/Documents may be overridden by user-dirs.conf or $XDG_DOCUMENTS_DIR. so like… don’t assume, always check. 🙈

🌟 NOTES 🌟

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. very “link me, bestie” of them. 🫶

The code described here uses getenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) from a parallel thread. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. lowkey important, highkey please respect it. 😭

👑 HISTORY 👑

sd_path_lookup() and sd_path_lookup_strv() were added in version 246. a little historical moment. 🎀

💜 SEE ALSO 💜

systemd(1), sd-path(3), systemd-path(1)

📎 NOTES 📎

1. XDG Base Directory Specification — https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html

---

xoxo, this page is from systemd 261.3 and it’s literally the SD_PATH_LOOKUP(3) manual — mwah 💋✨