X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsd_bus_error.xml;h=c2d7ee389bd001af90fccb38ea1e53cf0af5bf96;hb=4c80d201ace0377312c27143afab04e9c9f1ee64;hp=aba80832d29b58e000f64456e0f3954fe016ed7e;hpb=8474b70c3a3842cdf3d51f331dd117ab6421f6d0;p=thirdparty%2Fsystemd.git diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index aba80832d29..c2d7ee389bd 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -1,27 +1,27 @@ - + - + sd_bus_error @@ -44,11 +44,15 @@ along with systemd; If not, see . 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 @@ -75,7 +79,7 @@ along with systemd; If not, see . - int sd_bus_error_free + void sd_bus_error_free sd_bus_error *e @@ -115,6 +119,14 @@ along with systemd; If not, see . ... + + 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 @@ -138,234 +150,194 @@ along with systemd; If not, see . - - 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(). @@ -407,8 +379,10 @@ along with systemd; If not, see . systemd1, sd-bus3, + sd-bus-errors3, + sd_bus_error_add_map3, errno3, - strerror3 + strerror_r3