sd_path_lookup_strv(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 <sd-path.h>
139
140           int main(void) {
141             char *t;
142
143             sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
144             printf("~/Documents: %s\n", t);
145           }
146
147       Note that the default answer of $HOME/Documents may be overridden by
148       user-dirs.conf or $XDG_DOCUMENTS_DIR.
149

NOTES

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

NOTES

158        1. XDG Base Directory Specification
159           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
160
161
162
163systemd 246                                                  SD_PATH_LOOKUP(3)