SD_BUS_ERROR(3)

NAME
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

SYNOPSIS

#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

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[1]. 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:

-EINVAL
    Error was already set in sd_bus_error structure when one the error-setting functions was called.

-ENOMEM
    Memory allocation failed.

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)

NOTES

1.  Valid Names
    http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names