]>
Commit | Line | Data |
---|---|---|
60f067b4 JS |
1 | '\" t |
2 | .TH "SD_BUS_ERROR" "3" "" "systemd 214" "sd_bus_error" | |
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_bus_error, sd_bus_error_free, sd_bus_error_set, sd_bus_error_set_const, sd_bus_error_set_errno, sd_bus_error_set_errnof, sd_bus_error_get_errno, sd_bus_error_copy, sd_bus_error_is_set, sd_bus_error_has_name \- sd\-bus error handling | |
24 | .SH "SYNOPSIS" | |
25 | .sp | |
26 | .ft B | |
27 | .nf | |
28 | #include <systemd/sd\-bus\&.h> | |
29 | .fi | |
30 | .ft | |
31 | .sp | |
32 | .ft B | |
33 | .nf | |
34 | typedef struct { | |
35 | const char *name; | |
36 | const char *message; | |
37 | \&.\&.\&. | |
38 | } sd_bus_error; | |
39 | .fi | |
40 | .ft | |
41 | .PP | |
42 | \fBSD_BUS_ERROR_MAKE_CONST(\fR\fB\fIname\fR\fR\fB, \fR\fB\fImessage\fR\fR\fB)\fR | |
43 | .PP | |
44 | \fBSD_BUS_ERROR_NULL\fR | |
45 | .HP \w'int\ sd_bus_error_free('u | |
46 | .BI "int sd_bus_error_free(sd_bus_error\ *" "e" ");" | |
47 | .HP \w'int\ sd_bus_error_set('u | |
48 | .BI "int sd_bus_error_set(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "message" ");" | |
49 | .HP \w'int\ sd_bus_error_setf('u | |
50 | .BI "int sd_bus_error_setf(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "format" ", \&.\&.\&.);" | |
51 | .HP \w'int\ sd_bus_error_set_const('u | |
52 | .BI "int sd_bus_error_set_const(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "message" ");" | |
53 | .HP \w'int\ sd_bus_error_set_errno('u | |
54 | .BI "int sd_bus_error_set_errno(sd_bus_error\ *" "e" ", int\ " "error" ");" | |
55 | .HP \w'int\ sd_bus_error_set_errnof('u | |
56 | .BI "int sd_bus_error_set_errnof(sd_bus_error\ *" "e" ", int\ " "error" ", const\ char\ *" "format" ", \&.\&.\&.);" | |
57 | .HP \w'int\ sd_bus_error_get_errno('u | |
58 | .BI "int sd_bus_error_get_errno(const\ sd_bus_error\ *" "e" ");" | |
59 | .HP \w'int\ sd_bus_error_copy('u | |
60 | .BI "int sd_bus_error_copy(sd_bus_error\ *" "dst" ", const\ sd_bus_error\ *" "e" ");" | |
61 | .HP \w'int\ sd_bus_error_is_set('u | |
62 | .BI "int sd_bus_error_is_set(const\ sd_bus_error\ *" "e" ");" | |
63 | .HP \w'int\ sd_bus_error_has_name('u | |
64 | .BI "int sd_bus_error_has_name(const\ sd_bus_error\ *" "e" ", const\ char\ *" "name" ");" | |
65 | .PP | |
66 | \fBSD_BUS_ERROR_FAILED\fR | |
67 | .PP | |
68 | \fBSD_BUS_ERROR_NO_MEMORY\fR | |
69 | .PP | |
70 | \fBSD_BUS_ERROR_SERVICE_UNKNOWN\fR | |
71 | .PP | |
72 | \fBSD_BUS_ERROR_NAME_HAS_NO_OWNER\fR | |
73 | .PP | |
74 | \fBSD_BUS_ERROR_NO_REPLY\fR | |
75 | .PP | |
76 | \fBSD_BUS_ERROR_IO_ERROR\fR | |
77 | .PP | |
78 | \fBSD_BUS_ERROR_BAD_ADDRESS\fR | |
79 | .PP | |
80 | \fBSD_BUS_ERROR_NOT_SUPPORTED\fR | |
81 | .PP | |
82 | \fBSD_BUS_ERROR_LIMITS_EXCEEDED\fR | |
83 | .PP | |
84 | \fBSD_BUS_ERROR_ACCESS_DENIED\fR | |
85 | .PP | |
86 | \fBSD_BUS_ERROR_AUTH_FAILED\fR | |
87 | .PP | |
88 | \fBSD_BUS_ERROR_NO_SERVER\fR | |
89 | .PP | |
90 | \fBSD_BUS_ERROR_TIMEOUT\fR | |
91 | .PP | |
92 | \fBSD_BUS_ERROR_NO_NETWORK\fR | |
93 | .PP | |
94 | \fBSD_BUS_ERROR_ADDRESS_IN_USE\fR | |
95 | .PP | |
96 | \fBSD_BUS_ERROR_DISCONNECTED\fR | |
97 | .PP | |
98 | \fBSD_BUS_ERROR_INVALID_ARGS\fR | |
99 | .PP | |
100 | \fBSD_BUS_ERROR_FILE_NOT_FOUND\fR | |
101 | .PP | |
102 | \fBSD_BUS_ERROR_FILE_EXISTS\fR | |
103 | .PP | |
104 | \fBSD_BUS_ERROR_UNKNOWN_METHOD\fR | |
105 | .PP | |
106 | \fBSD_BUS_ERROR_UNKNOWN_OBJECT\fR | |
107 | .PP | |
108 | \fBSD_BUS_ERROR_UNKNOWN_INTERFACE\fR | |
109 | .PP | |
110 | \fBSD_BUS_ERROR_UNKNOWN_PROPERTY\fR | |
111 | .PP | |
112 | \fBSD_BUS_ERROR_PROPERTY_READ_ONLY\fR | |
113 | .PP | |
114 | \fBSD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN\fR | |
115 | .PP | |
116 | \fBSD_BUS_ERROR_INVALID_SIGNATURE\fR | |
117 | .PP | |
118 | \fBSD_BUS_ERROR_INCONSISTENT_MESSAGE\fR | |
119 | .PP | |
120 | \fBSD_BUS_ERROR_MATCH_RULE_NOT_FOUND\fR | |
121 | .PP | |
122 | \fBSD_BUS_ERROR_MATCH_RULE_INVALID\fR | |
123 | .SH "DESCRIPTION" | |
124 | .PP | |
125 | The | |
126 | sd_bus_error | |
127 | structure carries information for a | |
128 | sd\-bus | |
129 | error\&. The functions described below can be used to set and query fields in this structure\&. The | |
130 | \fIname\fR | |
131 | field contains a short identifier of an error\&. It should follow the rules for error names described in the D\-Bus specification, subsection | |
132 | \m[blue]\fBValid Names\fR\m[]\&\s-2\u[1]\d\s+2\&. The | |
133 | \fImessage\fR | |
134 | is a human readable string describing the details\&. When no longer necessary, resources held by this structure should be destroyed with | |
135 | \fBsd_bus_error_free\fR\&. | |
136 | .PP | |
137 | \fBsd_bus_error_set\fR | |
138 | will return an errno\-like negative value returned based on parameter | |
139 | \fIname\fR | |
140 | (see | |
141 | \fBerrno\fR(3))\&. Various well\-known D\-Bus errors are converted to specific values, and the remaining ones to | |
142 | \fB\-ENXIO\fR\&. Well\-known D\-Bus error names are available as constants | |
143 | \fBSD_BUS_ERROR_FAILED\fR, etc\&., listed above\&. If | |
144 | \fIname\fR | |
145 | is | |
146 | \fBNULL\fR, it is assumed that no error occured, and 0 is returned\&. This means that this function may be conveniently used in a | |
147 | \fBreturn\fR | |
148 | statement\&. | |
149 | .PP | |
150 | If | |
151 | \fIe\fR | |
152 | is not | |
153 | \fBNULL\fR, | |
154 | \fIname\fR | |
155 | and | |
156 | \fImessage\fR | |
157 | in the | |
158 | sd_bus_error | |
159 | structure | |
160 | \fIe\fR | |
161 | points at will be filled in\&. As described above, | |
162 | \fIname\fR | |
163 | may be | |
164 | \fBNULL\fR, which is treated as no error\&. Parameter | |
165 | \fImessage\fR | |
166 | may also be | |
167 | \fBNULL\fR, in which case no message is specified\&. | |
168 | \fBsd_bus_error_set\fR | |
169 | will make internal copies of specified strings\&. | |
170 | .PP | |
171 | \fBsd_bus_error_setf\fR | |
172 | is similar to | |
173 | \fBsd_bus_error_set\fR, but takes a | |
174 | \fBprintf\fR(3) | |
175 | format string and corresponding arguments to generate | |
176 | message\&. | |
177 | .PP | |
178 | \fBsd_bus_error_set_const\fR | |
179 | is similar to | |
180 | \fBsd_bus_error_set\fR, but string parameters are not copied internally, and must remain valid for the lifetime of | |
181 | \fIe\fR\&. | |
182 | .PP | |
183 | \fBsd_bus_error_set_errno\fR | |
184 | will set | |
185 | \fIname\fR | |
186 | based on an errno\-like value\&. | |
187 | \fBstrerror\fR(3) | |
188 | will be used to set | |
189 | \fImessage\fR\&. Well\-known D\-Bus error names will be used for | |
190 | \fIname\fR | |
191 | if available, otherwise a name in the | |
192 | "System\&.Error" | |
193 | namespace will be generated\&. | |
194 | .PP | |
195 | \fBsd_bus_error_set_errnof\fR | |
196 | is similar to | |
197 | \fBsd_bus_error_set_errno\fR, but in addition to | |
198 | \fIname\fR, takes a | |
199 | \fBprintf\fR(3) | |
200 | format and corresponding arguments\&. | |
201 | \fIname\fR | |
202 | will be generated from | |
203 | \fIformat\fR | |
204 | and the arguments\&. | |
205 | .PP | |
206 | \fBsd_bus_error_get_errno\fR | |
207 | is will convert | |
208 | e\->name | |
209 | to an errno\-like value using the same rules as | |
210 | \fBsd_bus_error_set\fR\&. If | |
211 | \fIe\fR | |
212 | is | |
213 | \fBNULL\fR, 0 will be returned\&. | |
214 | .PP | |
215 | \fBsd_bus_error_copy\fR | |
216 | will initialize | |
217 | \fIdst\fR | |
218 | using the values in | |
219 | \fIe\fR\&. If the strings in | |
220 | \fIe\fR | |
221 | were set using | |
222 | \fBsd_bus_set_error_const\fR, they will be shared\&. Otherwise, they will be copied\&. | |
223 | .PP | |
224 | \fBsd_bus_error_is_set\fR | |
225 | will return | |
226 | \fBtrue\fR | |
227 | if | |
228 | \fIe\fR | |
229 | is non\-\fBNULL\fR | |
230 | and an error has been set, | |
231 | \fBfalse\fR | |
232 | otherwise\&. | |
233 | .PP | |
234 | \fBsd_bus_error_has_name\fR | |
235 | will return true if | |
236 | \fIe\fR | |
237 | is non\-\fBNULL\fR | |
238 | and an error with the same | |
239 | \fIname\fR | |
240 | has been set, | |
241 | \fBfalse\fR | |
242 | otherwise\&. | |
243 | .PP | |
244 | \fBsd_bus_error_free\fR | |
245 | will destroy resources held by | |
246 | \fIe\fR\&. The parameter itself will not be deallocated, and must be | |
247 | \fBfree\fR(3)d by the caller if necessary\&. | |
248 | .SH "RETURN VALUE" | |
249 | .PP | |
250 | Functions | |
251 | \fBsd_bus_error_set\fR, | |
252 | \fBsd_bus_error_setf\fR, | |
253 | \fBsd_bus_error_set_const\fR, when successful, return the negative errno value corresponding to the | |
254 | \fIname\fR | |
255 | parameter\&. Functions | |
256 | \fBsd_bus_error_set_errno\fR | |
257 | and | |
258 | \fBsd_bus_error_set_errnof\fR, when successful, return the value of the | |
259 | \fIerrno\fR | |
260 | parameter\&. If an error occurs, one of the negative error values listed below will be returned\&. | |
261 | .PP | |
262 | \fBsd_bus_error_get_errno\fR | |
263 | returns | |
264 | \fBfalse\fR | |
265 | when | |
266 | \fIe\fR | |
267 | is | |
268 | \fBNULL\fR, and a positive errno value mapped from | |
269 | \fIe\->name\fR | |
270 | otherwise\&. | |
271 | .PP | |
272 | \fBsd_bus_error_copy\fR | |
273 | returns 0 or a positive integer on success, and one of the negative error values listed below otherwise\&. | |
274 | .PP | |
275 | \fBsd_bus_error_is_set\fR | |
276 | returns | |
277 | \fBtrue\fR | |
278 | when | |
279 | \fIe\fR | |
280 | and | |
281 | \fIe\->name\fR | |
282 | are non\-\fBNULL\fR, | |
283 | \fBfalse\fR | |
284 | otherwise\&. | |
285 | .PP | |
286 | \fBsd_bus_error_has_name\fR | |
287 | returns | |
288 | \fBtrue\fR | |
289 | when | |
290 | \fIe\fR | |
291 | is non\-\fBNULL\fR | |
292 | and | |
293 | \fIe\->name\fR | |
294 | is equal to | |
295 | \fIname\fR, | |
296 | \fBfalse\fR | |
297 | otherwise\&. | |
298 | .SH "REFERENCE OWNERSHIP" | |
299 | .PP | |
300 | sd_bus_error | |
301 | is not reference counted\&. Users should destroy resources held by it by calling | |
302 | \fBsd_bus_error_free\fR\&. | |
303 | .SH "ERRORS" | |
304 | .PP | |
305 | Returned errors may indicate the following problems: | |
306 | .PP | |
307 | \fI\-EINVAL\fR | |
308 | .RS 4 | |
309 | Error was already set in | |
310 | sd_bus_error | |
311 | structure when one the error\-setting functions was called\&. | |
312 | .RE | |
313 | .PP | |
314 | \fI\-ENOMEM\fR | |
315 | .RS 4 | |
316 | Memory allocation failed\&. | |
317 | .RE | |
318 | .SH "NOTES" | |
319 | .PP | |
320 | \fBsd_bus_set_error()\fR | |
321 | and other functions described here are available as a shared library, which can be compiled and linked to with the | |
322 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) | |
323 | file\&. | |
324 | .SH "SEE ALSO" | |
325 | .PP | |
326 | \fBsystemd\fR(1), | |
327 | \fBsd-bus\fR(3), | |
328 | \fBerrno\fR(3), | |
329 | \fBstrerror\fR(3) | |
330 | .SH "NOTES" | |
331 | .IP " 1." 4 | |
332 | Valid Names | |
333 | .RS 4 | |
334 | \%http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names | |
335 | .RE |