man/sd_bus_default.xml

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