Debian Codegraph @

upstream/fedora-44/man3/sd_path_lookup.3

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