sd_bus_error

Index · Directives · Python · libudev · gudev systemd 215

## 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. 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(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)