From 9d3e5d11bee9ab29a479e534622bb1b23daf9fab Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 19:37:28 +0200 Subject: 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] --- man/sd-bus-errors.xml | 309 ++++++++++++++++++++++++++++++++++++ man/sd_bus_error.xml | 344 +++++++++++++++++++---------------------- man/sd_bus_error_add_map.xml | 173 +++++++++++++++++++++ man/systemd.journal-fields.xml | 1 - 4 files changed, 641 insertions(+), 186 deletions(-) create mode 100644 man/sd-bus-errors.xml create mode 100644 man/sd_bus_error_add_map.xml (limited to 'man') diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml new file mode 100644 index 0000000000..d6bbd7fbb2 --- /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.xml b/man/sd_bus_error.xml index b8cb339cec..6dc4541eb1 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -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 @@ -75,7 +79,7 @@ - int sd_bus_error_free + void sd_bus_error_free sd_bus_error *e @@ -115,6 +119,14 @@ ... + + 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 @@ - - 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 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 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(), + 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 + 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 @@ systemd1, sd-bus3, + sd-bus-errors3, + sd_bus_error_add_map3, errno3, - strerror3 + strerror_r3 diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml new file mode 100644 index 0000000000..3fca63be4a --- /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 + + + + diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml index a101006a7e..afe1200d7e 100644 --- a/man/systemd.journal-fields.xml +++ b/man/systemd.journal-fields.xml @@ -440,7 +440,6 @@ - -- cgit v1.2.3-54-g00ecf From f6f7a9848e27fbc1748aec9264e58a2aeaf736db Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 20:42:57 +0200 Subject: man: fully document sd_bus_creds subsystem [@zonque: typo fixed, reported by @ronnychevalier] --- Makefile-man.am | 10 +++ man/sd_bus_creds_get_pid.xml | 59 ++++++++++----- man/sd_bus_creds_new_from_pid.xml | 150 ++++++++++++++++++++++++++------------ 3 files changed, 154 insertions(+), 65 deletions(-) (limited to 'man') diff --git a/Makefile-man.am b/Makefile-man.am index 35874e0b84..950207bd4e 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -227,6 +227,7 @@ MANPAGES_ALIAS += \ man/reboot.8 \ man/sd_bus_creds_get_audit_login_uid.3 \ man/sd_bus_creds_get_audit_session_id.3 \ + man/sd_bus_creds_get_augmented_mask.3 \ man/sd_bus_creds_get_cgroup.3 \ man/sd_bus_creds_get_cmdline.3 \ man/sd_bus_creds_get_comm.3 \ @@ -252,6 +253,7 @@ MANPAGES_ALIAS += \ man/sd_bus_creds_get_uid.3 \ man/sd_bus_creds_get_unique_name.3 \ man/sd_bus_creds_get_unit.3 \ + man/sd_bus_creds_get_user_slice.3 \ man/sd_bus_creds_get_user_unit.3 \ man/sd_bus_creds_get_well_known_names.3 \ man/sd_bus_creds_has_bounding_cap.3 \ @@ -511,6 +513,7 @@ man/poweroff.8: man/halt.8 man/reboot.8: man/halt.8 man/sd_bus_creds_get_audit_login_uid.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_audit_session_id.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_augmented_mask.3: man/sd_bus_creds_new_from_pid.3 man/sd_bus_creds_get_cgroup.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_cmdline.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_comm.3: man/sd_bus_creds_get_pid.3 @@ -536,6 +539,7 @@ man/sd_bus_creds_get_tty.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_uid.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_unique_name.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_unit.3: man/sd_bus_creds_get_pid.3 +man/sd_bus_creds_get_user_slice.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_user_unit.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_get_well_known_names.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_has_bounding_cap.3: man/sd_bus_creds_get_pid.3 @@ -925,6 +929,9 @@ man/sd_bus_creds_get_audit_login_uid.html: man/sd_bus_creds_get_pid.html man/sd_bus_creds_get_audit_session_id.html: man/sd_bus_creds_get_pid.html $(html-alias) +man/sd_bus_creds_get_augmented_mask.html: man/sd_bus_creds_new_from_pid.html + $(html-alias) + man/sd_bus_creds_get_cgroup.html: man/sd_bus_creds_get_pid.html $(html-alias) @@ -1000,6 +1007,9 @@ man/sd_bus_creds_get_unique_name.html: man/sd_bus_creds_get_pid.html man/sd_bus_creds_get_unit.html: man/sd_bus_creds_get_pid.html $(html-alias) +man/sd_bus_creds_get_user_slice.html: man/sd_bus_creds_get_pid.html + $(html-alias) + man/sd_bus_creds_get_user_unit.html: man/sd_bus_creds_get_pid.html $(html-alias) diff --git a/man/sd_bus_creds_get_pid.xml b/man/sd_bus_creds_get_pid.xml index 13f885cd5d..4162fab065 100644 --- a/man/sd_bus_creds_get_pid.xml +++ b/man/sd_bus_creds_get_pid.xml @@ -61,8 +61,9 @@ sd_bus_creds_get_cmdline sd_bus_creds_get_cgroup sd_bus_creds_get_unit - sd_bus_creds_get_user_unit sd_bus_creds_get_slice + sd_bus_creds_get_user_unit + sd_bus_creds_get_user_slice sd_bus_creds_get_session sd_bus_creds_get_owner_uid sd_bus_creds_has_effective_cap @@ -192,6 +193,12 @@ const char **unit + + int sd_bus_creds_get_slice + sd_bus_creds *c + const char **slice + + int sd_bus_creds_get_user_unit sd_bus_creds *c @@ -199,7 +206,7 @@ - int sd_bus_creds_get_slice + int sd_bus_creds_get_user_slice sd_bus_creds *c const char **slice @@ -288,9 +295,9 @@ Description - These functions return information from an - sd_bus_creds credential object. Credential - objects may be created with + These functions return credential information from an + sd_bus_creds object. Credential objects may + be created with sd_bus_creds_new_from_pid3, in which case they describe the credentials of the process identified by the specified PID, with @@ -301,7 +308,13 @@ in which case they describe the credentials of the creator of a bus, or with sd_bus_message_get_creds3, - in which case they describe the credentials of the sender of the message. + in which case they describe the credentials of the sender of the + message. + + Not all credential fields are part of every + sd_bus_creds object. Use + sd_bus_creds_get_mask3 + to determine the mask of fields available. sd_bus_creds_get_pid() will retrieve the PID (process identifier). Similar, @@ -374,19 +387,22 @@ sd_bus_creds_get_slice() will retrieve the systemd slice (a unit in the system instance of systemd) that the process is part of. See - systemd.slice5. + systemd.slice5. Similar, + sd_bus_creds_get_user_slice() retrieves the + systemd slice of the process, in the user instance of systemd. sd_bus_creds_get_session() will - retrieve the logind session that the process is part of. See + retrieve the identifier of the login session that the process is + part of. See systemd-logind.service8. For processes that are not part of a session returns -ENXIO. sd_bus_creds_get_owner_uid() will retrieve the numeric UID (user identifier) of the user who owns - the session that the process is part of. See - systemd.slice5 + the login session that the process is part of. See + systemd-logind.service8. For processes that are not part of a session returns -ENXIO. @@ -395,7 +411,7 @@ capability was set in the effective capabilities mask. A positive return value means that is was set, zero means that it was not set, and a negative return - value signifies an error. See + value indicates an error. See capabilities7 and Capabilities= and CapabilityBoundingSet= settings in @@ -427,8 +443,8 @@ processes that are not part of an audit session. sd_bus_creds_get_tty() will retrieve - the controlling TTY. Returns -ENXIO for processes that have no - controlling TTY. + the controlling TTY, without the prefixing "/dev/". Returns -ENXIO + for processes that have no controlling TTY. sd_bus_creds_get_unique_name() will retrieve the D-Bus unique name. See Given field is not specified for the described process or peer. This will be returned by sd_bus_get_unit(), - sd_bus_get_user_unit(), sd_bus_get_slice(), + sd_bus_get_user_unit(), + sd_bus_get_user_slice(), sd_bus_get_session(), and sd_bus_get_owner_uid() if the process is not part of a systemd system unit, systemd user unit, systemd @@ -526,10 +543,11 @@ Notes - sd_bus_open_user() and other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 + sd_bus_creds_get_pid() and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 file. @@ -539,8 +557,9 @@ systemd1, sd-bus3, - fork2, - execve2, + sd_bus_creds_new_from_pid2, + fork2, + execve2, credentials7, free3, proc5, diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml index 8c054a5905..a78d3f5717 100644 --- a/man/sd_bus_creds_new_from_pid.xml +++ b/man/sd_bus_creds_new_from_pid.xml @@ -45,6 +45,7 @@ sd_bus_creds_new_from_pid sd_bus_creds_get_mask + sd_bus_creds_get_augmented_mask sd_bus_creds_ref sd_bus_creds_unref @@ -67,6 +68,11 @@ const sd_bus_creds *c + + uint64_t sd_bus_creds_get_augmented_mask + const sd_bus_creds *c + + sd_bus_creds *sd_bus_creds_ref sd_bus_creds *c @@ -80,17 +86,26 @@ SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, SD_BUS_CREDS_TID, SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, SD_BUS_CREDS_COMM, SD_BUS_CREDS_TID_COMM, SD_BUS_CREDS_EXE, SD_BUS_CREDS_CMDLINE, SD_BUS_CREDS_CGROUP, SD_BUS_CREDS_UNIT, - SD_BUS_CREDS_USER_UNIT, SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, SD_BUS_CREDS_SESSION, SD_BUS_CREDS_OWNER_UID, SD_BUS_CREDS_EFFECTIVE_CAPS, @@ -100,8 +115,11 @@ SD_BUS_CREDS_SELINUX_CONTEXT, SD_BUS_CREDS_AUDIT_SESSION_ID, SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, SD_BUS_CREDS_UNIQUE_NAME, SD_BUS_CREDS_WELL_KNOWN_NAMES, + SD_BUS_CREDS_DESCRIPTION, + SD_BUS_CREDS_AUGMENT, _SD_BUS_CREDS_ALL @@ -109,25 +127,39 @@ Description - sd_bus_creds_new_from_pid() creates a new - credentials object and fills it with information about the process - pid. This pointer to this object will - be stored in ret pointer. + sd_bus_creds_new_from_pid() creates a + new credentials object and fills it with information about the + process pid. The pointer to this object + will be stored in ret pointer. Note that + credential objects may also be created and retrieved via + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3 + and + sd_bus_message_get_creds3. The information that will be stored is determined by creds_mask. It may contain a subset of ORed constants SD_BUS_CREDS_PID, + SD_BUS_CREDS_PPID, SD_BUS_CREDS_TID, SD_BUS_CREDS_UID, + SD_BUS_CREDS_EUID, + SD_BUS_CREDS_SUID, + SD_BUS_CREDS_FSUID, SD_BUS_CREDS_GID, + SD_BUS_CREDS_EGID, + SD_BUS_CREDS_SGID, + SD_BUS_CREDS_FSGID, + SD_BUS_CREDS_SUPPLEMENTARY_GIDS, SD_BUS_CREDS_COMM, SD_BUS_CREDS_TID_COMM, SD_BUS_CREDS_EXE, SD_BUS_CREDS_CMDLINE, SD_BUS_CREDS_CGROUP, SD_BUS_CREDS_UNIT, - SD_BUS_CREDS_USER_UNIT, SD_BUS_CREDS_SLICE, + SD_BUS_CREDS_USER_UNIT, + SD_BUS_CREDS_USER_SLICE, SD_BUS_CREDS_SESSION, SD_BUS_CREDS_OWNER_UID, SD_BUS_CREDS_EFFECTIVE_CAPS, @@ -137,34 +169,71 @@ SD_BUS_CREDS_SELINUX_CONTEXT, SD_BUS_CREDS_AUDIT_SESSION_ID, SD_BUS_CREDS_AUDIT_LOGIN_UID, + SD_BUS_CREDS_TTY, SD_BUS_CREDS_UNIQUE_NAME, SD_BUS_CREDS_WELL_KNOWN_NAMES, - or _SD_BUS_CREDS_ALL to indicate - all known fields. + SD_BUS_CREDS_DESCRIPTION. Use the special + value _SD_BUS_CREDS_ALL to request all + supported fields. The SD_BUS_CREDS_AUGMENT + may not be ORed into the mask for invocations of + sd_bus_creds_new_from_pid(). Fields can be retrieved from the credentials object using sd_bus_creds_get_pid3 and other functions which correspond directly to the constants listed above. - A mask of fields which were actually successfully set - (acquired from /proc, etc.) can be retrieved - with sd_bus_creds_get_mask(). If the - credentials object was created with + A mask of fields which were actually successfully retrieved + can be retrieved with + sd_bus_creds_get_mask(). If the credentials + object was created with sd_bus_creds_new_from_pid(), this will be a subset of fields requested in creds_mask. - sd_bus_creds_ref creates a new + Similar to sd_bus_creds_get_mask() the + function sd_bus_creds_get_augmented_mask() + returns a bitmask of field constants. The mask indicates which + credential fields have been retrieved in a non-atomic fashion. For + credential objects created via + sd_bus_creds_new_from_pid() this mask will be + identical to the mask returned by + sd_bus_creds_get_mask(). However, for + credential objects retrieved via + sd_bus_get_name_creds() this mask will be set + for the credential fields that could not be determined atomically + at peer connection time, and which were later added by reading + augmenting credential data from + /proc. Similar, for credential objects + retrieved via sd_bus_get_owner_creds() the + mask is set for the fields that could not be determined atomically + at bus creation time, but have been augmented. Similar, for + credential objects retrieved via + sd_bus_message_get_creds() the mask is set + for the fields that could not be determined atomically at message + send time, but have been augmented. The mask returned by + sd_bus_creds_get_augmented_mask() is always a + subset of (or identical to) the mask returned by + sd_bus_creds_get_mask() for the same + object. The latter call hence returns all credential fields + available in the credential object, the former then marks the + subset of those that have been augmented. Note that augmented + fields are unsuitable for authorization decisions as they may be + retrieved at different times, thus being subject to races. Hence + augmented fields should be used exclusively for informational + purposes. + + + sd_bus_creds_ref() creates a new reference to the credentials object c. This object will not be destroyed until - sd_bus_creds_unref has been called as many + sd_bus_creds_unref() has been called as many times plus once more. Once the reference count has dropped to zero, c cannot be used anymore, so further calls to sd_bus_creds_ref(c) or sd_bus_creds_unref(c) are illegal. - sd_bus_creds_unref destroys a reference + sd_bus_creds_unref() destroys a reference to c. @@ -178,10 +247,15 @@ sd_bus_creds_get_mask() returns the mask of successfully acquired fields. - sd_bus_creds_ref always returns the + sd_bus_creds_get_augmented_mask() + returns the mask of fields that have been augmented from data in + /proc, and are thus not suitable for + authorization decisions. + + sd_bus_creds_ref() always returns the argument. - sd_bus_creds_unref always returns + sd_bus_creds_unref() always returns NULL. @@ -222,16 +296,23 @@ Memory allocation failed. + + + -EOPNOTSUPP + + One of the requested fields is unknown to the local system. + Notes - sd_bus_creds_new_from_pid() is - available as a shared library, which can be compiled and linked to - with the - libsystemd pkg-config1 + sd_bus_creds_new_from_pid() and the + other calls described here are available as a shared library, + which can be compiled and linked to with the + libsystemd pkg-config1 file. @@ -241,31 +322,10 @@ systemd1, sd-bus3, - sd_bus_creds_ref3, - sd_bus_creds_unref3, sd_bus_creds_get_pid3, - sd_bus_creds_get_tid3, - sd_bus_creds_get_uid3, - sd_bus_creds_get_gid3, - sd_bus_creds_get_comm3, - sd_bus_creds_get_tid_comm3, - sd_bus_creds_get_exe3, - sd_bus_creds_get_cmdline3, - sd_bus_creds_get_cgroup3, - sd_bus_creds_get_unit3, - sd_bus_creds_get_user_unit3, - sd_bus_creds_get_slice3, - sd_bus_creds_get_session3, - sd_bus_creds_get_owner_uid3, - sd_bus_creds_has_effective_cap3, - sd_bus_creds_has_permitted_cap3, - sd_bus_creds_has_inheritable_cap3, - sd_bus_creds_has_bounding_cap3, - sd_bus_creds_get_selinux_context3, - sd_bus_creds_get_audit_session_id3, - sd_bus_creds_get_audit_login_uid3, - sd_bus_creds_get_unique_name3, - sd_bus_creds_get_well_known_names3 + sd_bus_get_name_creds3, + sd_bus_get_owner_creds3, + sd_bus_message_get_creds3 -- cgit v1.2.3-54-g00ecf From 02855643499f63045159fec72f23a339ef5a64d6 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 20:44:15 +0200 Subject: man: fix sd_bus_negotiate_timestamps documentation link-up --- Makefile-man.am | 6 +++--- man/sd_bus_negotiate_fds.xml | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'man') diff --git a/Makefile-man.am b/Makefile-man.am index 950207bd4e..08d22b344c 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -285,7 +285,7 @@ MANPAGES_ALIAS += \ man/sd_bus_message_get_reply_cookie.3 \ man/sd_bus_message_get_seqnum.3 \ man/sd_bus_negotiate_creds.3 \ - man/sd_bus_negotiate_timestamps.3 \ + man/sd_bus_negotiate_timestamp.3 \ man/sd_bus_open.3 \ man/sd_bus_open_system.3 \ man/sd_bus_open_system_machine.3 \ @@ -571,7 +571,7 @@ man/sd_bus_message_get_realtime_usec.3: man/sd_bus_message_get_monotonic_usec.3 man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3 man/sd_bus_message_get_seqnum.3: man/sd_bus_message_get_monotonic_usec.3 man/sd_bus_negotiate_creds.3: man/sd_bus_negotiate_fds.3 -man/sd_bus_negotiate_timestamps.3: man/sd_bus_negotiate_fds.3 +man/sd_bus_negotiate_timestamp.3: man/sd_bus_negotiate_fds.3 man/sd_bus_open.3: man/sd_bus_default.3 man/sd_bus_open_system.3: man/sd_bus_default.3 man/sd_bus_open_system_machine.3: man/sd_bus_default.3 @@ -1103,7 +1103,7 @@ man/sd_bus_message_get_seqnum.html: man/sd_bus_message_get_monotonic_usec.html man/sd_bus_negotiate_creds.html: man/sd_bus_negotiate_fds.html $(html-alias) -man/sd_bus_negotiate_timestamps.html: man/sd_bus_negotiate_fds.html +man/sd_bus_negotiate_timestamp.html: man/sd_bus_negotiate_fds.html $(html-alias) man/sd_bus_open.html: man/sd_bus_default.html diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index 04042f2136..1be44e2785 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -44,7 +44,7 @@ sd_bus_negotiate_fds - sd_bus_negotiate_timestamps + sd_bus_negotiate_timestamp sd_bus_negotiate_creds Control feature negotiation on bus connections -- cgit v1.2.3-54-g00ecf From dddbc69577820e6ecce17d3ac836ad865fcbcde2 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 21:22:56 +0200 Subject: man: document user slice sd-login calls we added a while back --- Makefile-man.am | 10 ++++++ man/sd_pid_get_session.xml | 83 +++++++++++++++++++++++++++++----------------- 2 files changed, 63 insertions(+), 30 deletions(-) (limited to 'man') diff --git a/Makefile-man.am b/Makefile-man.am index 08d22b344c..218a299e91 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -1937,11 +1937,13 @@ MANPAGES_ALIAS += \ man/sd_peer_get_session.3 \ man/sd_peer_get_slice.3 \ man/sd_peer_get_unit.3 \ + man/sd_peer_get_user_slice.3 \ man/sd_peer_get_user_unit.3 \ man/sd_pid_get_machine_name.3 \ man/sd_pid_get_owner_uid.3 \ man/sd_pid_get_slice.3 \ man/sd_pid_get_unit.3 \ + man/sd_pid_get_user_slice.3 \ man/sd_pid_get_user_unit.3 \ man/sd_seat_can_graphical.3 \ man/sd_seat_can_multi_session.3 \ @@ -1979,11 +1981,13 @@ man/sd_peer_get_owner_uid.3: man/sd_pid_get_session.3 man/sd_peer_get_session.3: man/sd_pid_get_session.3 man/sd_peer_get_slice.3: man/sd_pid_get_session.3 man/sd_peer_get_unit.3: man/sd_pid_get_session.3 +man/sd_peer_get_user_slice.3: man/sd_pid_get_session.3 man/sd_peer_get_user_unit.3: man/sd_pid_get_session.3 man/sd_pid_get_machine_name.3: man/sd_pid_get_session.3 man/sd_pid_get_owner_uid.3: man/sd_pid_get_session.3 man/sd_pid_get_slice.3: man/sd_pid_get_session.3 man/sd_pid_get_unit.3: man/sd_pid_get_session.3 +man/sd_pid_get_user_slice.3: man/sd_pid_get_session.3 man/sd_pid_get_user_unit.3: man/sd_pid_get_session.3 man/sd_seat_can_graphical.3: man/sd_seat_get_active.3 man/sd_seat_can_multi_session.3: man/sd_seat_get_active.3 @@ -2049,6 +2053,9 @@ man/sd_peer_get_slice.html: man/sd_pid_get_session.html man/sd_peer_get_unit.html: man/sd_pid_get_session.html $(html-alias) +man/sd_peer_get_user_slice.html: man/sd_pid_get_session.html + $(html-alias) + man/sd_peer_get_user_unit.html: man/sd_pid_get_session.html $(html-alias) @@ -2064,6 +2071,9 @@ man/sd_pid_get_slice.html: man/sd_pid_get_session.html man/sd_pid_get_unit.html: man/sd_pid_get_session.html $(html-alias) +man/sd_pid_get_user_slice.html: man/sd_pid_get_session.html + $(html-alias) + man/sd_pid_get_user_unit.html: man/sd_pid_get_session.html $(html-alias) diff --git a/man/sd_pid_get_session.xml b/man/sd_pid_get_session.xml index b46d47101b..9c6706caf8 100644 --- a/man/sd_pid_get_session.xml +++ b/man/sd_pid_get_session.xml @@ -49,15 +49,17 @@ sd_pid_get_owner_uid sd_pid_get_machine_name sd_pid_get_slice + sd_pid_get_user_slice sd_peer_get_session sd_peer_get_unit sd_peer_get_user_unit sd_peer_get_owner_uid sd_peer_get_machine_name sd_peer_get_slice - Determine session, service, owner of a - session, container/VM or slice of a specific - PID or socket peer + sd_peer_get_user_slice + Determine session, unit, owner of a session, + container/VM or slice of a specific PID or socket + peer @@ -100,6 +102,12 @@ char **slice + + int sd_pid_get_user_slice + pid_t pid + char **slice + + int sd_peer_get_session int fd @@ -135,6 +143,12 @@ int fd char **slice + + + int sd_peer_get_user_slice + int fd + char **slice + @@ -155,30 +169,29 @@ call after use. sd_pid_get_unit() may be used to - determine the systemd system unit (i.e. system service) identifier - of a process identified by the specified PID. The unit name is a - short string, suitable for usage in file system paths. Note that - not all processes are part of a system unit/service (e.g. user - processes, or kernel threads). For processes not being part of a - systemd system unit this function will fail with -ENXIO (More - specifically: this call will not work for processes that are part - of user units, use sd_pid_get_user_unit() for - that.) The returned string needs to be freed with the libc - free3 call after use. sd_pid_get_user_unit() may be used to - determine the systemd user unit (i.e. user service) identifier of - a process identified by the specified PID. This is similar to - sd_pid_get_unit() but applies to user units - instead of system units. + determine the systemd user unit (i.e. user service or scope unit) + identifier of a process identified by the specified PID. This is + similar to sd_pid_get_unit() but applies to + user units instead of system units. sd_pid_get_owner_uid() may be used to - determine the Unix user identifier of the owner of the session of - a process identified the specified PID. Note that this function - will succeed for user processes which are shared between multiple - login sessions of the same user, where + determine the Unix UID (user identifier) of the owner of the + session of a process identified the specified PID. Note that this + function will succeed for user processes which are shared between + multiple login sessions of the same user, where sd_pid_get_session() will fail. For processes not being part of a login session and not being a shared process of a user this function will fail with -ENXIO. @@ -200,6 +213,10 @@ free3 call after use. + Similar, sd_pid_get_user_slice() + returns the user slice (as managed by the user's systemd instance) + of a process. + If the pid parameter of any of these functions is passed as 0, the operation is executed for the calling process. @@ -208,10 +225,14 @@ sd_peer_get_unit(), sd_peer_get_user_unit(), sd_peer_get_owner_uid(), - sd_peer_get_machine_name() and - sd_peer_get_slice() calls operate similar to - their PID counterparts, but operate on a connected AF_UNIX socket - and retrieve information about the connected peer process. + sd_peer_get_machine_name(), + sd_peer_get_slice() and + sd_peer_get_user_slice() calls operate + similar to their PID counterparts, but operate on a connected + AF_UNIX socket and retrieve information about the connected peer + process. Note that these fields are retrieved via + /proc, and hence are not suitable for + authorization purposes, as they are subject to races. @@ -262,15 +283,17 @@ sd_pid_get_owner_uid(), sd_pid_get_machine_name(), sd_pid_get_slice(), + sd_pid_get_user_slice(), sd_peer_get_session(), sd_peer_get_unit(), sd_peer_get_user_unit(), sd_peer_get_owner_uid(), - sd_peer_get_machine_name() and - sd_peer_get_slice() interfaces are - available as a shared library, which can be compiled - and linked to with the - libsystemd pkg-config1 + sd_peer_get_machine_name(), + sd_peer_get_slice() and + sd_peer_get_user_slice() interfaces are + available as a shared library, which can be compiled and linked to + with the libsystemd pkg-config1 file. Note that the login session identifier as -- cgit v1.2.3-54-g00ecf From 2a2e6a0845dedf57233d2c8a89201a563e0c3c6d Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 21:41:15 +0200 Subject: man: minor updates to the sd_bus_request_name() documentation --- man/sd_bus_request_name.xml | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) (limited to 'man') diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index 9b0a93d888..f07ae09555 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -45,7 +45,7 @@ sd_bus_request_name sd_bus_release_name - Request or release a well-known name on a bus + Request or release a well-known service name on a bus @@ -71,9 +71,9 @@ Description sd_bus_request_name() requests a - well-known name on a bus. It takes a bus connection, a valid bus - name and a flags parameter. The flags parameter is a combination - of the following flags: + well-known service name on a bus. It takes a bus connection, a + valid bus name and a flags parameter. The flags parameter is a + combination of the following flags: @@ -166,8 +166,11 @@ -EINVAL - A specified parameter is - invalid. + A specified parameter is invalid. This is also + generated when the requested name is a special service name + reserved by the D-Bus specification, or when the operation is + requested on a connection that does not refer to a + bus. -- cgit v1.2.3-54-g00ecf