sd_bus_error

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`

## 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 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 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` 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. 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 3d 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