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 +++++++++++++++++++++++++++++++++++++++++++++++ man/sd_bus_open_user.xml | 217 -------------------------------------- 2 files changed, 263 insertions(+), 217 deletions(-) create mode 100644 man/sd_bus_default.xml delete mode 100644 man/sd_bus_open_user.xml (limited to 'man') 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 + + + + diff --git a/man/sd_bus_open_user.xml b/man/sd_bus_open_user.xml deleted file mode 100644 index 3c16eacba0..0000000000 --- a/man/sd_bus_open_user.xml +++ /dev/null @@ -1,217 +0,0 @@ - - - - - - - - - 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 user bus. - sd_bus_open_system() does the same, but - connects to the system bus. - - 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 container. - See - machinectl1 - for more information about "machines". - - sd_bus_default_user() returns a bus - object connected to the user bus. Each thread has its own object, but it - may be passed around. 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. - - - The 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 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