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 };
85 int sd_path_lookup(uint64_t type, const char *suffix, char **paths);
87 int sd_path_lookup_strv(uint64_t type, const char *suffix,
89 char ***paths);
90
92 sd_path_lookup() and sd_bus_path_lookup_strv() return a single path or
93 set of file system paths specified by the argument type. In case of
94 sd_path_lookup() a single NUL-terminated string is returned. When type
95 specifies a set of paths, they are concatenated using ":" as a
96 separator (as is traditionally done for e.g. $PATH or
97 $LD_LIBRARY_PATH). In case of sd_path_lookup_strv() a NULL-terminated
98 array of strings is returned (strv). If suffix suffix is given, it is
99 concatenated to each of the paths after a slash ("/"). All returned
100 paths are absolute.
101 For paths which refer to user directories, the relevant XDG standard is
103 followed, with support for environment variables like
104 $XDG_DOCUMENTS_DIR, $XDG_DESKTOP_DIR, ..., and explicit configuration
105 in /etc/xdg/user-dirs.conf or ${XDG_CONFIG_HOME}/user-dirs.dirs. See
106 XDG Base Directory Specification[1] for details.
107 systemd-path(1) is a wrapper around sd_path_lookup() and allows the
109 same set of paths to be queried.
110
112 On success, sd_path_lookup() and sd_path_lookup_strv() return a
113 non-negative integer. On failure, a negative errno-style error number
114 is returned by either function.
115 The returned string or string array (strv) must be free(3)'d by the
117 caller.
118 Errors
120 Returned errors may indicate the following problems:
121 -EOPNOTSUPP
123 Unknown identifier type.
124 -EINVAL
126 Output argument is NULL.
127 -ENXIO
129 Query failed because of an undefined environment variable (e.g. for
130 SD_PATH_USER_RUNTIME when $XDG_RUNTIME_DIR is not defined).
131 -ENOMEM
133 Memory allocation failed.
134
136 Look up the location of ~/Documents
137 /* SPDX-License-Identifier: CC0-1.0 */
138 #include <stdio.h>
140 #include <stdlib.h>
141 #include <sd-path.h>
142 int main(void) {
144 int r;
145 char *t;
146 r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
148 if (r < 0)
149 return EXIT_FAILURE;
150 printf("~/Documents: %s\n", t);
152 free(t);
153 return EXIT_SUCCESS;
155 }
156 Note that the default answer of $HOME/Documents may be overridden by
158 user-dirs.conf or $XDG_DOCUMENTS_DIR.
159
161 These APIs are implemented as a shared library, which can be compiled
162 and linked to with the libsystemd pkg-config(1) file.
163
165 systemd-path(1)
166
168 1. XDG Base Directory Specification
169 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
170systemd 251 SD_PATH_LOOKUP(3)