Debian Codegraph @

upstream/debian-unstable/man3/sd_path_lookup.3

raw
1 '\" t
2 .TH "SD_PATH_LOOKUP" "3" "" "systemd 261~rc3" "sd_path_lookup"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_path_lookup, sd_path_lookup_strv \- Query well\-known file system paths
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-path\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 enum {
35 \fBSD_PATH_TEMPORARY\fR,
36 \fBSD_PATH_TEMPORARY_LARGE\fR,
37
38 \fBSD_PATH_SYSTEM_BINARIES\fR,
39 \fBSD_PATH_SYSTEM_INCLUDE\fR,
40 \fBSD_PATH_SYSTEM_LIBRARY_PRIVATE\fR,
41 \fBSD_PATH_SYSTEM_LIBRARY_ARCH\fR,
42 \fBSD_PATH_SYSTEM_SHARED\fR,
43 \fBSD_PATH_SYSTEM_CONFIGURATION_FACTORY\fR,
44 \fBSD_PATH_SYSTEM_STATE_FACTORY\fR,
45
46 \fBSD_PATH_SYSTEM_CONFIGURATION\fR,
47 \fBSD_PATH_SYSTEM_SEARCH_CONFIGURATION\fR,
48 \fBSD_PATH_SYSTEM_RUNTIME\fR,
49 \fBSD_PATH_SYSTEM_RUNTIME_LOGS\fR,
50 \fBSD_PATH_SYSTEM_STATE_PRIVATE\fR,
51 \fBSD_PATH_SYSTEM_STATE_LOGS\fR,
52 \fBSD_PATH_SYSTEM_STATE_CACHE\fR,
53 \fBSD_PATH_SYSTEM_STATE_SPOOL\fR,
54
55 \fBSD_PATH_USER_BINARIES\fR,
56 \fBSD_PATH_USER_LIBRARY_PRIVATE\fR,
57 \fBSD_PATH_USER_LIBRARY_ARCH\fR,
58 \fBSD_PATH_USER_SHARED\fR,
59
60 \fBSD_PATH_USER_CONFIGURATION\fR,
61 \fBSD_PATH_USER_RUNTIME\fR,
62 \fBSD_PATH_USER_STATE_PRIVATE\fR,
63 \fBSD_PATH_USER_STATE_CACHE\fR,
64
65 \fBSD_PATH_USER\fR,
66 \fBSD_PATH_USER_DOCUMENTS\fR,
67 \fBSD_PATH_USER_MUSIC\fR,
68 \fBSD_PATH_USER_PICTURES\fR,
69 \fBSD_PATH_USER_VIDEOS\fR,
70 \fBSD_PATH_USER_DOWNLOAD\fR,
71 \fBSD_PATH_USER_PUBLIC\fR,
72 \fBSD_PATH_USER_TEMPLATES\fR,
73 \fBSD_PATH_USER_DESKTOP\fR,
74 \fBSD_PATH_USER_PROJECTS\fR,
75
76 \fBSD_PATH_SEARCH_BINARIES\fR,
77 \fBSD_PATH_SEARCH_BINARIES_DEFAULT\fR,
78 \fBSD_PATH_SEARCH_LIBRARY_PRIVATE\fR,
79 \fBSD_PATH_SEARCH_LIBRARY_ARCH\fR,
80 \fBSD_PATH_SEARCH_SHARED\fR,
81 \fBSD_PATH_SEARCH_CONFIGURATION_FACTORY\fR,
82 \fBSD_PATH_SEARCH_STATE_FACTORY\fR,
83 \fBSD_PATH_SEARCH_CONFIGURATION\fR,
84
85 \fBSD_PATH_SYSTEMD_UTIL\fR,
86 \fBSD_PATH_SYSTEMD_SYSTEM_UNIT\fR,
87 \fBSD_PATH_SYSTEMD_SYSTEM_PRESET\fR,
88 \fBSD_PATH_SYSTEMD_USER_UNIT\fR,
89 \fBSD_PATH_SYSTEMD_USER_PRESET\fR,
90 \fBSD_PATH_SYSTEMD_SYSTEM_CONF\fR,
91 \fBSD_PATH_SYSTEMD_USER_CONF\fR,
92 \fBSD_PATH_SYSTEMD_SEARCH_SYSTEM_UNIT\fR,
93 \fBSD_PATH_SYSTEMD_SEARCH_USER_UNIT\fR,
94 \fBSD_PATH_SYSTEMD_SYSTEM_GENERATOR\fR,
95 \fBSD_PATH_SYSTEMD_USER_GENERATOR\fR,
96 \fBSD_PATH_SYSTEMD_SEARCH_SYSTEM_GENERATOR\fR,
97 \fBSD_PATH_SYSTEMD_SEARCH_USER_GENERATOR\fR,
98 \fBSD_PATH_SYSTEMD_SLEEP\fR,
99 \fBSD_PATH_SYSTEMD_SHUTDOWN\fR,
100
101 \fBSD_PATH_TMPFILES\fR,
102 \fBSD_PATH_SYSUSERS\fR,
103 \fBSD_PATH_SYSCTL\fR,
104 \fBSD_PATH_BINFMT\fR,
105 \fBSD_PATH_MODULES_LOAD\fR,
106 \fBSD_PATH_CATALOG\fR,
107
108 \fBSD_PATH_SYSTEMD_SEARCH_NETWORK\fR,
109
110 \fBSD_PATH_SYSTEMD_SYSTEM_ENVIRONMENT_GENERATOR\fR,
111 \fBSD_PATH_SYSTEMD_USER_ENVIRONMENT_GENERATOR\fR,
112 \fBSD_PATH_SYSTEMD_SEARCH_SYSTEM_ENVIRONMENT_GENERATOR\fR,
113 \fBSD_PATH_SYSTEMD_SEARCH_USER_ENVIRONMENT_GENERATOR\fR,
114 };
115 .fi
116 .ft
117 .HP \w'int\ sd_path_lookup('u
118 .BI "int sd_path_lookup(uint64_t\ " "type" ", const\ char\ *" "suffix" ", char\ **" "paths" ");"
119 .HP \w'int\ sd_path_lookup_strv('u
120 .BI "int sd_path_lookup_strv(uint64_t\ " "type" ", const\ char\ *" "suffix" ", char\ ***" "paths" ");"
121 .SH "DESCRIPTION"
122 .PP
123 \fBsd_path_lookup()\fR
124 and
125 \fBsd_bus_path_lookup_strv()\fR
126 return a single path or set of file system paths specified by the argument
127 \fItype\fR\&. In case of
128 \fBsd_path_lookup()\fR
129 a single
130 \fBNUL\fR\-terminated string is returned\&. When
131 \fItype\fR
132 specifies a set of paths, they are concatenated using
133 ":"
134 as a separator (as is traditionally done for e\&.g\&.
135 \fI$PATH\fR
136 or
137 \fI$LD_LIBRARY_PATH\fR)\&. In case of
138 \fBsd_path_lookup_strv()\fR
139 a
140 \fBNULL\fR\-terminated array of strings is returned (strv)\&. If suffix
141 \fIsuffix\fR
142 is given, it is concatenated to each of the paths after a slash ("/")\&. All returned paths are absolute\&.
143 .PP
144 For paths which refer to user directories, the relevant XDG standard is followed, with support for environment variables like
145 \fI$XDG_DOCUMENTS_DIR\fR,
146 \fI$XDG_DESKTOP_DIR\fR, \&.\&.\&., and explicit configuration in
147 /etc/xdg/user\-dirs\&.conf
148 or
149 ${XDG_CONFIG_HOME}/user\-dirs\&.dirs\&. See
150 \m[blue]\fBXDG Base Directory Specification\fR\m[]\&\s-2\u[1]\d\s+2
151 for details\&.
152 .PP
153 \fBsystemd-path\fR(1)
154 is a wrapper around
155 \fBsd_path_lookup()\fR
156 and allows the same set of paths to be queried\&.
157 .SH "RETURN VALUE"
158 .PP
159 On success,
160 \fBsd_path_lookup()\fR
161 and
162 \fBsd_path_lookup_strv()\fR
163 return a non\-negative integer\&. On failure, a negative errno\-style error number is returned by either function\&.
164 .PP
165 The returned string or string array (strv) must be
166 \fBfree\fR(3)\*(Aqd by the caller\&.
167 .SS "Errors"
168 .PP
169 Returned errors may indicate the following problems:
170 .PP
171 \fB\-EOPNOTSUPP\fR
172 .RS 4
173 Unknown identifier
174 \fItype\fR\&.
175 .sp
176 Added in version 246\&.
177 .RE
178 .PP
179 \fB\-EINVAL\fR
180 .RS 4
181 Output argument is
182 \fBNULL\fR\&.
183 .sp
184 Added in version 246\&.
185 .RE
186 .PP
187 \fB\-ENXIO\fR
188 .RS 4
189 Query failed because of an undefined environment variable (e\&.g\&. for
190 \fBSD_PATH_USER_RUNTIME\fR
191 when
192 \fI$XDG_RUNTIME_DIR\fR
193 is not defined)\&.
194 .sp
195 Added in version 246\&.
196 .RE
197 .PP
198 \fB\-ENOMEM\fR
199 .RS 4
200 Memory allocation failed\&.
201 .sp
202 Added in version 246\&.
203 .RE
204 .SH "EXAMPLES"
205 .SS "Look up the location of ~/Documents"
206 .sp
207 .if n \{\
208 .RS 4
209 .\}
210 .nf
211 /* SPDX\-License\-Identifier: MIT\-0 */
212
213 #include <stdio\&.h>
214 #include <stdlib\&.h>
215 #include <systemd/sd\-path\&.h>
216
217 int main(void) {
218 int r;
219 char *t;
220
221 r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
222 if (r < 0)
223 return EXIT_FAILURE;
224
225 printf("~/Documents: %s\en", t);
226 free(t);
227
228 return EXIT_SUCCESS;
229 }
230 .fi
231 .if n \{\
232 .RE
233 .\}
234 .PP
235 Note that the default answer of
236 $HOME/Documents
237 may be overridden by
238 user\-dirs\&.conf
239 or
240 \fI$XDG_DOCUMENTS_DIR\fR\&.
241 .SH "NOTES"
242 .PP
243 Functions described here are available as a shared library, which can be compiled against and linked to with the
244 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
245 file\&.
246 .PP
247 The code described here uses
248 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
249 \fBsetenv\fR(3)
250 from a parallel thread\&. It is recommended to only do calls to
251 \fBsetenv()\fR
252 from an early phase of the program when no other threads have been started\&.
253 .SH "HISTORY"
254 .PP
255 \fBsd_path_lookup()\fR
256 and
257 \fBsd_path_lookup_strv()\fR
258 were added in version 246\&.
259 .SH "SEE ALSO"
260 .PP
261 \fBsystemd\fR(1), \fBsd-path\fR(3), \fBsystemd-path\fR(1)
262 .SH "NOTES"
263 .IP " 1." 4
264 XDG Base Directory Specification
265 .RS 4
266 \%https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
267 .RE