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