Description¶

The sd_bus_error structure carries information for a sd-bus error. The functions described below can be used to set and query fields in this structure. The name field contains a short identifier of an error. It should follow the rules for error names described in the D-Bus specification, subsection Valid Names. The message is a human readable string describing the details. When no longer necessary, resources held by this structure should be destroyed with sd_bus_error_free.

sd_bus_error_set will return an errno-like negative value returned based on parameter name (see errno(3)). Various well-known D-Bus errors are converted to specific values, and the remaining ones to -ENXIO. Well-known D-Bus error names are available as constants SD_BUS_ERROR_FAILED, etc., listed above. If name is NULL, it is assumed that no error occurred, and 0 is returned. This means that this function may be conveniently used in a return statement.

If e is not NULL, name and message in the sd_bus_error structure e points at will be filled in. As described above, name may be NULL, which is treated as no error. Parameter message may also be NULL, in which case no message is specified. sd_bus_error_set will make internal copies of specified strings.

sd_bus_error_setf is similar to sd_bus_error_set, but takes a printf(3) format string and corresponding arguments to generate message.

sd_bus_error_set_const is similar to sd_bus_error_set, but string parameters are not copied internally, and must remain valid for the lifetime of e.

sd_bus_error_set_errno will set name based on an errno-like value. strerror(3) will be used to set message. Well-known D-Bus error names will be used for name if available, otherwise a name in the "System.Error" namespace will be generated.

sd_bus_error_set_errnof is similar to sd_bus_error_set_errno, but in addition to name, takes a printf(3) format and corresponding arguments. name will be generated from format and the arguments.

sd_bus_error_get_errno will convert e->name to an errno-like value using the same rules as sd_bus_error_set. If e is NULL, 0 will be returned.

sd_bus_error_copy will initialize dst using the values in e. If the strings in e were set using sd_bus_set_error_const, they will be shared. Otherwise, they will be copied.

sd_bus_error_is_set will return true if e is non-NULL and an error has been set, false otherwise.

sd_bus_error_has_name will return true if e is non-NULL and an error with the same name has been set, false otherwise.

sd_bus_error_free will destroy resources held by e. The parameter itself will not be deallocated, and must be free(3)d by the caller if necessary.

Return Value¶

Functions sd_bus_error_set, sd_bus_error_setf, sd_bus_error_set_const, when successful, return the negative errno value corresponding to the name parameter. Functions sd_bus_error_set_errno and sd_bus_error_set_errnof, when successful, return the value of the errno parameter. If an error occurs, one of the negative error values listed below will be returned.

sd_bus_error_get_errno returns false when e is NULL, and a positive errno value mapped from e->name otherwise.

sd_bus_error_copy returns 0 or a positive integer on success, and one of the negative error values listed below otherwise.

sd_bus_error_is_set returns true when e and e->name are non-NULL, false otherwise.

sd_bus_error_has_name returns true when e is non-NULL and e->name is equal to name, false otherwise.

Reference ownership¶

sd_bus_error is not reference counted. Users should destroy resources held by it by calling sd_bus_error_free.

Errors¶

Returned errors may indicate the following problems:

Notes¶

sd_bus_set_error() and other functions described here are available as a shared library, which can be compiled and linked to with the libsystemd pkg-config(1) file.

See Also¶

systemd(1), sd-bus(3), errno(3), strerror(3)