From 4a2af8d76f71064f2605c538102e23dc31b31cb2 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 30 Apr 2015 01:52:39 +0200 Subject: man: update sd_bus_open() documentation Update for current function prototypes. Also, document -ESOCKTNOSUPPORT as being returned when protocol version mismatches are detected. --- man/sd_bus_default.xml | 263 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 man/sd_bus_default.xml (limited to 'man/sd_bus_default.xml') diff --git a/man/sd_bus_default.xml b/man/sd_bus_default.xml new file mode 100644 index 0000000000..98ec04ecde --- /dev/null +++ b/man/sd_bus_default.xml @@ -0,0 +1,263 @@ + + + + + + + + + sd_bus_default + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_default + 3 + + + + sd_bus_default + sd_bus_default_user + sd_bus_default_system + + sd_bus_open + sd_bus_open_user + sd_bus_open_system + sd_bus_open_system_remote + sd_bus_open_system_machine + + Acquire a connection to a system or user bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_default + sd_bus **bus + + + + int sd_bus_default_user + sd_bus **bus + + + + int sd_bus_default_system + sd_bus **bus + + + + int sd_bus_open + sd_bus **bus + + + + int sd_bus_open_user + sd_bus **bus + + + + int sd_bus_open_system + sd_bus **bus + + + + int sd_bus_open_system_remote + sd_bus **bus + const char *host + + + + int sd_bus_open_system_machine + sd_bus **bus + const char *machine + + + + + + + Description + + sd_bus_default() acquires a bus + connection object to the user bus when invoked in user context or + to the system bus otherwise. The connection object is associated + to the calling thread. Each time the function is invoked from the + same thread the same object is returned, but its reference count + increased by one, as long as at least one reference is kept. When + the last reference to the connection is dropped (using the + sd_bus_unref() call), the connection is + terminated. Note that the connection is not automatically + terminated when the associated thread ends. It is important to + drop the last reference to the bus connection explicitly before + the thread ends or otherwise the connection will be leaked. + + sd_bus_default_user() returns a user + bus connection object associated to the calling thread. + sd_bus_default_system() is similar, but + connects to the system bus. + + sd_bus_open() creates a new, + independent bus connection to the user bus when invoked in user + context or the system bus + otherwise. sd_bus_open_user() is similar, but + connects only to the user bus. + sd_bus_open_system() does the same, but + connects to the system bus. In contrast to + sd_bus_default(), + sd_bus_default_user(), + sd_bus_default_system() these calls return + new, independent connection objects that are not associated with + the invoking thread and are not shared between multiple + invocations. It is recommended to share connections per thread to + efficiently make use the available resources. Thus, it is + recommended to use sd_bus_default(), + sd_bus_default_user(), + sd_bus_default_system() to connect to the + user or system busses. + + If the $DBUS_SESSION_BUS_ADDRESS environment + variable is set + (cf. environ7), + it will be used as the address of the user bus. This variable can + contain multiple addresses separated by ;. If + this variable is not set, a suitable default for the default user + D-Bus instance will be used. + + If the $DBUS_SYSTEM_BUS_ADDRESS + environment variable is set, it will be used as the address of the + system bus. This variable uses the same syntax as + $DBUS_SESSION_BUS_ADDRESS. If this variable is + not set, a suitable default for the default system D-Bus instance + will be used. + + sd_bus_open_system_remote() connects to + the system bus on the specified host using + SSH. host consists of an optional user name + followed by the @ symbol, and the hostname. + + + sd_bus_open_system_container() connects + to the system bus in the specified machine, + where machine is the name of a local + container. See + machinectl1 + for more information about "machines". + + + + + Return Value + + On success, these calls return 0 or a positive + integer. On failure, these calls return a negative + errno-style error code. + + + + Reference ownership + The functions sd_bus_open_user(), + sd_bus_open(), + sd_bus_open_system(), + sd_bus_open_system_remote(), and + sd_bus_open_system_machine() return a new + object and the caller owns the sole reference. When not needed + anymore, this reference should be destroyed with + sd_bus_unref3. + + + The functions sd_bus_default(), + sd_bus_default_user() and + sd_bus_default_system() do not necessarily + create a new object, but increase the connection reference by + one. Use + sd_bus_unref3 + to drop the reference. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified parameters are invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + -ESOCKTNOSUPPORT + + The protocol version required to connect to the selected bus is not supported. + + + + In addition, any further connection-related errors may be + by returned. See sd_bus_send3. + + + + Notes + + sd_bus_open_user() 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. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_ref3, + sd_bus_unref3, + ssh1, + systemd-machined.service8, + machinectl1 + + + + -- cgit v1.2.3-54-g00ecf