1SD_BUS_ERROR(3) sd_bus_error SD_BUS_ERROR(3)
2
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
14 #include <systemd/sd-bus.h>
15 typedef struct {
17 const char *name;
18 const char *message;
19 ...
20 } sd_bus_error;
21 SD_BUS_ERROR_MAKE_CONST(name, message)
23 SD_BUS_ERROR_NULL
25 void sd_bus_error_free(sd_bus_error *e);
27 int sd_bus_error_set(sd_bus_error *e, const char *name,
29 const char *message);
30 int sd_bus_error_setf(sd_bus_error *e, const char *name,
32 const char *format, ...);
33 int sd_bus_error_set_const(sd_bus_error *e, const char *name,
35 const char *message);
36 int sd_bus_error_set_errno(sd_bus_error *e, int error);
38 int sd_bus_error_set_errnof(sd_bus_error *e, int error,
40 const char *format, ...);
41 int sd_bus_error_set_errnofv(sd_bus_error *e, int error,
43 const char *format, va_list ap);
44 int sd_bus_error_get_errno(const sd_bus_error *e);
46 int sd_bus_error_copy(sd_bus_error *dst, const sd_bus_error *e);
48 int sd_bus_error_is_set(const sd_bus_error *e);
50 int sd_bus_error_has_name(const sd_bus_error *e, const char *name);
52
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 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 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 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 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 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 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 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 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 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 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 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
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 sd_bus_error_get_errno() returns false when e is NULL, and a positive
152 errno value mapped from e->name otherwise.
153 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 sd_bus_error_is_set() returns a non-zero value when e and the name
158 field are non-NULL, zero otherwise.
159 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
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
172 Returned errors may indicate the following problems:
173 -EINVAL
175 Error was already set in sd_bus_error structure when one the
176 error-setting functions was called.
177 -ENOMEM
179 Memory allocation failed.
180
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
186 systemd(1), sd-bus(3), sd-bus-errors(3), sd_bus_error_add_map(3),
187 errno(3), strerror_r(3)
188
190 1. Valid Names
191 http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names
192systemd 239 SD_BUS_ERROR(3)