diff --git a/man/rules/meson.build b/man/rules/meson.build index f9762ffb2e..0be4b9c86c 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -356,6 +356,7 @@ manpages = [ ''], ['sd_bus_slot_set_floating', '3', ['sd_bus_slot_get_floating'], ''], ['sd_bus_slot_set_userdata', '3', ['sd_bus_slot_get_userdata'], ''], + ['sd_bus_start', '3', [], ''], ['sd_bus_track_add_name', '3', ['sd_bus_track_add_sender', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 2f6013b7b0..14fca6ee6b 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -94,6 +94,7 @@ sd_bus_slot_set_destroy_callback3, sd_bus_slot_set_floating3, sd_bus_slot_set_userdata3, +sd_bus_start3, sd_bus_track_add_name3, sd_bus_track_new3 diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml index 51c27f04ff..ca06f8e6f4 100644 --- a/man/sd_bus_default.xml +++ b/man/sd_bus_default.xml @@ -297,7 +297,7 @@ - In addition, any further connection-related errors may be by returned. See + In addition, other connection-related errors may be returned. See sd_bus_send3. diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 7771a78d8b..ceca3350fc 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -87,14 +87,12 @@ or a related call, and then start the connection with sd_bus_start3. - In most cases, it is a better idea to invoke + In most cases, it is better to use sd_bus_default_user3, sd_bus_default_system3 - or related calls instead of the more low-level - sd_bus_new() and - sd_bus_start(). The higher-level calls not - only allocate a bus object but also start the connection to a - well-known bus in a single function invocation. + or related calls instead of the more low-level sd_bus_new() and + sd_bus_start(). The higher-level functions not only allocate a bus object but also + start the connection to a well-known bus in a single function call. sd_bus_ref() increases the reference counter of bus by one. diff --git a/man/sd_bus_start.xml b/man/sd_bus_start.xml new file mode 100644 index 0000000000..0be07f4777 --- /dev/null +++ b/man/sd_bus_start.xml @@ -0,0 +1,124 @@ + + + + + + + + sd_bus_start + systemd + + + + sd_bus_start + 3 + + + + sd_bus_start + + Initiate a bus connection to the D-bus broker daemon + + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_start + sd_bus *bus + + + + + + Description + + sd_bus_start() connects an existing bus connection object to the D-Bus + broker daemon, usually + dbus-daemon1 + or + dbus-broker1. + The mechanism to use for the connection must be configured before the call to + sd_bus_start(), using one of + sd_bus_set_address3, + sd_bus_set_fd3, or + sd_bus_set_exec3. + sd_bus_start() will open the connection socket or spawn the executable as + needed, and asynchronously start a org.freedesktop.DBus.Hello() call. The + answer to the Hello call will be processed later from + sd_bus_process3. If + opening of the connection or queuing of the asynchronous call fail, the connection will be closed with + sd_bus_close3. + + In most cases, it is better to use + sd_bus_default_user3, + sd_bus_default_system3 + or related calls instead of the more low-level sd_bus_new() and + sd_bus_start(). The higher-level functions not only allocate a bus object but also + start the connection to a well-known bus in a single function call. + + + + Return Value + + On success, this function returns a non-negative integer. On failure, it returns a negative + errno-style error code. + + + Errors + + + + -EINVAL + + The input parameter bus is NULL. + + + + + -ENOPKG + + Bus object bus could not be resolved. + + + + + -EPERM + + The input parameter bus is in a wrong state + (sd_bus_start() may only be called once on a newly-created bus object). + + + + + -ECHILD + + The bus object bus was created in a different + process. + + + + + In addition, other connection-related errors may be returned. See + sd_bus_send3. + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_default3, + sd_bus_call_async3 + + + +