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 sd-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 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 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 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 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 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 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 pkg-config1 file. systemd1, sd-bus3, errno3, strerror3