1SD_PATH_LOOKUP(3)               sd_path_lookup               SD_PATH_LOOKUP(3)
2
3
4

NAME

6       sd_path_lookup, sd_path_lookup_strv - Query well-known file system
7       paths
8

SYNOPSIS

10       #include <systemd/sd-path.h>
11
12       enum {
13               SD_PATH_TEMPORARY,
14               SD_PATH_TEMPORARY_LARGE,
15
16               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
24               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
32               SD_PATH_USER_BINARIES,
33               SD_PATH_USER_LIBRARY_PRIVATE,
34               SD_PATH_USER_LIBRARY_ARCH,
35               SD_PATH_USER_SHARED,
36
37               SD_PATH_USER_CONFIGURATION,
38               SD_PATH_USER_RUNTIME,
39               SD_PATH_USER_STATE_CACHE,
40
41               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
51               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
60               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
76               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
83               SD_PATH_SYSTEMD_SEARCH_NETWORK,
84       };
85
86       int sd_path_lookup(uint64_t type, const char *suffix, char **paths);
87
88       int sd_path_lookup_strv(uint64_t type, const char *suffix,
89                               char ***paths);
90

DESCRIPTION

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
102       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
108       systemd-path(1) is a wrapper around sd_path_lookup() and allows the
109       same set of paths to be queried.
110

RETURN VALUE

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
116       The returned string or string array (strv) must be free(3)'d by the
117       caller.
118
119   Errors
120       Returned errors may indicate the following problems:
121
122       -EOPNOTSUPP
123           Unknown identifier type.
124
125       -EINVAL
126           Output argument is NULL.
127
128       -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
132       -ENOMEM
133           Memory allocation failed.
134

EXAMPLES

136   Look up the location of ~/Documents
137           /* SPDX-License-Identifier: CC0-1.0 */
138
139           #include <stdio.h>
140           #include <stdlib.h>
141           #include <sd-path.h>
142
143           int main(void) {
144             int r;
145             char *t;
146
147             r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
148             if (r < 0)
149               return EXIT_FAILURE;
150
151             printf("~/Documents: %s\n", t);
152             free(t);
153
154             return EXIT_SUCCESS;
155           }
156
157       Note that the default answer of $HOME/Documents may be overridden by
158       user-dirs.conf or $XDG_DOCUMENTS_DIR.
159

NOTES

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

SEE ALSO

165       systemd-path(1)
166

NOTES

168        1. XDG Base Directory Specification
169           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
170
171
172
173systemd 251                                                  SD_PATH_LOOKUP(3)
Impressum