From 8f2477715691f96b93d277b023f086203f76653f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 26 May 2022 14:04:52 +0200 Subject: [PATCH] man/sd-bus: discuss negative-return values and add example Fixes #22816. --- man/sd_bus_error-example.c | 18 ++++++++++ man/sd_bus_error.xml | 68 ++++++++++++++++++++++++++------------ 2 files changed, 65 insertions(+), 21 deletions(-) create mode 100644 man/sd_bus_error-example.c diff --git a/man/sd_bus_error-example.c b/man/sd_bus_error-example.c new file mode 100644 index 00000000000..abea13ca451 --- /dev/null +++ b/man/sd_bus_error-example.c @@ -0,0 +1,18 @@ +/* SPDX-License-Identifier: CC0-1.0 */ + +#include +#include +#include +#include + +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); +} diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index 5697ce73230..f4d0fea2e65 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -246,10 +246,15 @@ 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. Returns a converted errno-like, negative error code or 0. - Before this call, dst must be unset, i.e. either freshly initialized with + 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 @@ -286,6 +291,18 @@ 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 free3 the memory + held by the structure itself after freeing its contents with + sd_bus_error_free(). + + Return Value @@ -297,7 +314,8 @@ 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. + 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 @@ -305,7 +323,9 @@ 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. + 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 @@ -316,32 +336,18 @@ 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: + Return value may indicate the following problems in the invocation of the function itself: - -EINVAL - Error was already set in sd_bus_error structure when one - the error-setting functions was called. + Error was already set in the sd_bus_error structure when + one the error-setting functions was called. @@ -350,9 +356,29 @@ 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 + + + Using the negative return value to propagate an error + + + + +