From: Lennart Poettering Date: Tue, 23 Jun 2015 17:37:28 +0000 (+0200) Subject: man: fully document sd-bus' error APIs X-Git-Tag: v226.4~1^2~249 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=62804d0390850723e9be6cdd580415fb4f90050d;p=elogind.git man: fully document sd-bus' error APIs [@zonque: Some minor nits fixed as pointed out by @ronnychevalier, dropped class='sd-bus-errors' to fix python logic] --- diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml new file mode 100644 index 000000000..d6bbd7fbb --- /dev/null +++ b/man/sd-bus-errors.xml @@ -0,0 +1,309 @@ + + + + + + + + + sd-bus-errors + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd-bus-errors + 3 + + + + sd-bus-errors + 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 + SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED + + Standard D-Bus error names + + + + + #include <systemd/sd-bus.h> + +#define SD_BUS_ERROR_FAILED "org.freedesktop.DBus.Error.Failed" +#define SD_BUS_ERROR_NO_MEMORY "org.freedesktop.DBus.Error.NoMemory" +#define SD_BUS_ERROR_SERVICE_UNKNOWN "org.freedesktop.DBus.Error.ServiceUnknown" +#define SD_BUS_ERROR_NAME_HAS_NO_OWNER "org.freedesktop.DBus.Error.NameHasNoOwner" +#define SD_BUS_ERROR_NO_REPLY "org.freedesktop.DBus.Error.NoReply" +#define SD_BUS_ERROR_IO_ERROR "org.freedesktop.DBus.Error.IOError" +#define SD_BUS_ERROR_BAD_ADDRESS "org.freedesktop.DBus.Error.BadAddress" +#define SD_BUS_ERROR_NOT_SUPPORTED "org.freedesktop.DBus.Error.NotSupported" +#define SD_BUS_ERROR_LIMITS_EXCEEDED "org.freedesktop.DBus.Error.LimitsExceeded" +#define SD_BUS_ERROR_ACCESS_DENIED "org.freedesktop.DBus.Error.AccessDenied" +#define SD_BUS_ERROR_AUTH_FAILED "org.freedesktop.DBus.Error.AuthFailed" +#define SD_BUS_ERROR_NO_SERVER "org.freedesktop.DBus.Error.NoServer" +#define SD_BUS_ERROR_TIMEOUT "org.freedesktop.DBus.Error.Timeout" +#define SD_BUS_ERROR_NO_NETWORK "org.freedesktop.DBus.Error.NoNetwork" +#define SD_BUS_ERROR_ADDRESS_IN_USE "org.freedesktop.DBus.Error.AddressInUse" +#define SD_BUS_ERROR_DISCONNECTED "org.freedesktop.DBus.Error.Disconnected" +#define SD_BUS_ERROR_INVALID_ARGS "org.freedesktop.DBus.Error.InvalidArgs" +#define SD_BUS_ERROR_FILE_NOT_FOUND "org.freedesktop.DBus.Error.FileNotFound" +#define SD_BUS_ERROR_FILE_EXISTS "org.freedesktop.DBus.Error.FileExists" +#define SD_BUS_ERROR_UNKNOWN_METHOD "org.freedesktop.DBus.Error.UnknownMethod" +#define SD_BUS_ERROR_UNKNOWN_OBJECT "org.freedesktop.DBus.Error.UnknownObject" +#define SD_BUS_ERROR_UNKNOWN_INTERFACE "org.freedesktop.DBus.Error.UnknownInterface" +#define SD_BUS_ERROR_UNKNOWN_PROPERTY "org.freedesktop.DBus.Error.UnknownProperty" +#define SD_BUS_ERROR_PROPERTY_READ_ONLY "org.freedesktop.DBus.Error.PropertyReadOnly" +#define SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN "org.freedesktop.DBus.Error.UnixProcessIdUnknown" +#define SD_BUS_ERROR_INVALID_SIGNATURE "org.freedesktop.DBus.Error.InvalidSignature" +#define SD_BUS_ERROR_INCONSISTENT_MESSAGE "org.freedesktop.DBus.Error.InconsistentMessage" +#define SD_BUS_ERROR_MATCH_RULE_NOT_FOUND "org.freedesktop.DBus.Error.MatchRuleNotFound" +#define SD_BUS_ERROR_MATCH_RULE_INVALID "org.freedesktop.DBus.Error.MatchRuleInvalid" +#define SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED \ + "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired" + + + + + + Description + + In addition to the error names user programs define, D-Bus + knows a number of generic, standardized error names, that are + listed below. + + In addition to this list, in sd-bus the special error + namespace System.Error. is used to map + arbitrary Linux system errors (as defined by errno3) + to D-Bus errors and back. For example, the error + EUCLEAN is mapped to + System.Error.EUCLEAN and back. + + + + + SD_BUS_ERROR_FAILED + A generic error indication. See the error + message for further details. This error name should be + avoided, in favour of a more expressive error + name. + + + + SD_BUS_ERROR_NO_MEMORY + A memory allocation failed, and the requested + operation could not be completed. + + + + SD_BUS_ERROR_SERVICE_UNKNOWN + The contacted bus service is unknown and + cannot be activated. + + + + SD_BUS_ERROR_NAME_HAS_NO_OWNER + The specified bus service name currently has + no owner. + + + SD_BUS_ERROR_NO_REPLY + A message did not receive a reply. This error + is usually generated after a timeout. + + + SD_BUS_ERROR_IO_ERROR + Generic input/output error, for example when + accessing a socket or other IO context. + + + SD_BUS_ERROR_BAD_ADDRESS + The specified D-Bus bus address string is + malformed. + + + SD_BUS_ERROR_NOT_SUPPORTED + The requested operation is not supported on + the local system. + + + SD_BUS_ERROR_LIMITS_EXCEEDED + Some limited resource has been + exhausted. + + + SD_BUS_ERROR_ACCESS_DENIED + Access to a resource has bee denied, due to security restrictions. + + + SD_BUS_ERROR_AUTH_FAILED + Authentication did not complete successfully. + + + SD_BUS_ERROR_NO_SERVER + Unable to connect to the specified server. + + + SD_BUS_ERROR_TIMEOUT + An operation timed out. Note that method calls + which timeout generate a + SD_BUS_ERROR_NO_REPLY. + + + SD_BUS_ERROR_NO_NETWORK + No network available to execute requested network operation on. + + + SD_BUS_ERROR_ADDRESS_IN_USE + The specified network address is already being listened on. + + + SD_BUS_ERROR_DISCONNECTED + The connection has been terminated. + + + SD_BUS_ERROR_INVALID_ARGS + One or more invalid arguments have been passed. + + + SD_BUS_ERROR_FILE_NOT_FOUND + The requested file could not be found. + + + SD_BUS_ERROR_FILE_EXISTS + The requested file exists already. + + + SD_BUS_ERROR_UNKNOWN_METHOD + The requested method does not exist in the selected interface. + + + SD_BUS_ERROR_UNKNOWN_OBJECT + The requested object does not exist in the selected service. + + + SD_BUS_ERROR_UNKNOWN_INTERFACE + The requested interface does not exist on the selected object. + + + SD_BUS_ERROR_UNKNOWN_PROPERTY + The requested property does not exist in the selected interface. + + + SD_BUS_ERROR_PROPERTY_READ_ONLY + A write operation was requested on a read-only property. + + + SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN + The requested PID is not known. + + + SD_BUS_ERROR_INVALID_SIGNATURE + The specified message signature is not + valid. + + + + SD_BUS_ERROR_INCONSISTENT_MESSAGE + The passed message does not validate + correctly. + + + SD_BUS_ERROR_MATCH_RULE_NOT_FOUND + The specified match rule does not exist. + + + SD_BUS_ERROR_MATCH_RULE_INVALID + The specified match rule is invalid. + + + SD_BUS_ERROR_INTERACTIVE_AUTHORIZATION_REQUIRED + Access to the requested operation is not + permitted, however, it might be available after interactive + authentication. This is usually returned by method calls + supporting a framework for additional interactive + authorization, when interactive authorization was not enabled + with the + sd_bus_message_set_allow_interactive_authorization3 + for the method call message. + + + + + + Notes + + The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_error3, + sd_bus_message_set_allow_interactive_authorization3, + errno3, + strerror3 + + + + diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml new file mode 100644 index 000000000..3fca63be4 --- /dev/null +++ b/man/sd_bus_error_add_map.xml @@ -0,0 +1,173 @@ + + + + + + + + + sd_bus_error_add_map + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_error_add_map + 3 + + + + sd_bus_error_add_map + sd_bus_error_map + SD_BUS_ERROR_MAP + SD_BUS_ERROR_END + + Additional sd-dbus error mappings + + + + + #include <systemd/sd-bus.h> + + typedef struct { + const char *name; + int code; + ... +} sd_bus_error_map; + + + + + SD_BUS_ERROR_MAP(name, code) + + + SD_BUS_ERROR_MAP_END + + + + int sd_bus_error_add_map + const sd_bus_map *map + + + + + + Description + + The sd_bus_error_add_map() call may be + used to register additional mappings for converting D-Bus errors + to Linux errno-style errors. The mappings + defined with this call are consulted by calls such as + sd_bus_error_set3 + or + sd_bus_error_get_errno3. By + default a number of generic, standardized mappings are known, as + documented in + sd-bus-errors3. Use + this call to add further, application-specific mappings. + + The function takes a pointer to an array of + sd_bus_error_map structures. A reference + to the specified array is added to the lookup tables for error + mappings. Note that the structure is not copied, it is hence + essential that the array stays available and constant during the + entire remaining runtime of the process. + + The mapping array should be put together with a series of + SD_BUS_ERROR_MAP() macro invocations, that + take a literal name string and a (positive) + errno-style error number. The last entry of the + array should be an invocation of the + SD_BUS_ERROR_MAP_END macro. The array should not be + put together without use of these two macros. + + Note that the call is idempotent: it is safe to invoke it + multiple times with the parameter, which will only add the passed + mapping array once. + + Note that the memory allocated by this call is not intended + to be freed during the lifetime of the process. It should not be + freed explicitly. + + + + Return Value + + sd_bus_error_add_map() returns a + positive value when the new array was added to the lookup + tables. It returns zero when the same array was already added + before. On error, a negative errno-style error + code is returned. See below for known error codes. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified mapping array is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_error3, + sd-bus-errors3, + errno3, + strerror_r3 + + + +