NAME
sd_bus_error, SD_BUS_ERROR_MAKE_CONST, SD_BUS_ERROR_NULL, sd_bus_error_free, sd_bus_error_set, sd_bus_error_setf, sd_bus_error_setfv, sd_bus_error_set_const, sd_bus_error_set_errno, sd_bus_error_set_errnof, sd_bus_error_set_errnofv, sd_bus_error_get_errno, sd_bus_error_copy, sd_bus_error_move, sd_bus_error_is_set, sd_bus_error_has_name, sd_bus_error_has_names_sentinel, sd_bus_error_has_names - sd-bus error handlingSYNOPSIS
#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
void
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_setfv(sd_bus_error *e,
const char *name,
const char *format,
va_list ap);
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_set_errnofv(sd_bus_error *e,
int error,
const char *format,
va_list ap);
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_move(sd_bus_error *dst,
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);
int
sd_bus_error_has_names_sentinel(const sd_bus_error *e,
...);
#define sd_bus_error_has_names(e, ...) sd_bus_error_has_names_sentinel(e, ...,
NULL)
DESCRIPTION
The sd_bus_error structure carries information about a D-Bus error condition, or lack thereof. The functions described below may 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]. A number of
common, standardized error names are described in sd-bus-errors(3), but
additional domain-specific errors may be defined by applications.
•The message field usually
contains a human-readable string describing the details, but might be
NULL.
REFERENCE OWNERSHIP
sd_bus_error is not reference-counted. Users should destroy resources held by it by calling sd_bus_error_free(). Usually, error structures are allocated on the stack or passed in as function parameters, but they may also be allocated dynamically, in which case it is the duty of the caller to free(3) the memory held by the structure itself after freeing its contents with sd_bus_error_free().RETURN VALUE
The functions sd_bus_error_set(), sd_bus_error_setf(), and sd_bus_error_set_const() always return 0 when the specified error value is NULL, and a negative errno-like value corresponding to the name parameter otherwise. The functions sd_bus_error_set_errno(), sd_bus_error_set_errnof() and sd_bus_error_set_errnofv(), return 0 when the specified error value is 0, and a negative errno-like value corresponding to the error parameter otherwise. If an error occurs internally, one of the negative error values listed below will be returned. This allows those functions to be conveniently used in a return statement, see the example below. 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() and sd_bus_error_move() return a negative error value converted from the source error, and zero if the error has not been set. This allows those functions to be conveniently used in a return statement, see the example below. sd_bus_error_is_set() returns a non-zero value when e and the name field are non- NULL, zero otherwise. sd_bus_error_has_name(), sd_bus_error_has_names(), and sd_bus_error_has_names_sentinel() return a non-zero value when e is non- NULL and the name field is equal to one of the given names, zero otherwise.Errors
Return value may indicate the following problems in the invocation of the function itself: -EINVALError was already set in the sd_bus_error
structure when one the error-setting functions was called.
-ENOMEM
Memory allocation failed.
On success, sd_bus_error_set(), sd_bus_error_setf(),
sd_bus_error_set_const(), sd_bus_error_set_errno(),
sd_bus_error_set_errnof(), sd_bus_error_set_errnofv(),
sd_bus_error_copy(), and sd_bus_error_move() will return a
negative converted errno-style value, or 0 if the error
parameter is NULL or unset. D-Bus errors are converted to the integral
errno-style value, and the mapping mechanism is extensible, see the
discussion above. This effectively means that almost any negative
errno-style value can be returned.
EXAMPLES
Example 1. Using the negative return value to propagate an error/* SPDX-License-Identifier: MIT-0 */ #include <errno.h> #include <string.h> #include <unistd.h> #include <systemd/sd-bus.h> int writer_with_negative_errno_return(int fd, sd_bus_error *error) { const char *message = "Hello, World!\n"; ssize_t n = write(fd, message, strlen(message)); if (n >= 0) return n; /* On success, return the number of bytes written, possibly 0. */ /* On error, initialize the error structure, and also propagate the errno * value that write(2) set for us. */ return sd_bus_error_set_errnof(error, errno, "Failed to write to fd %i: %m", fd); }
NOTES
These APIs are implemented 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), sd-bus-errors(3), sd_bus_error_add_map(3), errno(3), strerror_r(3)NOTES
- 1.
- Valid Names
systemd 252 |