systemd A monkey with a typewriter Zbigniew Jędrzejewski-Szmek zbyszek@in.waw.pl sd_bus_error 3 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 libsystemd-bus error handling #include <systemd/sd-bus.h> typedef struct { const char *name; const char *message; ... } sd_bus_error; SD_BUS_ERROR_MAKE_CONST(name, message) SD_BUS_ERROR_NULL int sd_bus_error_free sd_bus_error *e int sd_bus_error_set sd_bus_error *e const char *name const char *message int sd_bus_error_setf sd_bus_error *e const char *name const char *format ... int sd_bus_error_set_const sd_bus_error *e const char *name const char *message int sd_bus_error_set_errno sd_bus_error *e int error int sd_bus_error_set_errnof sd_bus_error *e int error const char *format ... int sd_bus_error_get_errno const sd_bus_error *e int sd_bus_error_copy sd_bus_error *dst const sd_bus_error *e int sd_bus_error_is_set const sd_bus_error *e int sd_bus_error_has_name const sd_bus_error *e const char *name SD_BUS_ERROR_FAILED SD_BUS_ERROR_NO_MEMORY SD_BUS_ERROR_SERVICE_UNKNOWN SD_BUS_ERROR_NAME_HAS_NO_OWNER SD_BUS_ERROR_NO_REPLY SD_BUS_ERROR_IO_ERROR SD_BUS_ERROR_BAD_ADDRESS SD_BUS_ERROR_NOT_SUPPORTED SD_BUS_ERROR_LIMITS_EXCEEDED SD_BUS_ERROR_ACCESS_DENIED SD_BUS_ERROR_AUTH_FAILED SD_BUS_ERROR_NO_SERVER SD_BUS_ERROR_TIMEOUT SD_BUS_ERROR_NO_NETWORK SD_BUS_ERROR_ADDRESS_IN_USE SD_BUS_ERROR_DISCONNECTED SD_BUS_ERROR_INVALID_ARGS SD_BUS_ERROR_FILE_NOT_FOUND SD_BUS_ERROR_FILE_EXISTS SD_BUS_ERROR_UNKNOWN_METHOD SD_BUS_ERROR_UNKNOWN_OBJECT SD_BUS_ERROR_UNKNOWN_INTERFACE SD_BUS_ERROR_UNKNOWN_PROPERTY SD_BUS_ERROR_PROPERTY_READ_ONLY SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN SD_BUS_ERROR_INVALID_SIGNATURE SD_BUS_ERROR_INCONSISTENT_MESSAGE SD_BUS_ERROR_MATCH_RULE_NOT_FOUND SD_BUS_ERROR_MATCH_RULE_INVALID sd_bus_error structure carries information for a libsystemd-bus error. Functions described below can be used to set and query fields in this structure. Field name 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 errno3). 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 is assumed that no error occured, 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 will be filled-in in the sd_bus_error structure e points at. 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 printf3 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. strerror3 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 printf3 format and corresponding arguments. name will be generated from format and the arguments. sd_bus_error_get_errno is 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. Otherwie they wil 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 free3d by the caller if necessary. 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. sd_bus_error is not reference counted. Users should destroy resources held by it by calling sd_bus_error_free. Returned errors may indicate the following problems: -EINVAL Error was already set in sd_bus_error structure when one the error-setting functions was called. -ENOMEM Memory allocation failed. 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-bus pkg-config1 file. systemd1, sd-bus3, errno3, strerror3