1SD_PATH_LOOKUP(3) sd_path_lookup SD_PATH_LOOKUP(3)
2
6 sd_path_lookup, sd_path_lookup_strv - Query well-known file system
7 paths
8
10 #include <systemd/sd-path.h>
11 enum {
13 SD_PATH_TEMPORARY,
14 SD_PATH_TEMPORARY_LARGE,
15 SD_PATH_SYSTEM_BINARIES,
17 SD_PATH_SYSTEM_INCLUDE,
18 SD_PATH_SYSTEM_LIBRARY_PRIVATE,
19 SD_PATH_SYSTEM_LIBRARY_ARCH,
20 SD_PATH_SYSTEM_SHARED,
21 SD_PATH_SYSTEM_CONFIGURATION_FACTORY,
22 SD_PATH_SYSTEM_STATE_FACTORY,
23 SD_PATH_SYSTEM_CONFIGURATION,
25 SD_PATH_SYSTEM_RUNTIME,
26 SD_PATH_SYSTEM_RUNTIME_LOGS,
27 SD_PATH_SYSTEM_STATE_PRIVATE,
28 SD_PATH_SYSTEM_STATE_LOGS,
29 SD_PATH_SYSTEM_STATE_CACHE,
30 SD_PATH_SYSTEM_STATE_SPOOL,
31 SD_PATH_USER_BINARIES,
33 SD_PATH_USER_LIBRARY_PRIVATE,
34 SD_PATH_USER_LIBRARY_ARCH,
35 SD_PATH_USER_SHARED,
36 SD_PATH_USER_CONFIGURATION,
38 SD_PATH_USER_RUNTIME,
39 SD_PATH_USER_STATE_PRIVATE,
40 SD_PATH_USER_STATE_CACHE,
41 SD_PATH_USER,
43 SD_PATH_USER_DOCUMENTS,
44 SD_PATH_USER_MUSIC,
45 SD_PATH_USER_PICTURES,
46 SD_PATH_USER_VIDEOS,
47 SD_PATH_USER_DOWNLOAD,
48 SD_PATH_USER_PUBLIC,
49 SD_PATH_USER_TEMPLATES,
50 SD_PATH_USER_DESKTOP,
51 SD_PATH_SEARCH_BINARIES,
53 SD_PATH_SEARCH_BINARIES_DEFAULT,
54 SD_PATH_SEARCH_LIBRARY_PRIVATE,
55 SD_PATH_SEARCH_LIBRARY_ARCH,
56 SD_PATH_SEARCH_SHARED,
57 SD_PATH_SEARCH_CONFIGURATION_FACTORY,
58 SD_PATH_SEARCH_STATE_FACTORY,
59 SD_PATH_SEARCH_CONFIGURATION,
60 SD_PATH_SYSTEMD_UTIL,
62 SD_PATH_SYSTEMD_SYSTEM_UNIT,
63 SD_PATH_SYSTEMD_SYSTEM_PRESET,
64 SD_PATH_SYSTEMD_USER_UNIT,
65 SD_PATH_SYSTEMD_USER_PRESET,
66 SD_PATH_SYSTEMD_SYSTEM_CONF,
67 SD_PATH_SYSTEMD_USER_CONF,
68 SD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT,
69 SD_PATH_SYSTEMD_SEARCH_USER_UNIT,
70 SD_PATH_SYSTEMD_SYSTEM_GENERATOR,
71 SD_PATH_SYSTEMD_USER_GENERATOR,
72 SD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR,
73 SD_PATH_SYSTEMD_SEARCH_USER_GENERATOR,
74 SD_PATH_SYSTEMD_SLEEP,
75 SD_PATH_SYSTEMD_SHUTDOWN,
76 SD_PATH_TMPFILES,
78 SD_PATH_SYSUSERS,
79 SD_PATH_SYSCTL,
80 SD_PATH_BINFMT,
81 SD_PATH_MODULES_LOAD,
82 SD_PATH_CATALOG,
83 SD_PATH_SYSTEMD_SEARCH_NETWORK,
85 SD_PATH_SYSTEMD_SYSTEM_ENVIRONMENT_GENERATOR,
87 SD_PATH_SYSTEMD_USER_ENVIRONMENT_GENERATOR,
88 SD_PATH_SYSTEMD_SEARCH_SYSTEM_ENVIRONMENT_GENERATOR,
89 SD_PATH_SYSTEMD_SEARCH_USER_ENVIRONMENT_GENERATOR,
90 };
91 int sd_path_lookup(uint64_t type, const char *suffix, char **paths);
93 int sd_path_lookup_strv(uint64_t type, const char *suffix,
95 char ***paths);
96
98 sd_path_lookup() and sd_bus_path_lookup_strv() return a single path or
99 set of file system paths specified by the argument type. In case of
100 sd_path_lookup() a single NUL-terminated string is returned. When type
101 specifies a set of paths, they are concatenated using ":" as a
102 separator (as is traditionally done for e.g. $PATH or
103 $LD_LIBRARY_PATH). In case of sd_path_lookup_strv() a NULL-terminated
104 array of strings is returned (strv). If suffix suffix is given, it is
105 concatenated to each of the paths after a slash ("/"). All returned
106 paths are absolute.
107 For paths which refer to user directories, the relevant XDG standard is
109 followed, with support for environment variables like
110 $XDG_DOCUMENTS_DIR, $XDG_DESKTOP_DIR, ..., and explicit configuration
111 in /etc/xdg/user-dirs.conf or ${XDG_CONFIG_HOME}/user-dirs.dirs. See
112 XDG Base Directory Specification[1] for details.
113 systemd-path(1) is a wrapper around sd_path_lookup() and allows the
115 same set of paths to be queried.
116
118 On success, sd_path_lookup() and sd_path_lookup_strv() return a
119 non-negative integer. On failure, a negative errno-style error number
120 is returned by either function.
121 The returned string or string array (strv) must be free(3)'d by the
123 caller.
124 Errors
126 Returned errors may indicate the following problems:
127 -EOPNOTSUPP
129 Unknown identifier type.
130 -EINVAL
132 Output argument is NULL.
133 -ENXIO
135 Query failed because of an undefined environment variable (e.g. for
136 SD_PATH_USER_RUNTIME when $XDG_RUNTIME_DIR is not defined).
137 -ENOMEM
139 Memory allocation failed.
140
142 Look up the location of ~/Documents
143 /* SPDX-License-Identifier: MIT-0 */
144 #include <stdio.h>
146 #include <stdlib.h>
147 #include <sd-path.h>
148 int main(void) {
150 int r;
151 char *t;
152 r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
154 if (r < 0)
155 return EXIT_FAILURE;
156 printf("~/Documents: %s\n", t);
158 free(t);
159 return EXIT_SUCCESS;
161 }
162 Note that the default answer of $HOME/Documents may be overridden by
164 user-dirs.conf or $XDG_DOCUMENTS_DIR.
165
167 Functions described here are available as a shared library, which can
168 be compiled against and linked to with the libsystemd pkg-config(1)
169 file.
170 The code described here uses getenv(3), which is declared to be not
172 multi-thread-safe. This means that the code calling the functions
173 described here must not call setenv(3) from a parallel thread. It is
174 recommended to only do calls to setenv() from an early phase of the
175 program when no other threads have been started.
176
178 systemd-path(1)
179
181 1. XDG Base Directory Specification
182 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
183systemd 254 SD_PATH_LOOKUP(3)