Debian Codegraph @

upstream/debian-trixie/man3/sd_path_lookup.3

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