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
 169     the system bus on the specified <parameter>host</parameter> using
 170     <citerefentry
 171     project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter>
 172     consists of an optional user name followed by the
 173     <literal>@</literal> symbol, and the hostname.
 174     </para>
 175
 176     <para><function>sd_bus_open_system_machine()</function> connects
 177     to the system bus in the specified <parameter>machine</parameter>,
 178     where <parameter>machine</parameter> is the name of a local
 179     container.  See
 180     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 181     for more information about the "machine" concept. Note that
 182     connections into local containers are only available to privileged
 183     processes at this time.</para>
 184
 185     <para>These calls allocate a bus connection object and initiate
 186     the connection to a well-known bus of some form. An alternative to
 187     using these high-level calls is to create an unconnected bus
 188     object with
 189     <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 190     and to connect it with
 191     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 192     </para>
 193
 194   </refsect1>
 195
 196   <refsect1>
 197     <title>Reference ownership</title>
 198     <para>The functions <function>sd_bus_open()</function>,
 199     <function>sd_bus_open_user()</function>,
 200     <function>sd_bus_open_system()</function>,
 201     <function>sd_bus_open_system_remote()</function>, and
 202     <function>sd_bus_open_system_machine()</function> return a new
 203     connection object and the caller owns the sole reference. When not
 204     needed anymore, this reference should be destroyed with
 205     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 206     </para>
 207
 208     <para>The functions <function>sd_bus_default()</function>,
 209     <function>sd_bus_default_user()</function> and
 210     <function>sd_bus_default_system()</function> do not necessarily
 211     create a new object, but increase the connection reference of an
 212     existing connection object by one. Use
 213     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 214     to drop the reference.</para>
 215
 216     <para>Queued but unwritten/unread messages also keep a reference
 217     to their bus connection object. For this reason, even if an
 218     application dropped all references to a bus connection, it might
 219     not get destroyed right away. Until all incoming queued
 220     messages are read, and until all outgoing unwritten messages are
 221     written, the bus object will stay
 222     alive. <function>sd_bus_flush()</function> may be used to write
 223     all outgoing queued messages so they drop their references. To
 224     flush the unread incoming messages, use
 225     <function>sd_bus_close()</function>, which will also close the bus
 226     connection. When using the default bus logic, it is a good idea to
 227     first invoke <function>sd_bus_flush()</function> followed by
 228     <function>sd_bus_close()</function> when a thread or process
 229     terminates, and thus its bus connection object should be
 230     freed.</para>
 231
 232     <para>The life cycle of the default bus connection should be the
 233     responsibility of the code that creates/owns the thread the
 234     default bus connection object is associated with. Library code
 235     should neither call <function>sd_bus_flush()</function> nor
 236     <function>sd_bus_close()</function> on default bus objects unless
 237     it does so in its own private, self-allocated thread. Library code
 238     should not use the default bus object in other threads unless it
 239     is clear that the program using it will life cycle the bus
 240     connection object and flush and close it before exiting from the
 241     thread. In libraries where it is not clear that the calling
 242     program will life cycle the bus connection object, it is hence
 243     recommended to use <function>sd_bus_open_system()</function>
 244     instead of <function>sd_bus_default_system()</function> and
 245     related calls.</para>
 246   </refsect1>
 247
 248   <refsect1>
 249     <title>Return Value</title>
 250
 251     <para>On success, these calls return 0 or a positive
 252     integer. On failure, these calls return a negative
 253     errno-style error code.</para>
 254   </refsect1>
 255
 256   <refsect1>
 257     <title>Errors</title>
 258
 259     <para>Returned errors may indicate the following problems:</para>
 260
 261     <variablelist>
 262
 263       <varlistentry>
 264         <term><constant>-EINVAL</constant></term>
 265
 266         <listitem><para>The specified parameters are invalid.</para></listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term><constant>-ENOMEM</constant></term>
 271
 272         <listitem><para>Memory allocation failed.</para></listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><constant>-ESOCKTNOSUPPORT</constant></term>
 277
 278         <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem>
 279       </varlistentry>
 280     </variablelist>
 281
 282     <para>In addition, any further connection-related errors may be
 283     by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 284   </refsect1>
 285
 286   <refsect1>
 287     <title>Notes</title>
 288
 289     <para><function>sd_bus_open_user()</function> and the other
 290     functions described here are available as a shared library, which
 291     can be compiled and linked to with the
 292     <constant>libelogind</constant> <citerefentry
 293     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 294     file.</para>
 295   </refsect1>
 296
 297   <refsect1>
 298     <title>See Also</title>
 299
 300     <para>
 301       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 302       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 303       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 304       <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 305       <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 306       <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 308       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 309     </para>
 310   </refsect1>
 311
 312 </refentry>