1SD_BUS_ERROR(3)                  sd_bus_error                  SD_BUS_ERROR(3)
2
3
4

NAME

6       sd_bus_error, SD_BUS_ERROR_MAKE_CONST, SD_BUS_ERROR_NULL,
7       sd_bus_error_free, sd_bus_error_set, sd_bus_error_setf,
8       sd_bus_error_set_const, sd_bus_error_set_errno,
9       sd_bus_error_set_errnof, sd_bus_error_set_errnofv,
10       sd_bus_error_get_errno, sd_bus_error_copy, sd_bus_error_is_set,
11       sd_bus_error_has_name - sd-bus error handling
12

SYNOPSIS

14       #include <systemd/sd-bus.h>
15
16       typedef struct {
17               const char *name;
18               const char *message;
19               ...
20       } sd_bus_error;
21
22       SD_BUS_ERROR_MAKE_CONST(name, message)
23
24       SD_BUS_ERROR_NULL
25
26       void sd_bus_error_free(sd_bus_error *e);
27
28       int sd_bus_error_set(sd_bus_error *e, const char *name,
29                            const char *message);
30
31       int sd_bus_error_setf(sd_bus_error *e, const char *name,
32                             const char *format, ...);
33
34       int sd_bus_error_set_const(sd_bus_error *e, const char *name,
35                                  const char *message);
36
37       int sd_bus_error_set_errno(sd_bus_error *e, int error);
38
39       int sd_bus_error_set_errnof(sd_bus_error *e, int error,
40                                   const char *format, ...);
41
42       int sd_bus_error_set_errnofv(sd_bus_error *e, int error,
43                                    const char *format, va_list ap);
44
45       int sd_bus_error_get_errno(const sd_bus_error *e);
46
47       int sd_bus_error_copy(sd_bus_error *dst, const sd_bus_error *e);
48
49       int sd_bus_error_is_set(const sd_bus_error *e);
50
51       int sd_bus_error_has_name(const sd_bus_error *e, const char *name);
52

DESCRIPTION

