diff options
| -rw-r--r-- | Makefile-man.am | 36 | ||||
| -rw-r--r-- | man/sd_bus_default.xml (renamed from man/sd_bus_open_user.xml) | 140 |
2 files changed, 116 insertions, 60 deletions
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.html: man/sd_bus_default.html + $(html-alias) + +man/sd_bus_open_system_machine.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_remote.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_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 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 <http://www.gnu.org/licenses/>. --> -<refentry id="sd_bus_open_user" conditional="ENABLE_KDBUS"> +<refentry id="sd_bus_default" conditional="ENABLE_KDBUS"> <refentryinfo> - <title>sd_bus_open_user</title> + <title>sd_bus_default</title> <productname>systemd</productname> <authorgroup> @@ -38,20 +38,22 @@ </refentryinfo> <refmeta> - <refentrytitle>sd_bus_open_user</refentrytitle> + <refentrytitle>sd_bus_default</refentrytitle> <manvolnum>3</manvolnum> </refmeta> <refnamediv> + <refname>sd_bus_default</refname> + <refname>sd_bus_default_user</refname> + <refname>sd_bus_default_system</refname> + + <refname>sd_bus_open</refname> <refname>sd_bus_open_user</refname> <refname>sd_bus_open_system</refname> <refname>sd_bus_open_system_remote</refname> - <refname>sd_bus_open_system_container</refname> - - <refname>sd_bus_default_user</refname> - <refname>sd_bus_default_system</refname> + <refname>sd_bus_open_system_machine</refname> - <refpurpose>Open a connection to the system or user bus</refpurpose> + <refpurpose>Acquire a connection to a system or user bus</refpurpose> </refnamediv> <refsynopsisdiv> @@ -59,47 +61,90 @@ <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> <funcprototype> - <funcdef>int <function>sd_bus_open_user</function></funcdef> + <funcdef>int <function>sd_bus_default</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_bus_open_system</function></funcdef> + <funcdef>int <function>sd_bus_default_user</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_bus_open_system_remote</function></funcdef> - <paramdef>const char *<parameter>host</parameter></paramdef> + <funcdef>int <function>sd_bus_default_system</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_bus_open_system_container</function></funcdef> - <paramdef>const char *<parameter>machine</parameter></paramdef> + <funcdef>int <function>sd_bus_open</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_bus_default_user</function></funcdef> + <funcdef>int <function>sd_bus_open_user</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> <funcprototype> - <funcdef>int <function>sd_bus_default_system</function></funcdef> + <funcdef>int <function>sd_bus_open_system</function></funcdef> <paramdef>sd_bus **<parameter>bus</parameter></paramdef> </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system_remote</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>host</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>int <function>sd_bus_open_system_machine</function></funcdef> + <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>const char *<parameter>machine</parameter></paramdef> + </funcprototype> + </funcsynopsis> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><function>sd_bus_open_user()</function> creates a new bus - object and opens a connection to the user bus. - <function>sd_bus_open_system()</function> does the same, but + <para><function>sd_bus_default()</function> 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 + <function>sd_bus_unref()</function> 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.</para> + + <para><function>sd_bus_default_user()</function> returns a user + bus connection object associated to the calling thread. + <function>sd_bus_default_system()</function> is similar, but connects to the system bus.</para> + <para><function>sd_bus_open()</function> creates a new, + independent bus connection to the user bus when invoked in user + context or the system bus + otherwise. <function>sd_bus_open_user()</function> is similar, but + connects only to the user bus. + <function>sd_bus_open_system()</function> does the same, but + connects to the system bus. In contrast to + <function>sd_bus_default()</function>, + <function>sd_bus_default_user()</function>, + <function>sd_bus_default_system()</function> 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 <function>sd_bus_default()</function>, + <function>sd_bus_default_user()</function>, + <function>sd_bus_default_system()</function> to connect to the + user or system busses.</para> + <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment variable is set (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>), @@ -108,10 +153,10 @@ this variable is not set, a suitable default for the default user D-Bus instance will be used.</para> - <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> environment - variable is set, it will be used as the address of the system - bus. This variable uses the same syntax as - <varname>$DBUS_SESSION_BUS_ADDRESS</varname>/. If this variable is + <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> + environment variable is set, it will be used as the address of the + system bus. This variable uses the same syntax as + <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is not set, a suitable default for the default system D-Bus instance will be used.</para> @@ -123,20 +168,11 @@ <para><function>sd_bus_open_system_container()</function> connects to the system bus in the specified <parameter>machine</parameter>, - where <parameter>machine</parameter> is the name of a container. - See + where <parameter>machine</parameter> is the name of a local + container. See <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more information about "machines".</para> - <para><function>sd_bus_default_user()</function> 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 - <function>sd_bus_default_user()</function>, and subsequent - invocations returns a reference to the same object.</para> - - <para><function>sd_bus_default_system()</function> is similar to - <function>sd_bus_default_user()</function>, but connects to the - system bus.</para> </refsect1> <refsect1> @@ -149,7 +185,8 @@ <refsect1> <title>Reference ownership</title> - <para>Functions <function>sd_bus_open_user()</function>, + <para>The functions <function>sd_bus_open_user()</function>, + <function>sd_bus_open()</function>, <function>sd_bus_open_system()</function>, <function>sd_bus_open_system_remote()</function>, and <function>sd_bus_open_system_machine()</function> return a new @@ -158,9 +195,13 @@ <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. </para> - <para>The functions <function>sd_bus_default_user()</function> and - <function>sd_bus_default_system()</function> do not create a new - reference.</para> + <para>The functions <function>sd_bus_default()</function>, + <function>sd_bus_default_user()</function> and + <function>sd_bus_default_system()</function> do not necessarily + create a new object, but increase the connection reference by + one. Use + <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> + to drop the reference.</para> </refsect1> <refsect1> @@ -173,9 +214,7 @@ <varlistentry> <term><constant>-EINVAL</constant></term> - <listitem><para>Specified parameter is invalid - (<constant>NULL</constant> in case of output - parameters).</para></listitem> + <listitem><para>The specified parameters are invalid.</para></listitem> </varlistentry> <varlistentry> @@ -184,18 +223,25 @@ <listitem><para>Memory allocation failed.</para></listitem> </varlistentry> - <para>In addition, any further connection-related errors may be - by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + <varlistentry> + <term><constant>-ESOCKTNOSUPPORT</constant></term> + + <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem> + </varlistentry> </variablelist> + + <para>In addition, any further connection-related errors may be + by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> </refsect1> <refsect1> <title>Notes</title> - <para><function>sd_bus_open_user()</function> and other functions - described here are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <para><function>sd_bus_open_user()</function> and the other + functions described here are available as a shared library, which + can be compiled and linked to with the + <constant>libsystemd</constant> <citerefentry + project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para> </refsect1> |