From: Zbigniew Jędrzejewski-Szmek Date: Wed, 18 Mar 2020 10:38:15 +0000 (+0100) Subject: man: add sd_bus_start(3) X-Git-Tag: v246-rc1~726^2~7 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=27622235c41e7e28e414378d26995dbcd619fab5;p=thirdparty%2Fsystemd.git man: add sd_bus_start(3) --- diff --git a/man/rules/meson.build b/man/rules/meson.build index f9762ffb2e1..0be4b9c86ce 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 2f6013b7b04..14fca6ee6b1 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 51c27f04fff..ca06f8e6f43 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 7771a78d8b8..ceca3350fc4 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 00000000000..0be07f47778 --- /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 + + + +