From 4a2af8d76f71064f2605c538102e23dc31b31cb2 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 30 Apr 2015 01:52:39 +0200 Subject: [PATCH] man: update sd_bus_open() documentation Update for current function prototypes. Also, document -ESOCKTNOSUPPORT as being returned when protocol version mismatches are detected. --- Makefile-man.am | 36 +++-- ...d_bus_open_user.xml => sd_bus_default.xml} | 150 ++++++++++++------ 2 files changed, 121 insertions(+), 65 deletions(-) rename man/{sd_bus_open_user.xml => sd_bus_default.xml} (59%) diff --git a/Makefile-man.am b/Makefile-man.am index e297b21041..85579e0c0a 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -769,6 +769,7 @@ if ENABLE_KDBUS MANPAGES += \ man/sd_bus_creds_get_pid.3 \ man/sd_bus_creds_new_from_pid.3 \ + man/sd_bus_default.3 \ man/sd_bus_error.3 \ man/sd_bus_message_append.3 \ man/sd_bus_message_append_array.3 \ @@ -779,7 +780,6 @@ MANPAGES += \ man/sd_bus_message_get_monotonic_usec.3 \ man/sd_bus_negotiate_fds.3 \ man/sd_bus_new.3 \ - man/sd_bus_open_user.3 \ man/sd_bus_path_encode.3 \ man/sd_bus_request_name.3 \ man/sd_event_add_child.3 \ @@ -850,9 +850,11 @@ MANPAGES_ALIAS += \ man/sd_bus_message_get_seqnum.3 \ man/sd_bus_negotiate_creds.3 \ man/sd_bus_negotiate_timestamps.3 \ + man/sd_bus_open.3 \ man/sd_bus_open_system.3 \ - man/sd_bus_open_system_container.3 \ + man/sd_bus_open_system_machine.3 \ man/sd_bus_open_system_remote.3 \ + man/sd_bus_open_user.3 \ man/sd_bus_path_decode.3 \ man/sd_bus_ref.3 \ man/sd_bus_release_name.3 \ @@ -909,8 +911,8 @@ man/sd_bus_creds_has_inheritable_cap.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_has_permitted_cap.3: man/sd_bus_creds_get_pid.3 man/sd_bus_creds_ref.3: man/sd_bus_creds_new_from_pid.3 man/sd_bus_creds_unref.3: man/sd_bus_creds_new_from_pid.3 -man/sd_bus_default_system.3: man/sd_bus_open_user.3 -man/sd_bus_default_user.3: man/sd_bus_open_user.3 +man/sd_bus_default_system.3: man/sd_bus_default.3 +man/sd_bus_default_user.3: man/sd_bus_default.3 man/sd_bus_error_copy.3: man/sd_bus_error.3 man/sd_bus_error_free.3: man/sd_bus_error.3 man/sd_bus_error_get_errno.3: man/sd_bus_error.3 @@ -930,9 +932,11 @@ man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3 man/sd_bus_message_get_seqnum.3: man/sd_bus_message_get_monotonic_usec.3 man/sd_bus_negotiate_creds.3: man/sd_bus_negotiate_fds.3 man/sd_bus_negotiate_timestamps.3: man/sd_bus_negotiate_fds.3 -man/sd_bus_open_system.3: man/sd_bus_open_user.3 -man/sd_bus_open_system_container.3: man/sd_bus_open_user.3 -man/sd_bus_open_system_remote.3: man/sd_bus_open_user.3 +man/sd_bus_open.3: man/sd_bus_default.3 +man/sd_bus_open_system.3: man/sd_bus_default.3 +man/sd_bus_open_system_machine.3: man/sd_bus_default.3 +man/sd_bus_open_system_remote.3: man/sd_bus_default.3 +man/sd_bus_open_user.3: man/sd_bus_default.3 man/sd_bus_path_decode.3: man/sd_bus_path_encode.3 man/sd_bus_ref.3: man/sd_bus_new.3 man/sd_bus_release_name.3: man/sd_bus_request_name.3 @@ -1059,10 +1063,10 @@ man/sd_bus_creds_ref.html: man/sd_bus_creds_new_from_pid.html man/sd_bus_creds_unref.html: man/sd_bus_creds_new_from_pid.html $(html-alias) -man/sd_bus_default_system.html: man/sd_bus_open_user.html +man/sd_bus_default_system.html: man/sd_bus_default.html $(html-alias) -man/sd_bus_default_user.html: man/sd_bus_open_user.html +man/sd_bus_default_user.html: man/sd_bus_default.html $(html-alias) man/sd_bus_error_copy.html: man/sd_bus_error.html @@ -1122,13 +1126,19 @@ man/sd_bus_negotiate_creds.html: man/sd_bus_negotiate_fds.html man/sd_bus_negotiate_timestamps.html: man/sd_bus_negotiate_fds.html $(html-alias) -man/sd_bus_open_system.html: man/sd_bus_open_user.html +man/sd_bus_open.html: man/sd_bus_default.html $(html-alias) -man/sd_bus_open_system_container.html: man/sd_bus_open_user.html +man/sd_bus_open_system.html: man/sd_bus_default.html $(html-alias) -man/sd_bus_open_system_remote.html: man/sd_bus_open_user.html +man/sd_bus_open_system_machine.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_system_remote.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_user.html: man/sd_bus_default.html $(html-alias) man/sd_bus_path_decode.html: man/sd_bus_path_encode.html @@ -1721,6 +1731,7 @@ EXTRA_DIST += \ man/sd_booted.xml \ man/sd_bus_creds_get_pid.xml \ man/sd_bus_creds_new_from_pid.xml \ + man/sd_bus_default.xml \ man/sd_bus_error.xml \ man/sd_bus_message_append.xml \ man/sd_bus_message_append_array.xml \ @@ -1731,7 +1742,6 @@ EXTRA_DIST += \ man/sd_bus_message_get_monotonic_usec.xml \ man/sd_bus_negotiate_fds.xml \ man/sd_bus_new.xml \ - man/sd_bus_open_user.xml \ man/sd_bus_path_encode.xml \ man/sd_bus_request_name.xml \ man/sd_event_add_child.xml \ diff --git a/man/sd_bus_open_user.xml b/man/sd_bus_default.xml similarity index 59% rename from man/sd_bus_open_user.xml rename to man/sd_bus_default.xml index 3c16eacba0..98ec04ecde 100644 --- a/man/sd_bus_open_user.xml +++ b/man/sd_bus_default.xml @@ -21,10 +21,10 @@ along with systemd; If not, see . --> - + - sd_bus_open_user + sd_bus_default systemd @@ -38,26 +38,48 @@ - sd_bus_open_user + sd_bus_default 3 - sd_bus_open_user - sd_bus_open_system - sd_bus_open_system_remote - sd_bus_open_system_container - + sd_bus_default sd_bus_default_user sd_bus_default_system - Open a connection to the system or user bus + 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 @@ -70,36 +92,59 @@ int sd_bus_open_system_remote + sd_bus **bus const char *host - sd_bus **bus - int sd_bus_open_system_container + int sd_bus_open_system_machine + sd_bus **bus 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 + 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), @@ -108,10 +153,10 @@ 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 + 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. @@ -123,20 +168,11 @@ sd_bus_open_system_container() connects to the system bus in the specified machine, - where machine is the name of a container. - See + where machine is the name of a local + 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. @@ -149,7 +185,8 @@ Reference ownership - Functions sd_bus_open_user(), + 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 @@ -158,9 +195,13 @@ sd_bus_unref3. - The functions sd_bus_default_user() and - sd_bus_default_system() do not create a new - reference. + 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. @@ -173,9 +214,7 @@ -EINVAL - Specified parameter is invalid - (NULL in case of output - parameters). + The specified parameters are invalid. @@ -184,18 +223,25 @@ Memory allocation failed. - In addition, any further connection-related errors may be - by returned. See sd_bus_send3. + + -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 other functions - described here are available as a shared library, which can be - compiled and linked to with the - libsystemd pkg-config1 + 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.