54       The sd_bus_error structure carries information about a D-Bus error
55       condition. The functions described below may be used to set and query
56       fields in this structure. The name field contains a short identifier of
57       an error. It should follow the rules for error names described in the
58       D-Bus specification, subsection Valid Names[1]. A number of common,
59       standardized error names are described in sd-bus-errors(3), but
60       additional domain-specific errors may be defined by applications. The
61       message field usually contains a human-readable string describing the
62       details, but might be NULL. An unset sd_bus_error structure should have
63       both fields initialized to NULL. Set an error structure to
64       SD_BUS_ERROR_NULL in order to reset both fields to NULL. When no longer
65       necessary, resources held by the sd_bus_errorstructure should be
66       destroyed with sd_bus_error_free().
67
68       sd_bus_error_set() sets an error structure to the specified name and
69       message strings. The strings will be copied into internal, newly
70       allocated memory. It is essential to free the error structure again
71       when it is not required anymore (see above). The function will return
72       an errno-like negative value (see errno(3)) determined from the
73       specified error name. Various well-known D-Bus errors are converted to
74       well-known errno counterparts, and the other ones to -EIO. See sd-bus-
75       errors(3) for a list of well-known error names. Additional error
76       mappings may be defined with sd_bus_error_add_map(3). If e is NULL, no
77       error structure is initialized, but the error is still converted into
78       an errno-style error. If name is NULL, it is assumed that no error
79       occurred, and 0 is returned. This means that this function may be
80       conveniently used in a return statement. If message is NULL, no message
81       is set. This call can fail if no memory may be allocated for the name
82       and message strings, in which case an SD_BUS_ERROR_NO_MEMORY error
83       might be set instead and -ENOMEM be returned. Do not use this call on
84       error structures that are already initialized. If you intend to reuse
85       an error structure, free the old data stored in it with
86       sd_bus_error_free() first.
87
88       sd_bus_error_setf() is similar to sd_bus_error_set(), but takes a
89       printf(3) format string and corresponding arguments to generate the
90       message field.
91
92       sd_bus_error_set_const() is similar to sd_bus_error_set(), but the
93       string parameters are not copied internally, and must hence remain
94       constant and valid for the lifetime of e. Use this call to avoid memory
95       allocations when setting error structures. Since this call does not
96       allocate memory, it will not fail with an out-of-memory condition as
97       sd_bus_error_set() can, as described above. Alternatively, the
98       SD_BUS_ERROR_MAKE_CONST() macro may be used to generate a literal,
99       constant bus error structure on-the-fly.
100
101       sd_bus_error_set_errno() will set name from an errno-like value that is
102       converted to a D-Bus error.  strerror_r(3) will be used to set message.
103       Well-known D-Bus error names will be used for name if applicable,
104       otherwise a name in the "System.Error."  namespace will be generated.
105       The sign of the specified error number is ignored. The absolute value
106       is used implicitly. The call always returns a negative value, for
107       convenient usage in return statements. This call might fail due to lack
108       of memory, in which case an SD_BUS_ERROR_NO_MEMORY error is set
109       instead, and -ENOMEM is returned.
110
111       sd_bus_error_set_errnof() is similar to sd_bus_error_set_errno(), but
112       in addition to error, takes a printf(3) format string and corresponding
113       arguments. The message field will be generated from format and the
114       arguments.
115
116       sd_bus_error_set_errnofv() is similar to sd_bus_error_set_errnof(), but
117       takes the format string parameters as va_arg(3) parameter list.
118
119       sd_bus_error_get_errno() converts the name field of an error structure
120       to an errno-like (positive) value using the same rules as
121       sd_bus_error_set(). If e is NULL, 0 will be returned.
122
123       sd_bus_error_copy() will initialize dst using the values in e. If the
124       strings in e were set using sd_bus_error_set_const(), they will be
125       shared. Otherwise, they will be copied. Returns a converted errno-like,
126       negative error code.
127
128       sd_bus_error_is_set() will return a non-zero value if e is non-NULL and
129       an error has been set, false otherwise.
130
131       sd_bus_error_has_name() will return a non-zero value if e is non-NULL
132       and an error with the same name has been set, false otherwise.
133
134       sd_bus_error_free() will destroy resources held by e. The parameter
135       itself will not be deallocated, and must be free(3)d by the caller if
136       necessary. The function may also be called safely on unset errors
137       (error structures with both fields set to NULL), in which case it
138       performs no operation. This call will reset the error structure after
139       freeing the data, so that all fields are set to NULL. The structure may
140       be reused afterwards.
141

RETURN VALUE

143       The functions sd_bus_error_set(), sd_bus_error_setf(), and
144       sd_bus_error_set_const(), when successful, return the negative errno
145       value corresponding to the name parameter. The functions
146       sd_bus_error_set_errno(), sd_bus_error_set_errnof() and
147       sd_bus_error_set_errnofv(), when successful, return the negative value
148       of the error parameter. If an error occurs, one of the negative error
149       values listed below will be returned.
150
151       sd_bus_error_get_errno() returns false when e is NULL, and a positive
152       errno value mapped from e->name otherwise.
153
154       sd_bus_error_copy() returns 0 or a positive integer on success, and a
155       negative error value converted from the error name otherwise.
156
157       sd_bus_error_is_set() returns a non-zero value when e and the name
158       field are non-NULL, zero otherwise.
159
160       sd_bus_error_has_name() returns a non-zero value when e is non-NULL and
161       the name field is equal to name, zero otherwise.
162

REFERENCE OWNERSHIP

164       sd_bus_error is not reference counted. Users should destroy resources
165       held by it by calling sd_bus_error_free(). Usually, error structures
166       are allocated on the stack or passed in as function parameters, but
167       they may also be allocated dynamically, in which case it is the duty of
168       the caller to free(3) the memory held by the structure itself after
169       freeing its contents with sd_bus_error_free().
170

ERRORS

172       Returned errors may indicate the following problems:
173
174       -EINVAL
175           Error was already set in sd_bus_error structure when one the
176           error-setting functions was called.
177
178       -ENOMEM
179           Memory allocation failed.
180

NOTES

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

SEE ALSO

186       systemd(1), sd-bus(3), sd-bus-errors(3), sd_bus_error_add_map(3),
187       errno(3), strerror_r(3)
188

NOTES

190        1. Valid Names
191           http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names
192
193
194
195systemd 239                                                    SD_BUS_ERROR(3)
Impressum