From: Zbigniew Jędrzejewski-Szmek Date: Wed, 8 Jan 2014 02:46:36 +0000 (-0500) Subject: man: document sd-bus error functions X-Git-Tag: v209~509 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=71365a7754db5ff8e07941501063b1da2a4b4bd5 man: document sd-bus error functions --- diff --git a/Makefile-man.am b/Makefile-man.am index 75cccc0d6..52e62f144 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -22,6 +22,7 @@ MANPAGES += \ man/sd_booted.3 \ man/sd_bus_creds_get_pid.3 \ man/sd_bus_creds_new_from_pid.3 \ + man/sd_bus_error.3 \ man/sd_bus_message_get_cookie.3 \ man/sd_bus_new.3 \ man/sd_bus_open_user.3 \ @@ -167,6 +168,15 @@ MANPAGES_ALIAS += \ man/sd_bus_creds_unref.3 \ man/sd_bus_default_system.3 \ man/sd_bus_default_user.3 \ + man/sd_bus_error_copy.3 \ + man/sd_bus_error_free.3 \ + man/sd_bus_error_get_errno.3 \ + man/sd_bus_error_has_name.3 \ + man/sd_bus_error_is_set.3 \ + man/sd_bus_error_set.3 \ + man/sd_bus_error_set_const.3 \ + man/sd_bus_error_set_errno.3 \ + man/sd_bus_error_set_errnof.3 \ man/sd_bus_message_get_reply_cookie.3 \ man/sd_bus_open_system.3 \ man/sd_bus_open_system_container.3 \ @@ -304,6 +314,15 @@ man/sd_bus_creds_ref.3: man/sd_bus_creds_new_from_pid.3 man/sd_bus_creds_unref.3: man/sd_bus_creds_new_from_pid.3 man/sd_bus_default_system.3: man/sd_bus_open_user.3 man/sd_bus_default_user.3: man/sd_bus_open_user.3 +man/sd_bus_error_copy.3: man/sd_bus_error.3 +man/sd_bus_error_free.3: man/sd_bus_error.3 +man/sd_bus_error_get_errno.3: man/sd_bus_error.3 +man/sd_bus_error_has_name.3: man/sd_bus_error.3 +man/sd_bus_error_is_set.3: man/sd_bus_error.3 +man/sd_bus_error_set.3: man/sd_bus_error.3 +man/sd_bus_error_set_const.3: man/sd_bus_error.3 +man/sd_bus_error_set_errno.3: man/sd_bus_error.3 +man/sd_bus_error_set_errnof.3: man/sd_bus_error.3 man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3 man/sd_bus_open_system.3: man/sd_bus_open_user.3 man/sd_bus_open_system_container.3: man/sd_bus_open_user.3 @@ -553,6 +572,33 @@ man/sd_bus_default_system.html: man/sd_bus_open_user.html man/sd_bus_default_user.html: man/sd_bus_open_user.html $(html-alias) +man/sd_bus_error_copy.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_free.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_get_errno.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_has_name.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_is_set.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_const.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_errno.html: man/sd_bus_error.html + $(html-alias) + +man/sd_bus_error_set_errnof.html: man/sd_bus_error.html + $(html-alias) + man/sd_bus_message_get_reply_cookie.html: man/sd_bus_message_get_cookie.html $(html-alias) @@ -1283,6 +1329,7 @@ EXTRA_DIST += \ man/sd_booted.xml \ man/sd_bus_creds_get_pid.xml \ man/sd_bus_creds_new_from_pid.xml \ + man/sd_bus_error.xml \ man/sd_bus_message_get_cookie.xml \ man/sd_bus_new.xml \ man/sd_bus_open_user.xml \ diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml new file mode 100644 index 000000000..38bc30311 --- /dev/null +++ b/man/sd_bus_error.xml @@ -0,0 +1,414 @@ + + + + + + + + + sd_bus_error + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_error + 3 + + + + sd_bus_error + sd_bus_error_free + sd_bus_error_set + sd_bus_error_set_const + sd_bus_error_set_errno + sd_bus_error_set_errnof + sd_bus_error_get_errno + sd_bus_error_copy + sd_bus_error_is_set + sd_bus_error_has_name + + libsystemd-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 + + + + int 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_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_is_set + const sd_bus_error *e + + + + int sd_bus_error_has_name + const sd_bus_error *e + const char *name + + + + + 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 + + sd_bus_error structure carries + information for a libsystemd-bus error. + Functions described below can be used to set and query fields in + this structure. Field name 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 + name is NULL, it is is + assumed that no error occured, 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 will be filled-in in the + sd_bus_error structure + e points at. 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 + 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 + format and the arguments. + + sd_bus_error_get_errno is will convert + e->name to an errno-like value + using the same rules as sd_bus_error_set. + + + 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. + Otherwie they wil be copied. + + sd_bus_error_is_set will return + true 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, + 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. + + + + Return Value + + Functions sd_bus_error_set, + sd_bus_error_setf, + 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 + 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_is_set returns + true when e and + e->name are non-NULL, + false otherwise. + + sd_bus_error_has_name returns + true when e is + non-NULL and e->name + is equal to name, + false otherwise. + + + + Reference ownership + sd_bus_error is not reference + counted. Users should destroy resources held by it by calling + 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. + + + + + + Notes + + 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-bus pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + errno3, + strerror3 + + + +