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