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     to the calling thread. Each time the function is invoked from the
 115     same thread the same object is returned, but its reference count
 116     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 or otherwise the connection will
 124     be leaked.</para>
 125
 126     <para><function>sd_bus_default_user()</function> returns a user
 127     bus connection object associated to the calling thread.
 128     <function>sd_bus_default_system()</function> is similar, but
 129     connects to the system bus. Note that
 130     <function>sd_bus_default()</function> is identical to these two
 131     calls, depending on the execution context.</para>
 132
 133     <para><function>sd_bus_open()</function> creates a new,
 134     independent bus connection to the user bus when invoked in user
 135     context, or the system bus
 136     otherwise. <function>sd_bus_open_user()</function> is similar, but
 137     connects only to the user bus.
 138     <function>sd_bus_open_system()</function> does the same, but
 139     connects to the system bus. In contrast to
 140     <function>sd_bus_default()</function>,
 141     <function>sd_bus_default_user()</function>,
 142     <function>sd_bus_default_system()</function> these calls return
 143     new, independent connection objects that are not associated with
 144     the invoking thread and are not shared between multiple
 145     invocations. It is recommended to share connections per thread to
 146     efficiently make use the available resources. Thus, it is
 147     recommended to use <function>sd_bus_default()</function>,
 148     <function>sd_bus_default_user()</function>,
 149     <function>sd_bus_default_system()</function> to connect to the
 150     user or system buses.</para>
 151
 152     <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
 153     variable is set
 154     (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 155     it will be used as the address of the user bus. This variable can
 156     contain multiple addresses separated by <literal>;</literal>. If
 157     this variable is not set, a suitable default for the default user
 158     D-Bus instance will be used.</para>
 159
 160     <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname>
 161     environment variable is set, it will be used as the address of the
 162     system bus. This variable uses the same syntax as
 163     <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is
 164     not set, a suitable default for the default system D-Bus instance
 165     will be used.</para>
 166
 167     <para><function>sd_bus_open_system_remote()</function> connects to
 168     the system bus on the specified <parameter>host</parameter> using
 169     <citerefentry
 170     project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter>
 171     consists of an optional user name followed by the
 172     <literal>@</literal> symbol, and the hostname.
 173     </para>
 174
 175     <para><function>sd_bus_open_system_machine()</function> connects
 176     to the system bus in the specified <parameter>machine</parameter>,
 177     where <parameter>machine</parameter> is the name of a local
 178     container.  See
 179     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 180     for more information about the "machine" concept. Note that
 181     connections into local containers are only available to privileged
 182     processes at this time.</para>
 183
 184     <para>These calls allocate a bus connection object and initiate
 185     the connection to a well-known bus of some form. An alternative to
 186     using these high-level calls is to create an unconnected bus
 187     object with
 188     <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     and to connect it with
 190     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 191     </para>
 192
 193   </refsect1>
 194
 195   <refsect1>
 196     <title>Return Value</title>
 197
 198     <para>On success, these calls return 0 or a positive
 199     integer. On failure, these calls return a negative
 200     errno-style error code.</para>
 201   </refsect1>
 202
 203   <refsect1>
 204     <title>Reference ownership</title>
 205     <para>The functions <function>sd_bus_open()</function>,
 206     <function>sd_bus_open_user()</function>,
 207     <function>sd_bus_open_system()</function>,
 208     <function>sd_bus_open_system_remote()</function>, and
 209     <function>sd_bus_open_system_machine()</function> return a new
 210     object and the caller owns the sole reference. When not needed
 211     anymore, this reference should be destroyed with
 212     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 213     </para>
 214
 215     <para>The functions <function>sd_bus_default()</function>,
 216     <function>sd_bus_default_user()</function> and
 217     <function>sd_bus_default_system()</function> do not necessarily
 218     create a new object, but increase the connection reference by
 219     one. Use
 220     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 221     to drop the reference.</para>
 222
 223     <para>Queued messages also keep a reference to the bus. For this reason, just
 224     because no application is having a reference to the bus does not mean that
 225     the bus object will be destroyed. Until all the messages are sent, the bus object
 226     will stay alive. <function>sd_bus_flush</function> can be used to send all the
 227     queued messages so they drop their references.</para>
 228   </refsect1>
 229
 230   <refsect1>
 231     <title>Errors</title>
 232
 233     <para>Returned errors may indicate the following problems:</para>
 234
 235     <variablelist>
 236
 237       <varlistentry>
 238         <term><constant>-EINVAL</constant></term>
 239
 240         <listitem><para>The specified parameters are invalid.</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><constant>-ENOMEM</constant></term>
 245
 246         <listitem><para>Memory allocation failed.</para></listitem>
 247       </varlistentry>
 248
 249       <varlistentry>
 250         <term><constant>-ESOCKTNOSUPPORT</constant></term>
 251
 252         <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem>
 253       </varlistentry>
 254     </variablelist>
 255
 256     <para>In addition, any further connection-related errors may be
 257     by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 258   </refsect1>
 259
 260   <refsect1>
 261     <title>Notes</title>
 262
 263     <para><function>sd_bus_open_user()</function> and the other
 264     functions described here are available as a shared library, which
 265     can be compiled and linked to with the
 266     <constant>libsystemd</constant> <citerefentry
 267     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 268     file.</para>
 269   </refsect1>
 270
 271   <refsect1>
 272     <title>See Also</title>
 273
 274     <para>
 275       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 276       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 277       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 278       <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 279       <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 280       <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 281       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 282       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 283     </para>
 284   </refsect1>
 285
 286 </refentry>