From 2cb7e0aaedad73b076ea18c6900b0e86c5760d79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 15:00:47 +0200 Subject: Adding upstream version 247.3. Signed-off-by: Daniel Baumann --- man/sd_bus_error.xml | 384 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 384 insertions(+) create mode 100644 man/sd_bus_error.xml (limited to 'man/sd_bus_error.xml') diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml new file mode 100644 index 0000000..af2238e --- /dev/null +++ b/man/sd_bus_error.xml @@ -0,0 +1,384 @@ + + + + + + + + sd_bus_error + systemd + + + + sd_bus_error + 3 + + + + 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_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 + + + + + #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_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. 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. A number of common, standardized error names are + described in + sd-bus-errors3, + 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. Set an error + structure to SD_BUS_ERROR_NULL in order to + reset 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 error structure again when it is not + required anymore (see above). The function will return an + errno-like negative value (see errno3) + determined from the specified error name. Various well-known + D-Bus errors are converted to well-known errno + counterparts, and the other ones to -EIO. See + sd-bus-errors3 + for a list of well-known error names. Additional error mappings + may be defined with + sd_bus_error_add_map3. If + e is NULL, no error structure is initialized, + but the error is still converted into an + errno-style error. 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 + 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 might be set + instead and -ENOMEM be returned. Do not use this call on error + structures that are already initialized. If you intend to reuse an + error structure, free the old data stored in it with + sd_bus_error_free() first. + + sd_bus_error_setf() is similar to + sd_bus_error_set(), but takes a printf3 + format string and corresponding arguments to generate the + message field. + + 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() can, 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 set + name from an + errno-like value that is converted to a D-Bus + error. strerror_r3 + 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. The absolute value + is used implicitly. 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() is similar to + sd_bus_error_set_errno(), but in addition to + error, takes a printf3 + format string and corresponding arguments. The + message field will be generated from + format and the arguments. + + sd_bus_error_set_errnofv() is similar to + sd_bus_error_set_errnof(), but takes the + format string parameters as va_arg3 + 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 the strings in + e were set using + sd_bus_error_set_const(), they will be shared. + Otherwise, they will be copied. Returns a converted + errno-like, negative error code. + + 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 + (or NULL) dst is initializated to + SD_BUS_ERROR_NULL. Moreover, if dst is NULL no + operation is executed on it and and resources held by e are freed and reset. Returns a + converted errno-like, negative error code. + + 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 free3d + 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. + + + + Return Value + + The functions sd_bus_error_set(), + sd_bus_error_setf(), and + sd_bus_error_set_const(), when successful, + return the negative errno value corresponding to the + name parameter. The functions + sd_bus_error_set_errno(), + sd_bus_error_set_errnof() and + sd_bus_error_set_errnofv(), when successful, + return the negative value of the error + 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() and sd_bus_error_move() return 0 or a positive + integer on success, and a negative error value converted from the error name otherwise. + + 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. + + + + 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 free3 + the memory held by the structure itself after freeing its contents + with 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. + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd-bus-errors3, + sd_bus_error_add_map3, + errno3, + strerror_r3 + + + + -- cgit v1.2.3