From cd6d5e1c7631d6e74cb04be279dee22e423e08b8 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Sat, 4 Jan 2014 00:08:50 -0500 Subject: man: document a batch of bus functions --- man/sd_bus_open_user.xml | 217 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 man/sd_bus_open_user.xml (limited to 'man/sd_bus_open_user.xml') diff --git a/man/sd_bus_open_user.xml b/man/sd_bus_open_user.xml new file mode 100644 index 0000000000..62b856993d --- /dev/null +++ b/man/sd_bus_open_user.xml @@ -0,0 +1,217 @@ + + + + + + + + + sd_bus_open_user + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_open_user + 3 + + + + sd_bus_open_user + sd_bus_open_system + sd_bus_open_system_remote + sd_bus_open_system_container + + sd_bus_default_user + sd_bus_default_system + + Open a connection to the system or user bus + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_open_user + sd_bus** bus + + + + int sd_bus_open_system + sd_bus** bus + + + + int sd_bus_open_system_remote + const char *host + sd_bus** bus + + + + int sd_bus_open_system_container + const char *machine + sd_bus** bus + + + + int sd_bus_default_user + sd_bus** bus + + + + int sd_bus_default_system + sd_bus** bus + + + + + + Description + + sd_bus_open_user() creates a new bus + object and opens a connection to the the user bus. + sd_bus_open_system() does the same, but + connects to the system bus. + + If $DBUS_SESSION_BUS_ADDRESS environment + variable is set + (c.f. 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 $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_remote() connects to + the system bus in the specified machine, + where machine is the name of a container. + See + machinectl1 + for more information about "machines". + + sd_bus_default_user() returns a bus + object connected to the user bus. This bus object is shared + per-thread. It is created on the first invocation of + sd_bus_default_user(), and subsequent + invocations returns a reference to the same object. + + sd_bus_default_system() is similar to + sd_bus_default_user(), but connects to the + system bus. + + + + 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 + Functions sd_bus_open_user(), + 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. + + + Functions sd_bus_default_user() and + sd_bus_default_system() do not create a new + reference. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + Specified parameter is invalid + (NULL in case of output + parameters). + + + + -ENOMEM + + Memory allocation failed. + + + In addition, any further connection-related errors may be + by returned. See sd_bus_send3. + + + + + Notes + + sd_bus_open_user() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libsystemd-bus 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