diff --git a/man/rules/meson.build b/man/rules/meson.build
index b3011c5f04b..1a6debaafff 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -114,6 +114,8 @@ manpages = [
'sd_bus_match_signal',
'sd_bus_match_signal_async'],
''],
+ ['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
+ ['sd_bus_close', '3', ['sd_bus_flush'], ''],
['sd_bus_creds_get_pid',
'3',
['sd_bus_creds_get_audit_login_uid',
@@ -271,7 +273,14 @@ manpages = [
'3',
['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'],
''],
- ['sd_bus_new', '3', ['sd_bus_ref', 'sd_bus_unref', 'sd_bus_unrefp'], ''],
+ ['sd_bus_new',
+ '3',
+ ['sd_bus_flush_close_unref',
+ 'sd_bus_flush_close_unrefp',
+ 'sd_bus_ref',
+ 'sd_bus_unref',
+ 'sd_bus_unrefp'],
+ ''],
['sd_bus_path_encode',
'3',
['sd_bus_path_decode', 'sd_bus_path_decode_many', 'sd_bus_path_encode_many'],
diff --git a/man/sd-bus.xml b/man/sd-bus.xml
index bf2f37a86d9..949e320c75b 100644
--- a/man/sd-bus.xml
+++ b/man/sd-bus.xml
@@ -44,6 +44,7 @@
See
sd_bus_add_match3,
+sd_bus_attach_event3,
sd_bus_creds_get_pid3,
sd_bus_creds_new_from_pid3,
sd_bus_default3,
diff --git a/man/sd_bus_attach_event.xml b/man/sd_bus_attach_event.xml
new file mode 100644
index 00000000000..45f034910fe
--- /dev/null
+++ b/man/sd_bus_attach_event.xml
@@ -0,0 +1,114 @@
+
+
+
+
+
+
+
+
+ sd_bus_attach_event
+ systemd
+
+
+
+ sd_bus_attach_event
+ 3
+
+
+
+ sd_bus_attach_event
+ sd_bus_detach_event
+ sd_bus_get_event
+
+ Attach a bus connection object to an event loop
+
+
+
+
+ #include <systemd/sd-bus.h>
+
+
+ int sd_bus_attach_event
+ sd_bus *bus
+ sd_event *e
+ int priority
+
+
+
+ int sd_bus_detach_event
+ sd_bus *bus
+
+
+
+ sd_event *sd_bus_get_event
+ sd_bus *bus
+
+
+
+
+
+ Description
+
+ sd_bus_attach_event() attaches the specified bus connection object to an
+ sd-event3 event loop object at
+ the specified priority (see
+ sd_event_source_set_priority3
+ for details on event loop priorities). When a bus connection object is attached to an event loop incoming messages
+ will be automatically read and processed, and outgoing messages written, whenever the event loop is run. When the
+ event loop is about to terminate, the bus connection is automatically flushed and closed (see
+ sd_bus_set_close_on_exit3 for
+ details on this). By default bus connection objects are not attached to any event loop. When a bus connection
+ object is attached to one it is not necessary to invoke
+ sd_bus_wait3 or
+ sd_bus_process3 as this
+ functionality is handled automatically by the event loop.
+
+ sd_bus_detach_event() detaches a bus object from its event loop.
+
+ The sd_bus_get_event() returns the event loop object the specified bus object is
+ currently attached to, or NULL if it is currently not attached to any.
+
+
+
+ Return Value
+
+ On success, sd_bus_attach_event() and sd_bus_detach_event() return
+ 0 or a positive integer. On failure, they return a negative errno-style error code.
+
+ sd_bus_get_event() returns an event loop object or NULL.
+
+
+
+ Errors
+
+ Returned errors may indicate the following problems:
+
+
+
+ -ECHILD
+
+ The bus connection has been created in a different process.
+
+
+
+
+
+
+
+ See Also
+
+
+ systemd1,
+ sd-bus3,
+ sd-event3,
+ sd_event_source_set_priority3,
+ sd_bus_set_close_on_exit3,
+ sd_bus_wait3
+
+
+
+
diff --git a/man/sd_bus_close.xml b/man/sd_bus_close.xml
new file mode 100644
index 00000000000..369afd87471
--- /dev/null
+++ b/man/sd_bus_close.xml
@@ -0,0 +1,101 @@
+
+
+
+
+
+
+
+
+ sd_bus_close
+ systemd
+
+
+
+ sd_bus_close
+ 3
+
+
+
+ sd_bus_close
+ sd_bus_flush
+
+ Close and flush a bus connection
+
+
+
+
+ #include <systemd/sd-bus.h>
+
+
+ void sd_bus_close
+ sd_bus *bus
+
+
+
+ int sd_bus_flush
+ sd_bus *bus
+
+
+
+
+
+ Description
+
+ sd_bus_close() disconnects the specified bus connection. When this call is invoked and
+ the specified bus object refers to an active connection it is immediately terminated. No further messages may be
+ sent or receieved on it. Any messages queued in the bus object (both incoming and outgoing) are released. If
+ invoked on NULL bus object or when the bus connection is already closed this function executes
+ no operation. This call does not free or unreference the bus object itself. Use
+ sd_bus_unref3 for that.
+
+ sd_bus_flush() synchronously writes out all outgoing queued message on a bus connection
+ if there are any. This function call may block if the peer is not processing bus messages quickly.
+
+ Before a program exits it is usually a good idea to flush any pending messages with
+ sd_bus_flush() and then close connections with sd_bus_close() to ensure
+ that no unwritten messages are lost, no further messages may be queued and all incoming but unprocessed messages
+ are released. After both operations have been done, it is a good idea to also drop any remaining references to the
+ bus object so that it may be freed. Since these three operations are frequently done together a helper call
+ sd_bus_flush_close_unref3 is
+ provided that combines them into one.
+
+
+
+ Return Value
+
+ On success, sd_bus_flush() returns 0 or a positive integer. On failure, it returns a
+ negative errno-style error code.
+
+
+
+ Errors
+
+ Returned errors may indicate the following problems:
+
+
+
+ -ECHILD
+
+ The bus connection has been created in a different process.
+
+
+
+
+
+
+
+ See Also
+
+
+ systemd1,
+ sd-bus3,
+ sd_bus_unref3,
+ sd_bus_set_close_on_exit3
+
+
+
+
diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml
index 59117676fde..1bc011d70a1 100644
--- a/man/sd_bus_new.xml
+++ b/man/sd_bus_new.xml
@@ -23,6 +23,8 @@
sd_bus_ref
sd_bus_unref
sd_bus_unrefp
+ sd_bus_flush_close_unref
+ sd_bus_flush_close_unrefp
Create a new bus object and create or destroy references to it
@@ -50,6 +52,16 @@
void sd_bus_unrefp
sd_bus **busp
+
+
+ sd_bus *sd_bus_flush_close_unref
+ sd_bus *bus
+
+
+
+ void sd_bus_flush_close_unrefp
+ sd_bus **busp
+
@@ -111,6 +123,18 @@
dereference its argument, which must not be NULL, and will
execute no operation if that is NULL.
+
+ sd_bus_flush_close_unref() is similar to sd_bus_unref(), but first
+ executes sd_bus_flush3 as well
+ as sd_bus_close3, ensuring that
+ any pending messages are properly flushed out before the reference to the connection is dropped and possibly the
+ object freed. This call is particularly useful immediately before exiting from a program as it ensures that any
+ pending outgoing messages are written out, and unprocessed but queued incoming messages released before the
+ connection is terminated and released.
+
+ sd_bus_flush_close_unrefp() is similar to
+ sd_bus_flush_close_unref(), but may be used in GCC's and LLVM's Clean-up Variable Attribute,
+ see above.
@@ -123,7 +147,7 @@
sd_bus_ref() always returns the argument.
- sd_bus_unref() always returns
+ sd_bus_unref() and sd_bus_flush_close_unref() always return
NULL.
@@ -152,7 +176,8 @@
sd_bus_default_user3,
sd_bus_default_system3,
sd_bus_open_user3,
- sd_bus_open_system3
+ sd_bus_open_system3,
+ sd_bus_close3