From d4169bf8b06502759d7d41d256f41d6b67ac4788 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 20 Apr 2020 20:59:27 +0200 Subject: [PATCH 1/4] sd-bus: Rewrap sd_bus_get_fd docs --- man/sd_bus_get_fd.xml | 106 +++++++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 48 deletions(-) diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml index 213d139019..eb488b1e6f 100644 --- a/man/sd_bus_get_fd.xml +++ b/man/sd_bus_get_fd.xml @@ -26,7 +26,8 @@ sd_bus_get_events sd_bus_get_timeout - Get the file descriptor, I/O events and time-out to wait for from a message bus object + Get the file descriptor, I/O events and time-out to wait for from a message bus + object @@ -61,65 +62,74 @@ Description - sd_bus_get_fd() returns the file descriptor used to communicate from a message bus - object. This descriptor can be used with poll3 or a similar - function to wait for I/O events on the specified bus connection object. If the bus object was configured with the - sd_bus_set_fd() function, then the input_fd file descriptor used in - that call is returned. + sd_bus_get_fd() returns the file descriptor used to communicate from + a message bus object. This descriptor can be used with + poll3 + or a similar function to wait for I/O events on the specified bus connection object. If the bus + object was configured with the sd_bus_set_fd() function, then the + input_fd file descriptor used in that call is returned. - sd_bus_set_fd() sets the file descriptors used to communicate from a message bus - object. Both input_fd and output_fd must be valid file descriptors. - The same file descriptor may be used as both the input and the output file descriptor. This function must be called - before the bus is started. + sd_bus_set_fd() sets the file descriptors used to communicate from a + message bus object. Both input_fd and output_fd + must be valid file descriptors. The same file descriptor may be used as both the input and the + output file descriptor. This function must be called before the bus is started. - sd_bus_get_events() returns the I/O events to wait for, suitable for passing to - poll() or a similar call. Returns a combination of POLLIN, - POLLOUT, … events, or negative on error. + sd_bus_get_events() returns the I/O events to wait for, suitable for + passing to poll() or a similar call. Returns a combination of + POLLIN, POLLOUT, … events, or negative on error. + sd_bus_get_timeout() returns the time-out in µs to pass to to - poll() or a similar call when waiting for events on the specified bus connection. The returned - time-out may be zero, in which case a subsequent I/O polling call should be invoked in non-blocking mode. The - returned timeout may be UINT64_MAX in which case the I/O polling call may block indefinitely, - without any applied time-out. Note that the returned time-out should be considered only a maximum sleeping time. It - is permissible (and even expected) that shorter time-outs are used by the calling program, in case other event - sources are polled in the same event loop. Note that the returned time-value is relative and specified in - microseconds. When converting this value in order to pass it as third argument to poll() - (which expects milliseconds), care should be taken to use a division that rounds up to ensure the I/O polling - operation doesn't sleep for shorter than necessary, which might result in unintended busy looping (alternatively, - use ppoll3 - instead of plain poll(), which understands time-outs with nano-second granularity). + poll() or a similar call when waiting for events on the specified bus + connection. The returned time-out may be zero, in which case a subsequent I/O polling call + should be invoked in non-blocking mode. The returned timeout may be + UINT64_MAX in which case the I/O polling call may block indefinitely, + without any applied time-out. Note that the returned time-out should be considered only a + maximum sleeping time. It is permissible (and even expected) that shorter time-outs are used by + the calling program, in case other event sources are polled in the same event loop. Note that + the returned time-value is relative and specified in microseconds. When converting this value in + order to pass it as third argument to poll() (which expects milliseconds), + care should be taken to use a division that rounds up to ensure the I/O polling operation + doesn't sleep for shorter than necessary, which might result in unintended busy looping + (alternatively, use + ppoll3 + instead of plain poll(), which understands time-outs with nano-second + granularity). - These three functions are useful to hook up a bus connection object with an external or manual event loop - involving poll() or a similar I/O polling call. Before each invocation of the I/O polling - call, all three functions should be invoked: the file descriptor returned by sd_bus_get_fd() - should be polled for the events indicated by sd_bus_get_events(), and the I/O call should - block for that up to the time-out returned by sd_bus_get_timeout(). After each I/O polling + These three functions are useful to hook up a bus connection object with an external or + manual event loop involving poll() or a similar I/O polling call. Before + each invocation of the I/O polling call, all three functions should be invoked: the file + descriptor returned by sd_bus_get_fd() should be polled for the events + indicated by sd_bus_get_events(), and the I/O call should block for that up + to the time-out returned by sd_bus_get_timeout(). After each I/O polling call the bus connection needs to process incoming or outgoing data, by invoking - sd_bus_process3. + sd_bus_process3. + - Note that these function are only one of three supported ways to implement I/O event handling for bus - connections. Alternatively use - sd_bus_attach_event3 to attach a - bus connection to an sd-event3 - event loop. Or use sd_bus_wait3 + Note that these function are only one of three supported ways to implement I/O event + handling for bus connections. Alternatively use + sd_bus_attach_event3 + to attach a bus connection to an + sd-event3 + event loop. Or use + sd_bus_wait3 as a simple synchronous, blocking I/O waiting call. Return Value - On success, sd_bus_get_fd() returns the file descriptor used for communication. On failure, - it returns a negative errno-style error code. + On success, sd_bus_get_fd() returns the file descriptor used for + communication. On failure, it returns a negative errno-style error code. - On success, sd_bus_set_fd() returns a non-negative integer. On failure, it returns a - negative errno-style error code. + On success, sd_bus_set_fd() returns a non-negative integer. On + failure, it returns a negative errno-style error code. - On success, sd_bus_get_events() returns the I/O event mask to use for I/O event watching. - On failure, it returns a negative errno-style error code. + On success, sd_bus_get_events() returns the I/O event mask to use for + I/O event watching. On failure, it returns a negative errno-style error code. - On success, sd_bus_get_timeout() returns a non-negative integer. On failure, it returns a - negative errno-style error code. + On success, sd_bus_get_timeout() returns a non-negative integer. On + failure, it returns a negative errno-style error code. Errors @@ -136,8 +146,8 @@ -ECHILD - The bus connection was allocated in a parent process and is being reused in a child - process after fork(). + The bus connection was allocated in a parent process and is being reused + in a child process after fork(). @@ -157,8 +167,8 @@ -EBADF - An invalid file descriptor was passed to sd_bus_set_fd(). - + An invalid file descriptor was passed to + sd_bus_set_fd(). From 75358555a5d2eb5bdc574808a39c33e34ccf5d22 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 20 Apr 2020 21:32:35 +0200 Subject: [PATCH 2/4] sd-bus: sd_bus_get_fd docs typo fix --- man/sd_bus_get_fd.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml index eb488b1e6f..d9586f9003 100644 --- a/man/sd_bus_get_fd.xml +++ b/man/sd_bus_get_fd.xml @@ -106,7 +106,7 @@ sd_bus_process3. - Note that these function are only one of three supported ways to implement I/O event + Note that these functions are only one of three supported ways to implement I/O event handling for bus connections. Alternatively use sd_bus_attach_event3 to attach a bus connection to an From b778146b94c927e26e289d0f2cd3514f5438a5a3 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 20 Apr 2020 21:39:07 +0200 Subject: [PATCH 3/4] sd-bus: Rewrap sd_bus_set_description docs --- man/sd_bus_set_description.xml | 70 ++++++++++++++++------------------ 1 file changed, 33 insertions(+), 37 deletions(-) diff --git a/man/sd_bus_set_description.xml b/man/sd_bus_set_description.xml index b855008eb8..05764bc471 100644 --- a/man/sd_bus_set_description.xml +++ b/man/sd_bus_set_description.xml @@ -82,53 +82,49 @@ Description - sd_bus_set_description() sets the description string - that is used in logging to the specified string. The string is copied internally - and freed when the bus object is deallocated. The - description argument may be NULL, in - which case the description is unset. This function must be called before the bus - is started. + sd_bus_set_description() sets the description string that is used in + logging to the specified string. The string is copied internally and freed when the bus object + is deallocated. The description argument may be + NULL, in which case the description is unset. This function must be called + before the bus is started. - sd_bus_get_description() returns a description string - in description. This string may have been previously set - with sd_bus_set_description() or + sd_bus_get_description() returns a description string in + description. This string may have been previously set with + sd_bus_set_description() or sd_bus_open_with_description3 - or similar. If not set this way, a default string like system - or user will be returned for the system or user buses, - and NULL otherwise. + or similar. If not set this way, a default string like system or + user will be returned for the system or user buses, and + NULL otherwise. - sd_bus_set_anonymous() enables or disables "anonymous - authentication", i.e. lack of authentication, of the bus peer. This function must - be called before the bus is started. See the Authentication - Mechanisms section of the D-Bus specification for details. + sd_bus_set_anonymous() enables or disables "anonymous authentication", + i.e. lack of authentication, of the bus peer. This function must be called before the bus is + started. See the + + Authentication Mechanisms section of the D-Bus specification for details. - sd_bus_is_anonymous() returns true if the bus connection allows anonymous - authentication (in the sense described in previous paragraph). + sd_bus_is_anonymous() returns true if the bus connection allows + anonymous authentication (in the sense described in previous paragraph). sd_bus_set_trusted() sets the "trusted" state on the - bus object. If true, all connections on the bus are - trusted and access to all privileged and unprivileged methods is granted. This - function must be called before the bus is started. + bus object. If true, all connections on the bus are trusted and access to + all privileged and unprivileged methods is granted. This function must be called before the bus + is started. - sd_bus_is_trusted() returns true if the bus connection is trusted (in the - sense described in previous paragraph). + sd_bus_is_trusted() returns true if the bus connection is trusted (in + the sense described in previous paragraph). - sd_bus_set_allow_interactive_authorization() - enables or disables interactive authorization for method calls. If true, - messages are marked with the + sd_bus_set_allow_interactive_authorization() enables or disables + interactive authorization for method calls. If true, messages are marked with the ALLOW_INTERACTIVE_AUTHORIZATION flag specified by the - D-Bus - specification, informing the receiving side that the caller is prepared to - wait for interactive authorization, which might take a considerable time to - complete. If this flag is set, the user may be queried for passwords or - confirmation via polkit or a - similar framework. + D-Bus + specification, informing the receiving side that the caller is prepared to wait for interactive + authorization, which might take a considerable time to complete. If this flag is set, the user + may be queried for passwords or confirmation via + polkit or a similar + framework. - sd_bus_get_allow_interactive_authorization() returns - true if interactive authorization is allowed and false if not. + sd_bus_get_allow_interactive_authorization() returns true if + interactive authorization is allowed and false if not. From 4eaf8bc69e9ef76d04fa483e1257fc9c857a8a38 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Mon, 20 Apr 2020 21:33:24 +0200 Subject: [PATCH 4/4] sd-bus: Add sd_bus_get_scope/tid/unique_name docs --- man/rules/meson.build | 3 ++ man/sd-bus.xml | 3 ++ man/sd_bus_set_description.xml | 57 +++++++++++++++++++++++++++++++++- 3 files changed, 62 insertions(+), 1 deletion(-) diff --git a/man/rules/meson.build b/man/rules/meson.build index 3b52d33e37..659edab1ab 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -379,6 +379,9 @@ manpages = [ '3', ['sd_bus_get_allow_interactive_authorization', 'sd_bus_get_description', + 'sd_bus_get_scope', + 'sd_bus_get_tid', + 'sd_bus_get_unique_name', 'sd_bus_is_anonymous', 'sd_bus_is_trusted', 'sd_bus_set_allow_interactive_authorization', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 3237eb82cc..c073d3bccc 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -80,6 +80,9 @@ sd_bus_get_fd3, sd_bus_get_method_call_timeout3, sd_bus_get_n_queued_read3, +sd_bus_get_scope3, +sd_bus_get_tid3, +sd_bus_get_unique_name3, sd_bus_is_bus_client3, sd_bus_is_server3, sd_bus_message_append3, diff --git a/man/sd_bus_set_description.xml b/man/sd_bus_set_description.xml index 05764bc471..bd3ec78864 100644 --- a/man/sd_bus_set_description.xml +++ b/man/sd_bus_set_description.xml @@ -24,6 +24,9 @@ sd_bus_is_trusted sd_bus_set_allow_interactive_authorization sd_bus_get_allow_interactive_authorization + sd_bus_get_scope + sd_bus_get_tid + sd_bus_get_unique_name Set or query properties of a bus object @@ -76,6 +79,24 @@ int sd_bus_get_allow_interactive_authorization sd_bus *bus + + + int sd_bus_get_scope + sd_bus *bus + const char **scope + + + + int sd_bus_get_tid + sd_bus *bus + pid_t *tid + + + + int sd_bus_get_unique_name + sd_bus *bus + const char **unique + @@ -125,6 +146,27 @@ sd_bus_get_allow_interactive_authorization() returns true if interactive authorization is allowed and false if not. + + sd_bus_get_scope() stores the scope of the given bus object in + scope. The scope of the system bus is system. The + scope of a user session bus is user. If the given bus object is not the + system or a user session bus, sd_bus_get_scope() returns an error. + + sd_bus_get_tid() stores the kernel thread id of the thread associated + with the given bus object in tid. If bus is a + default bus object obtained by calling one of the functions of the + sd_bus_default3 + family of functions, it stores the thread id of the thread the bus object was created in. + Otherwise, if the bus object is attached to an event loop, it stores the thread id of the + thread the event loop object was created in. If bus is not a default bus + object and is not attached to an event loop, sd_bus_get_tid() returns an + error. + + sd_bus_get_unique_name() stores the unique name of the bus object on + the bus in unique. See + + The D-Bus specification for more information on bus names. Note that the caller does not + own the string stored in unique and should not free it. @@ -168,8 +210,21 @@ Memory allocation failed. - + + -ENODATA + + The bus object passed to sd_bus_get_scope() was not a + system or user session bus. + + + + -ENXIO + + The bus object passed to sd_bus_get_tid() was not a + default bus object and is not attached to an event loop. + +