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_CACHE,
40 SD_PATH_USER,
42 SD_PATH_USER_DOCUMENTS,
43 SD_PATH_USER_MUSIC,
44 SD_PATH_USER_PICTURES,
45 SD_PATH_USER_VIDEOS,
46 SD_PATH_USER_DOWNLOAD,
47 SD_PATH_USER_PUBLIC,
48 SD_PATH_USER_TEMPLATES,
49 SD_PATH_USER_DESKTOP,
50 SD_PATH_SEARCH_BINARIES,
52 SD_PATH_SEARCH_BINARIES_DEFAULT,
53 SD_PATH_SEARCH_LIBRARY_PRIVATE,
54 SD_PATH_SEARCH_LIBRARY_ARCH,
55 SD_PATH_SEARCH_SHARED,
56 SD_PATH_SEARCH_CONFIGURATION_FACTORY,
57 SD_PATH_SEARCH_STATE_FACTORY,
58 SD_PATH_SEARCH_CONFIGURATION,
59 SD_PATH_SYSTEMD_UTIL,
61 SD_PATH_SYSTEMD_SYSTEM_UNIT,
62 SD_PATH_SYSTEMD_SYSTEM_PRESET,
63 SD_PATH_SYSTEMD_USER_UNIT,
64 SD_PATH_SYSTEMD_USER_PRESET,
65 SD_PATH_SYSTEMD_SYSTEM_CONF,
66 SD_PATH_SYSTEMD_USER_CONF,
67 SD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT,
68 SD_PATH_SYSTEMD_SEARCH_USER_UNIT,
69 SD_PATH_SYSTEMD_SYSTEM_GENERATOR,
70 SD_PATH_SYSTEMD_USER_GENERATOR,
71 SD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR,
72 SD_PATH_SYSTEMD_SEARCH_USER_GENERATOR,
73 SD_PATH_SYSTEMD_SLEEP,
74 SD_PATH_SYSTEMD_SHUTDOWN,
75 SD_PATH_TMPFILES,
77 SD_PATH_SYSUSERS,
78 SD_PATH_SYSCTL,
79 SD_PATH_BINFMT,
80 SD_PATH_MODULES_LOAD,
81 SD_PATH_CATALOG,
82 SD_PATH_SYSTEMD_SEARCH_NETWORK,
84 SD_PATH_SYSTEMD_SYSTEM_ENVIRONMENT_GENERATOR,
86 SD_PATH_SYSTEMD_USER_ENVIRONMENT_GENERATOR,
87 SD_PATH_SYSTEMD_SEARCH_SYSTEM_ENVIRONMENT_GENERATOR,
88 SD_PATH_SYSTEMD_SEARCH_USER_ENVIRONMENT_GENERATOR,
89 };
90 int sd_path_lookup(uint64_t type, const char *suffix, char **paths);
92 int sd_path_lookup_strv(uint64_t type, const char *suffix,
94 char ***paths);
95
97 sd_path_lookup() and sd_bus_path_lookup_strv() return a single path or
98 set of file system paths specified by the argument type. In case of
99 sd_path_lookup() a single NUL-terminated string is returned. When type
100 specifies a set of paths, they are concatenated using ":" as a
101 separator (as is traditionally done for e.g. $PATH or
102 $LD_LIBRARY_PATH). In case of sd_path_lookup_strv() a NULL-terminated
103 array of strings is returned (strv). If suffix suffix is given, it is
104 concatenated to each of the paths after a slash ("/"). All returned
105 paths are absolute.
106 For paths which refer to user directories, the relevant XDG standard is
108 followed, with support for environment variables like
109 $XDG_DOCUMENTS_DIR, $XDG_DESKTOP_DIR, ..., and explicit configuration
110 in /etc/xdg/user-dirs.conf or ${XDG_CONFIG_HOME}/user-dirs.dirs. See
111 XDG Base Directory Specification[1] for details.
112 systemd-path(1) is a wrapper around sd_path_lookup() and allows the
114 same set of paths to be queried.
115
117 On success, sd_path_lookup() and sd_path_lookup_strv() return a
118 non-negative integer. On failure, a negative errno-style error number
119 is returned by either function.
120 The returned string or string array (strv) must be free(3)'d by the
122 caller.
123 Errors
125 Returned errors may indicate the following problems:
126 -EOPNOTSUPP
128 Unknown identifier type.
129 -EINVAL
131 Output argument is NULL.
132 -ENXIO
134 Query failed because of an undefined environment variable (e.g. for
135 SD_PATH_USER_RUNTIME when $XDG_RUNTIME_DIR is not defined).
136 -ENOMEM
138 Memory allocation failed.
139
141 Look up the location of ~/Documents
142 /* SPDX-License-Identifier: MIT-0 */
143 #include <stdio.h>
145 #include <stdlib.h>
146 #include <sd-path.h>
147 int main(void) {
149 int r;
150 char *t;
151 r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
153 if (r < 0)
154 return EXIT_FAILURE;
155 printf("~/Documents: %s\n", t);
157 free(t);
158 return EXIT_SUCCESS;
160 }
161 Note that the default answer of $HOME/Documents may be overridden by
163 user-dirs.conf or $XDG_DOCUMENTS_DIR.
164
166 These APIs are implemented as a shared library, which can be compiled
167 and linked to with the libsystemd pkg-config(1) file.
168
170 systemd-path(1)
171
173 1. XDG Base Directory Specification
174 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
175systemd 253 SD_PATH_LOOKUP(3)