X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_error.xml;h=6f93a74cac296f27cfdd9d52f612e8869a63a101;hb=bb81dc92d38d5b1336ad842ef5f43f178aafcbb5;hp=dc5a93d61795ea767f8034f1a1fe17fc0b1bad63;hpb=5de0ccffcc4a5a946102a14e0b0e681d964e3225;p=elogind.git
diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml
index dc5a93d61..6f93a74ca 100644
--- a/man/sd_bus_error.xml
+++ b/man/sd_bus_error.xml
@@ -21,7 +21,7 @@
along with systemd; If not, see .
-->
-
+
sd_bus_error
@@ -44,11 +44,15 @@
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_is_set
@@ -64,7 +68,7 @@
typedef struct {
const char *name;
const char *message;
- ...
+ â¦
} sd_bus_error;
@@ -75,7 +79,7 @@
- int sd_bus_error_free
+ void sd_bus_error_free
sd_bus_error *e
@@ -91,7 +95,7 @@
sd_bus_error *e
const char *name
const char *format
- ...
+ â¦
@@ -112,7 +116,15 @@
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
@@ -138,234 +150,194 @@
-
- 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 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
- errno3).
- 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
+ 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_errorstructure 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 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
- printf3
- 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.
- strerror3
+ 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 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
- printf3
- format and corresponding arguments.
- name will be generated from
+ 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_get_errno will convert
- e->name to an errno-like value using the
- same rules as sd_bus_error_set. If
+ 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
+ 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_set_error_const(), they will be shared.
+ Otherwise, they will be copied. Returns a converted
+ errno-like, negative error code.
- sd_bus_error_is_set will return
- true if e is
+ 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 true
- if e is non-NULL and
- an error with the same name has been set,
+ 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_free will destroy resources
- held by e. The parameter itself will not
- be deallocated, and must be
- free3d
- by the caller if necessary.
+ 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
- Functions sd_bus_error_set,
- sd_bus_error_setf,
- sd_bus_error_set_const, when successful,
+ 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. 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
+ 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 returns 0 or a
- positive integer on success, and one of the negative error values
- listed below otherwise.
+ sd_bus_error_copy() returns 0 or a
+ positive integer on success, and a negative error value converted
+ from the error name otherwise.
- sd_bus_error_is_set returns
- true when e and
- e->name are non-NULL,
- false 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 returns
- true when e is
- non-NULL and e->name
- is equal to name,
- false otherwise.
+ sd_bus_error_has_name() returns a
+ non-zero value when e is
+ non-NULL and the
+ name field is equal to
+ name, zero otherwise.
Reference ownership
sd_bus_error is not reference
counted. Users should destroy resources held by it by calling
- sd_bus_error_free.
+ 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().
@@ -397,7 +369,7 @@
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-config1
+ libelogind pkg-config1
file.
@@ -407,8 +379,10 @@
systemd1,
sd-bus3,
+ sd-bus-errors3,
+ sd_bus_error_add_map3,
errno3,
- strerror3
+ strerror_r3