# sd_bus_error

## 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 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**
    
           **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 D-Bus Names******[1]. A number of
               common, standardized error names are described insd-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**.
    
           An unset sd_bus_error structure should have both fields
           initialized to **NULL** , and signifies lack of an error, i.e. success.
           Assign **SD_BUS_ERROR_NULL** to the structure in order to initialize
           both fields to **NULL**. When no longer necessary, resources held by
           the sd_bus_error structure should be destroyed with
           **sd_bus_error_free()**.
    
           **sd_bus_error_set()** sets an error structure to the specified name
           and message strings. The strings will be copied into internal,
           newly allocated memory. It is essential to free the contents again
           when they are not required anymore (see above). Do not use this
           call on error structures that have already been set. If you intend
           to reuse an error structure, free the old data stored in it with
           **sd_bus_error_free()** first.
    
           **sd_bus_error_set()** will return an _errno_ -like value (see errno(3))
           determined from the specified error name _name_. If _name_ is **NULL** , it
           is assumed that no error occurred, and **0** is returned. If _name_ is
           nonnull, a negative value is always returned. If _e_ is **NULL** , no
           error structure is initialized, but _name_ is still converted into
           an _errno_ -style value.
    
           Various well-known D-Bus errors are converted to well-known _errno_
           counterparts, and the other ones to **-EIO**. See sd-bus-errors(3) for
           a list of well-known error names. Additional error mappings may be
           defined with sd_bus_error_add_map(3).
    
           **sd_bus_error_set()** is designed to be conveniently used in a **return**
           statement. If _message_ is **NULL** , no message is set. This call can
           fail if no memory may be allocated for the name and message
           strings, in which case an **SD_BUS_ERROR_NO_MEMORY** error will be set
           instead and **-ENOMEM** returned.
    
           **sd_bus_error_setf()** and **sd_bus_error_setfv()** are similar to
           **sd_bus_error_set()** , but take a printf(3) format string and
           corresponding arguments to generate the _message_ field.
           **sd_bus_error_setf()** uses variadic arguments, and
           **sd_bus_error_setfv()** accepts the arguments as a va_arg(3)
           parameter list.
    
           **sd_bus_error_set_const()** is similar to **sd_bus_error_set()** , but the
           string parameters are not copied internally, and must hence remain
           constant and valid for the lifetime of _e_. Use this call to avoid
           memory allocations when setting error structures. Since this call
           does not allocate memory, it will not fail with an out-of-memory
           condition as **sd_bus_error_set()** may, as described above.
           Alternatively, the **SD_BUS_ERROR_MAKE_CONST()** macro may be used to
           generate a literal, constant bus error structure on-the-fly.
    
           **sd_bus_error_set_errno()** will immediately return **0** if the
           specified error parameter _error_ is **0**. Otherwise, it will set _name_
           from an _errno_ -like value that is converted to a D-Bus error.
           strerror_r(3) will be used to set _message_. Well-known D-Bus error
           names will be used for _name_ if applicable, otherwise a name in the
           "System.Error."  namespace will be generated. The sign of the
           specified error number is ignored and the absolute value is used
           implicitly. If the specified error _error_ is non-zero, the call
           always returns a negative value, for convenient usage in **return**
           statements. This call might fail due to lack of memory, in which
           case an **SD_BUS_ERROR_NO_MEMORY** error is set instead, and **-ENOMEM**
           is returned.
    
           **sd_bus_error_set_errnof()** and **sd_bus_error_set_errnof()** are
           similar to **sd_bus_error_set_errno()** , but in addition to _error_ ,
           take a printf(3) format string and corresponding arguments. The
           _message_ field will be generated from _format_ and the arguments.
           **sd_bus_error_set_errnof()** uses variadic arguments, and
           **sd_bus_error_set_errnofv()** accepts the arguments as a va_arg(3)
           parameter list.
    
           **sd_bus_error_get_errno()** converts the _name_ field of an error
           structure to an _errno_ -like (positive) 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
           _e_ has been set with an error value before. Otherwise, it will
           return immediately. If the strings in _e_ were set using
           **sd_bus_error_set_const()** , they will be shared. Otherwise, they
           will be copied. Before this call, _dst_ must be unset, i.e. either
           freshly initialized with **NULL** or reset using **sd_bus_error_free()**.
    
           **sd_bus_error_copy()** generally returns **0** or a negative _errno_ -like
           value based on the input parameter _e_ : **0** if it was unset and a
           negative integer if it was set to some error, similarly to
           **sd_bus_error_set()**. It may however also return an error generated
           internally, for example **-ENOMEM** if a memory allocation fails.
    
           **sd_bus_error_move()** is similar to **sd_bus_error_copy()** , but will
           move any error information from _e_ into _dst_ , resetting the former.
           This function cannot fail, as no new memory is allocated. Note
           that if _e_ is not set, _dst_ is initialized to **SD_BUS_ERROR_NULL**.
           Moreover, if _dst_ is **NULL** no operation is executed on it and
           resources held by _e_ are freed and reset. Returns a converted
           _errno_ -like, non-positive error value.
    
           **sd_bus_error_is_set()** will return a non-zero value if _e_ is
           non-**NULL** and an error has been set, **false** otherwise.
    
           **sd_bus_error_has_name()** will return a non-zero value if _e_ is
           non-**NULL** and an error with the same _name_ has been set, **false**
           otherwise.
    
           **sd_bus_error_has_names_sentinel()** is similar to
           **sd_bus_error_has_name()** , but takes multiple names to check
           against. The list must be terminated with **NULL**.
           **sd_bus_error_has_names()** is a macro wrapper around
           **sd_bus_error_has_names_sentinel()** that adds the **NULL** sentinel
           automatically.
    
           **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. The function may also be called safely on
           unset errors (error structures with both fields set to **NULL**), in
           which case it performs no operation. This call will reset the
           error structure after freeing the data, so that all fields are set
           to **NULL**. The structure may be reused afterwards.
    


## 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:
    
           **-EINVAL**
               Error 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: %s", fd, strerror(errno));
               }
    


## NOTES



           Functions described here are available as a shared library, which
           can be compiled against and linked to with the
           **libsystemd pkg-config**(1) file.
    
           The code described here uses getenv(3), which is declared to be
           not multi-thread-safe. This means that the code calling the
           functions described here must not call setenv(3) from a parallel
           thread. It is recommended to only do calls to **setenv()** from an
           early phase of the program when no other threads have been
           started.
    


## NOTES



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


* * *