man/sd_bus_default.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_default" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_default</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_default</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_default</refname>
  20     <refname>sd_bus_default_user</refname>
  21     <refname>sd_bus_default_system</refname>
  22
  23     <refname>sd_bus_open</refname>
  24     <refname>sd_bus_open_with_description</refname>
  25     <refname>sd_bus_open_user</refname>
  26     <refname>sd_bus_open_user_with_description</refname>
  27     <refname>sd_bus_open_user_machine</refname>
  28     <refname>sd_bus_open_system</refname>
  29     <refname>sd_bus_open_system_with_description</refname>
  30     <refname>sd_bus_open_system_remote</refname>
  31     <refname>sd_bus_open_system_machine</refname>
  32
  33     <refpurpose>Acquire a connection to a system or user bus</refpurpose>
  34   </refnamediv>
  35
  36   <refsynopsisdiv>
  37     <funcsynopsis>
  38       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  39
  40       <funcprototype>
  41         <funcdef>int <function>sd_bus_default</function></funcdef>
  42         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  43       </funcprototype>
  44
  45       <funcprototype>
  46         <funcdef>int <function>sd_bus_default_user</function></funcdef>
  47         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_bus_default_system</function></funcdef>
  52         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>int <function>sd_bus_open</function></funcdef>
  57         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_bus_open_with_description</function></funcdef>
  62         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  63         <paramdef>const char *<parameter>description</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_bus_open_user</function></funcdef>
  68         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_bus_open_user_with_description</function></funcdef>
  73         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  74         <paramdef>const char *<parameter>description</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_bus_open_user_machine</function></funcdef>
  79         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  80         <paramdef>const char *<parameter>machine</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_bus_open_system</function></funcdef>
  85         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  86       </funcprototype>
  87
  88       <funcprototype>
  89         <funcdef>int <function>sd_bus_open_system_with_description</function></funcdef>
  90         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  91         <paramdef>const char *<parameter>description</parameter></paramdef>
  92       </funcprototype>
  93
  94       <funcprototype>
  95         <funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
  96         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  97         <paramdef>const char *<parameter>host</parameter></paramdef>
  98       </funcprototype>
  99
 100       <funcprototype>
 101         <funcdef>int <function>sd_bus_open_system_machine</function></funcdef>
 102         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
 103         <paramdef>const char *<parameter>machine</parameter></paramdef>
 104       </funcprototype>
 105
 106     </funcsynopsis>
 107   </refsynopsisdiv>
 108
 109   <refsect1>
 110     <title>Description</title>
 111
 112     <para><function>sd_bus_default()</function> acquires a bus
 113     connection object to the user bus when invoked from within a user
 114     slice (any session under <literal>user-*.slice</literal>, e.g.:
 115     <literal>user@1000.service</literal>), or to the system bus
 116     otherwise. The connection object is associated with the calling
 117     thread. Each time the function is invoked from the same thread,
 118     the same object is returned, but its reference count is increased
 119     by one, as long as at least one reference is kept. When the last
 120     reference to the connection is dropped (using the
 121     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 122     call), the connection is terminated. Note that the connection is
 123     not automatically terminated when the associated thread ends. It
 124     is important to drop the last reference to the bus connection
 125     explicitly before the thread ends, as otherwise, the connection will
 126     leak. Also, queued but unread or unwritten messages keep the
 127     bus referenced, see below.</para>
 128
 129     <para><function>sd_bus_default_user()</function> returns a user
 130     bus connection object associated with the calling thread.
 131     <function>sd_bus_default_system()</function> is similar, but
 132     connects to the system bus. Note that
 133     <function>sd_bus_default()</function> is identical to these two
 134     calls, depending on the execution context.</para>
 135
 136     <para><function>sd_bus_open()</function> creates a new,
 137     independent bus connection to the user bus when invoked in user
 138     context, or the system bus
 139     otherwise. <function>sd_bus_open_user()</function> is similar, but
 140     connects only to the user bus.
 141     <function>sd_bus_open_system()</function> does the same, but
 142     connects to the system bus. In contrast to
 143     <function>sd_bus_default()</function>,
 144     <function>sd_bus_default_user()</function>, and
 145     <function>sd_bus_default_system()</function>, these calls return
 146     new, independent connection objects that are not associated with
 147     the invoking thread and are not shared between multiple
 148     invocations. It is recommended to share connections per thread to
 149     efficiently make use the available resources. Thus, it is
 150     recommended to use <function>sd_bus_default()</function>,
 151     <function>sd_bus_default_user()</function> and
 152     <function>sd_bus_default_system()</function> to connect to the
 153     user or system buses.</para>
 154
 155     <para><function>sd_bus_open_with_description()</function>,
 156     <function>sd_bus_open_user_with_description()</function>, and
 157     <function>sd_bus_open_system_with_description()</function> are similar to
 158     <function>sd_bus_open()</function>, <function>sd_bus_open_user()</function>, and
 159     <function>sd_bus_open_system()</function>, but allow a description string to be set, see
 160     <citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 161     <parameter>description</parameter> may be <constant>NULL</constant>, in which case this function
 162     is equivalent to <function>sd_bus_open()</function>. This description string is used in log
 163     messages about the bus object, and including a "name" for the bus makes them easier to
 164     understand. Some messages are emitted during bus initialization, hence using this function is
 165     preferable to setting the description later with
 166     <function>sd_bus_open_with_description()</function>. The argument is copied internally and will
 167     not be referenced after the function returns.</para>
 168
 169     <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
 170     variable is set
 171     (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 172     it will be used as the address of the user bus. This variable can
 173     contain multiple addresses separated by <literal>;</literal>. If
 174     this variable is not set, a suitable default for the default user
 175     D-Bus instance will be used.</para>
 176
 177     <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname>
 178     environment variable is set, it will be used as the address of the
 179     system bus. This variable uses the same syntax as
 180     <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is
 181     not set, a suitable default for the default system D-Bus instance
 182     will be used.</para>
 183
 184     <para><function>sd_bus_open_system_remote()</function> connects to the system bus on
 185     the specified host using
 186     <citerefentry project='man-pages'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 187     <parameter>host</parameter> consists of an optional user name followed by the
 188     <literal>@</literal> symbol, and the hostname, optionally followed by a
 189     <literal>:</literal> and a port, optionally followed by a
 190     <literal>/</literal> and a machine name. If the machine name is given, a connection
 191     is created to the system bus in the specified container on the remote machine, and
 192     otherwise a connection to the system bus on the specified host is created.</para>
 193
 194     <para>Note that entering a container is a privileged operation, and will likely only
 195     work for the root user on the remote machine.</para>
 196
 197     <para><function>sd_bus_open_system_machine()</function> connects to the system bus in the specified
 198     <parameter>machine</parameter>, where <parameter>machine</parameter> is the name of a local container,
 199     possibly prefixed by a user name and a separating <literal>@</literal>. If the container name is
 200     specified as the special string <literal>.host</literal> the connection is made to the local system. This
 201     is useful to connect to the local system bus as specific user, e.g. <literal>foobar@.host</literal> to
 202     connect to the local system bus as local user <literal>foobar</literal>. If the <literal>@</literal>
 203     syntax is used either the left-hand side or the right-hand side may be omitted (but not both) in which
 204     case the local user name or <literal>.host</literal> is implied. If the <literal>@</literal> syntax is
 205     not used the connection is always made as root user. See
 206     <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 207     for a description of the address syntax, and
 208     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for more
 209     information about the "machine" concept. Note that connections into local containers are only available
 210     to privileged processes at this time.</para>
 211
 212     <para><function>sd_bus_open_user_machine()</function> is similar to
 213     <function>sd_bus_open_system_machine()</function>, but connects to the user bus of the root user, or if
 214     the <literal>@</literal> syntax is used, of the specified user.</para>
 215
 216     <para>These calls allocate a bus connection object and initiate
 217     the connection to a well-known bus of some form. An alternative to
 218     using these high-level calls is to create an unconnected bus
 219     object with
 220     <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 221     and to connect it with
 222     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 223     </para>
 224
 225   </refsect1>
 226
 227   <refsect1>
 228     <title>Reference ownership</title>
 229     <para>The functions <function>sd_bus_open()</function>,
 230     <function>sd_bus_open_user()</function>,
 231     <function>sd_bus_open_user_machine()</function>,
 232     <function>sd_bus_open_system()</function>,
 233     <function>sd_bus_open_system_remote()</function>, and
 234     <function>sd_bus_open_system_machine()</function> return a new
 235     connection object and the caller owns the sole reference. When not
 236     needed anymore, this reference should be destroyed with
 237     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 238     </para>
 239
 240     <para>The functions <function>sd_bus_default()</function>,
 241     <function>sd_bus_default_user()</function> and
 242     <function>sd_bus_default_system()</function> do not necessarily
 243     create a new object, but increase the connection reference of an
 244     existing connection object by one. Use
 245     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 246     to drop the reference.</para>
 247
 248     <para>Queued but unwritten/unread messages keep a reference to their bus connection object. For this reason, even
 249     if an application dropped all references to a bus connection, it might not get destroyed right away. Until all
 250     incoming queued messages are read, and until all outgoing unwritten messages are written, the bus object will stay
 251     alive. <function>sd_bus_flush()</function> may be used to write all outgoing queued messages so they drop their
 252     references. To flush the unread incoming messages, use <function>sd_bus_close()</function>, which will also close
 253     the bus connection. When using the default bus logic, it is a good idea to first invoke
 254     <function>sd_bus_flush()</function> followed by <function>sd_bus_close()</function> when a thread or process
 255     terminates, and thus its bus connection object should be freed.</para>
 256
 257     <para>Normally, slot objects (as created by
 258     <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar
 259     calls) keep a reference to their bus connection object, too. Thus, as long as a bus slot object remains referenced
 260     its bus object will remain allocated too. Optionally, bus slot objects may be placed in "floating" mode. When in
 261     floating mode the life cycle of the bus slot object is bound to the bus object, i.e. when the bus object is freed
 262     the bus slot object is automatically unreferenced too. The floating state of a slot object may be controlled
 263     explicitly with
 264     <citerefentry><refentrytitle>sd_bus_slot_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 265     though usually floating bus slot objects are created by passing <constant>NULL</constant> as the
 266     <parameter>slot</parameter> parameter of <function>sd_bus_add_match()</function> and related calls, thus indicating
 267     that the caller is not directly interested in referencing and managing the bus slot object.</para>
 268
 269     <para>The life cycle of the default bus connection should be the
 270     responsibility of the code that creates/owns the thread the
 271     default bus connection object is associated with. Library code
 272     should neither call <function>sd_bus_flush()</function> nor
 273     <function>sd_bus_close()</function> on default bus objects unless
 274     it does so in its own private, self-allocated thread. Library code
 275     should not use the default bus object in other threads unless it
 276     is clear that the program using it will life cycle the bus
 277     connection object and flush and close it before exiting from the
 278     thread. In libraries where it is not clear that the calling
 279     program will life cycle the bus connection object, it is hence
 280     recommended to use <function>sd_bus_open_system()</function>
 281     instead of <function>sd_bus_default_system()</function> and
 282     related calls.</para>
 283   </refsect1>
 284
 285   <refsect1>
 286     <title>Return Value</title>
 287
 288     <para>On success, these calls return 0 or a positive
 289     integer. On failure, these calls return a negative
 290     errno-style error code.</para>
 291
 292     <refsect2>
 293       <title>Errors</title>
 294
 295       <para>Returned errors may indicate the following problems:</para>
 296
 297       <variablelist>
 298         <varlistentry>
 299           <term><constant>-EINVAL</constant></term>
 300
 301           <listitem><para>The specified parameters are invalid.</para></listitem>
 302         </varlistentry>
 303
 304         <varlistentry>
 305           <term><constant>-ENOMEDIUM</constant></term>
 306
 307           <listitem><para>The requested bus type is not available because of invalid environment (for example
 308           the user session bus is not available because <varname>$XDG_RUNTIME_DIR</varname> is not set).
 309           </para>
 310
 311           <xi:include href="version-info.xml" xpointer="v247"/></listitem>
 312         </varlistentry>
 313
 314         <varlistentry>
 315           <term><constant>-ENOMEM</constant></term>
 316
 317           <listitem><para>Memory allocation failed.</para></listitem>
 318         </varlistentry>
 319
 320         <varlistentry>
 321           <term><constant>-ESOCKTNOSUPPORT</constant></term>
 322
 323           <listitem><para>The protocol version required to connect to the selected bus is not
 324           supported.</para></listitem>
 325         </varlistentry>
 326       </variablelist>
 327
 328       <para>In addition, other connection-related errors may be returned. See
 329       <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 330     </refsect2>
 331   </refsect1>
 332
 333   <xi:include href="libsystemd-pkgconfig.xml" />
 334
 335   <refsect1>
 336     <title>See Also</title>
 337
 338     <para>
 339       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 340       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 341       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 342       <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 343       <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 344       <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 345       <citerefentry project='man-pages'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 346       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 347       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 348     </para>
 349   </refsect1>
 350
 351 </refentry>