sd_path_lookup(3)

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

NOTES

159       These APIs are implemented as a shared library, which can be compiled
160       and linked to with the libsystemd pkg-config(1) file.
161

NOTES

166        1. XDG Base Directory Specification
167           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
168
169
170
171systemd 249                                                  SD_PATH_LOOKUP(3)