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     increased by one, as long as at least one reference is kept. When
 117     the last reference to the connection is dropped (using the
 118     <function>sd_bus_unref()</function> call), the connection is
 119     terminated. Note that the connection is not automatically
 120     terminated when the associated thread ends. It is important to
 121     drop the last reference to the bus connection explicitly before
 122     the thread ends or otherwise the connection will be leaked.</para>
 123
 124     <para><function>sd_bus_default_user()</function> returns a user
 125     bus connection object associated to the calling thread.
 126     <function>sd_bus_default_system()</function> is similar, but
 127     connects to the system bus.</para>
 128
 129     <para><function>sd_bus_open()</function> creates a new,
 130     independent bus connection to the user bus when invoked in user
 131     context or the system bus
 132     otherwise. <function>sd_bus_open_user()</function> is similar, but
 133     connects only to the user bus.
 134     <function>sd_bus_open_system()</function> does the same, but
 135     connects to the system bus. In contrast to
 136     <function>sd_bus_default()</function>,
 137     <function>sd_bus_default_user()</function>,
 138     <function>sd_bus_default_system()</function> these calls return
 139     new, independent connection objects that are not associated with
 140     the invoking thread and are not shared between multiple
 141     invocations. It is recommended to share connections per thread to
 142     efficiently make use the available resources. Thus, it is
 143     recommended to use <function>sd_bus_default()</function>,
 144     <function>sd_bus_default_user()</function>,
 145     <function>sd_bus_default_system()</function> to connect to the
 146     user or system buses.</para>
 147
 148     <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
 149     variable is set
 150     (cf. <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 151     it will be used as the address of the user bus. This variable can
 152     contain multiple addresses separated by <literal>;</literal>. If
 153     this variable is not set, a suitable default for the default user
 154     D-Bus instance will be used.</para>
 155
 156     <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname>
 157     environment variable is set, it will be used as the address of the
 158     system bus. This variable uses the same syntax as
 159     <varname>$DBUS_SESSION_BUS_ADDRESS</varname>. If this variable is
 160     not set, a suitable default for the default system D-Bus instance
 161     will be used.</para>
 162
 163     <para><function>sd_bus_open_system_remote()</function> connects to
 164     the system bus on the specified <parameter>host</parameter> using
 165     SSH. <parameter>host</parameter> consists of an optional user name
 166     followed by the <literal>@</literal> symbol, and the hostname.
 167     </para>
 168
 169     <para><function>sd_bus_open_system_container()</function> connects
 170     to the system bus in the specified <parameter>machine</parameter>,
 171     where <parameter>machine</parameter> is the name of a local
 172     container.  See
 173     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 174     for more information about "machines".</para>
 175
 176   </refsect1>
 177
 178   <refsect1>
 179     <title>Return Value</title>
 180
 181     <para>On success, these calls return 0 or a positive
 182     integer. On failure, these calls return a negative
 183     errno-style error code.</para>
 184   </refsect1>
 185
 186   <refsect1>
 187     <title>Reference ownership</title>
 188     <para>The functions <function>sd_bus_open_user()</function>,
 189     <function>sd_bus_open()</function>,
 190     <function>sd_bus_open_system()</function>,
 191     <function>sd_bus_open_system_remote()</function>, and
 192     <function>sd_bus_open_system_machine()</function> return a new
 193     object and the caller owns the sole reference. When not needed
 194     anymore, this reference should be destroyed with
 195     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 196     </para>
 197
 198     <para>The functions <function>sd_bus_default()</function>,
 199     <function>sd_bus_default_user()</function> and
 200     <function>sd_bus_default_system()</function> do not necessarily
 201     create a new object, but increase the connection reference by
 202     one. Use
 203     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 204     to drop the reference.</para>
 205   </refsect1>
 206
 207   <refsect1>
 208     <title>Errors</title>
 209
 210     <para>Returned errors may indicate the following problems:</para>
 211
 212     <variablelist>
 213
 214       <varlistentry>
 215         <term><constant>-EINVAL</constant></term>
 216
 217         <listitem><para>The specified parameters are invalid.</para></listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term><constant>-ENOMEM</constant></term>
 222
 223         <listitem><para>Memory allocation failed.</para></listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><constant>-ESOCKTNOSUPPORT</constant></term>
 228
 229         <listitem><para>The protocol version required to connect to the selected bus is not supported.</para></listitem>
 230       </varlistentry>
 231     </variablelist>
 232
 233     <para>In addition, any further connection-related errors may be
 234     by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 235   </refsect1>
 236
 237   <refsect1>
 238     <title>Notes</title>
 239
 240     <para><function>sd_bus_open_user()</function> and the other
 241     functions described here are available as a shared library, which
 242     can be compiled and linked to with the
 243     <constant>libsystemd</constant> <citerefentry
 244     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 245     file.</para>
 246   </refsect1>
 247
 248   <refsect1>
 249     <title>See Also</title>
 250
 251     <para>
 252       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 253       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 257       <citerefentry project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 260     </para>
 261   </refsect1>
 262
 263 </refentry>