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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_bus_default" conditional="ENABLE_KDBUS">
  28
  29   <refentryinfo>
  30     <title>sd_bus_default</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>A monkey with a typewriter</contrib>
  36         <firstname>Zbigniew</firstname>
  37         <surname>Jędrzejewski-Szmek</surname>
  38         <email>zbyszek@in.waw.pl</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_bus_default</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_bus_default</refname>
  50     <refname>sd_bus_default_user</refname>
  51     <refname>sd_bus_default_system</refname>
  52
  53     <refname>sd_bus_open</refname>
  54     <refname>sd_bus_open_user</refname>
  55     <refname>sd_bus_open_system</refname>
  56     <refname>sd_bus_open_system_remote</refname>
  57     <refname>sd_bus_open_system_machine</refname>
  58
  59     <refpurpose>Acquire a connection to a system or user bus</refpurpose>
  60   </refnamediv>
  61
  62   <refsynopsisdiv>
  63     <funcsynopsis>
  64       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_bus_default</function></funcdef>
  68         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_bus_default_user</function></funcdef>
  73         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  74       </funcprototype>
  75
  76       <funcprototype>
  77         <funcdef>int <function>sd_bus_default_system</function></funcdef>
  78         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  79       </funcprototype>
  80
  81       <funcprototype>
  82         <funcdef>int <function>sd_bus_open</function></funcdef>
  83         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  84       </funcprototype>
  85
  86       <funcprototype>
  87         <funcdef>int <function>sd_bus_open_user</function></funcdef>
  88         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  89       </funcprototype>
  90
  91       <funcprototype>
  92         <funcdef>int <function>sd_bus_open_system</function></funcdef>
  93         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  94       </funcprototype>
  95
  96       <funcprototype>
  97         <funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
  98         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  99         <paramdef>const char *<parameter>host</parameter></paramdef>
 100       </funcprototype>
 101
 102       <funcprototype>
 103         <funcdef>int <function>sd_bus_open_system_machine</function></funcdef>
 104         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
 105         <paramdef>const char *<parameter>machine</parameter></paramdef>
 106       </funcprototype>
 107
 108     </funcsynopsis>
 109   </refsynopsisdiv>
 110
 111   <refsect1>
 112     <title>Description</title>
 113
 114     <para><function>sd_bus_default()</function> acquires a bus
 115     connection object to the user bus when invoked in user context or
 116     to the system bus otherwise. The connection object is associated
 117     to the calling thread. Each time the function is invoked from the
 118     same thread the same object is returned, but its reference count
 119     increased by one, as long as at least one reference is kept. When
 120     the last reference to the connection is dropped (using the
 121     <function>sd_bus_unref()</function> call), the connection is
 122     terminated. Note that the connection is not automatically
 123     terminated when the associated thread ends. It is important to
 124     drop the last reference to the bus connection explicitly before
 125     the thread ends or otherwise the connection will be leaked.</para>
 126
 127     <para><function>sd_bus_default_user()</function> returns a user
 128     bus connection object associated to the calling thread.
 129     <function>sd_bus_default_system()</function> is similar, but
 130     connects to the system bus.</para>
 131
 132     <para><function>sd_bus_open()</function> creates a new,
 133     independent bus connection to the user bus when invoked in user
 134     context or the system bus
 135     otherwise. <function>sd_bus_open_user()</function> is similar, but
 136     connects only to the user bus.
 137     <function>sd_bus_open_system()</function> does the same, but
 138     connects to the system bus. In contrast to
 139     <function>sd_bus_default()</function>,
 140     <function>sd_bus_default_user()</function>,
 141     <function>sd_bus_default_system()</function> these calls return
 142     new, independent connection objects that are not associated with
 143     the invoking thread and are not shared between multiple
 144     invocations. It is recommended to share connections per thread to
 145     efficiently make use the available resources. Thus, it is
 146     recommended to use <function>sd_bus_default()</function>,
 147     <function>sd_bus_default_user()</function>,
 148     <function>sd_bus_default_system()</function> to connect to the
 149     user or system buses.</para>
 150
 151     <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
 152     variable is set
 153     (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 154     it will be used as the address of the user bus. This variable can
 155     contain multiple addresses separated by <literal>;</literal>. If
 156     this variable is not set, a suitable default for the default user
 157     D-Bus instance will be used.</para>
 158
 159     <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname>
 160     environment variable is set, it will be used as the address of the
 161     system bus. This variable uses the same syntax as
 162     <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is
 163     not set, a suitable default for the default system D-Bus instance
 164     will be used.</para>
 165
 166     <para><function>sd_bus_open_system_remote()</function> connects to
 167     the system bus on the specified <parameter>host</parameter> using
 168     SSH. <parameter>host</parameter> consists of an optional user name
 169     followed by the <literal>@</literal> symbol, and the hostname.
 170     </para>
 171
 172     <para><function>sd_bus_open_system_container()</function> connects
 173     to the system bus in the specified <parameter>machine</parameter>,
 174     where <parameter>machine</parameter> is the name of a local
 175     container.  See
 176     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 177     for more information about "machines".</para>
 178
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>Return Value</title>
 183
 184     <para>On success, these calls return 0 or a positive
 185     integer. On failure, these calls return a negative
 186     errno-style error code.</para>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>Reference ownership</title>
 191     <para>The functions <function>sd_bus_open_user()</function>,
 192     <function>sd_bus_open()</function>,
 193     <function>sd_bus_open_system()</function>,
 194     <function>sd_bus_open_system_remote()</function>, and
 195     <function>sd_bus_open_system_machine()</function> return a new
 196     object and the caller owns the sole reference. When not needed
 197     anymore, this reference should be destroyed with
 198     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 199     </para>
 200
 201     <para>The functions <function>sd_bus_default()</function>,
 202     <function>sd_bus_default_user()</function> and
 203     <function>sd_bus_default_system()</function> do not necessarily
 204     create a new object, but increase the connection reference by
 205     one. Use
 206     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 207     to drop the reference.</para>
 208   </refsect1>
 209
 210   <refsect1>
 211     <title>Errors</title>
 212
 213     <para>Returned errors may indicate the following problems:</para>
 214
 215     <variablelist>
 216
 217       <varlistentry>
 218         <term><constant>-EINVAL</constant></term>
 219
 220         <listitem><para>The specified parameters are invalid.</para></listitem>
 221       </varlistentry>
 222
 223       <varlistentry>
 224         <term><constant>-ENOMEM</constant></term>
 225
 226         <listitem><para>Memory allocation failed.</para></listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term><constant>-ESOCKTNOSUPPORT</constant></term>
 231
 232         <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem>
 233       </varlistentry>
 234     </variablelist>
 235
 236     <para>In addition, any further connection-related errors may be
 237     by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>Notes</title>
 242
 243     <para><function>sd_bus_open_user()</function> and the other
 244     functions described here are available as a shared library, which
 245     can be compiled and linked to with the
 246     <constant>libsystemd</constant> <citerefentry
 247     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 248     file.</para>
 249   </refsect1>
 250
 251   <refsect1>
 252     <title>See Also</title>
 253
 254     <para>
 255       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 257       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 260       <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 261       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 262       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 263     </para>
 264   </refsect1>
 265
 266 </refentry>