man/sd_bus_open_user.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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_open_user" conditional="ENABLE_KDBUS">
  25
  26   <refentryinfo>
  27     <title>sd_bus_open_user</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_open_user</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_bus_open_user</refname>
  47     <refname>sd_bus_open_system</refname>
  48     <refname>sd_bus_open_system_remote</refname>
  49     <refname>sd_bus_open_system_container</refname>
  50
  51     <refname>sd_bus_default_user</refname>
  52     <refname>sd_bus_default_system</refname>
  53
  54     <refpurpose>Open a connection to the system or user bus</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_bus_open_user</function></funcdef>
  63         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_bus_open_system</function></funcdef>
  68         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_bus_open_system_remote</function></funcdef>
  73         <paramdef>const char *<parameter>host</parameter></paramdef>
  74         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_bus_open_system_container</function></funcdef>
  79         <paramdef>const char *<parameter>machine</parameter></paramdef>
  80         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_bus_default_user</function></funcdef>
  85         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  86       </funcprototype>
  87
  88       <funcprototype>
  89         <funcdef>int <function>sd_bus_default_system</function></funcdef>
  90         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  91       </funcprototype>
  92     </funcsynopsis>
  93   </refsynopsisdiv>
  94
  95   <refsect1>
  96     <title>Description</title>
  97
  98     <para><function>sd_bus_open_user()</function> creates a new bus
  99     object and opens a connection to the user bus.
 100     <function>sd_bus_open_system()</function> does the same, but
 101     connects to the system bus.</para>
 102
 103     <para>If the <varname>$DBUS_SESSION_BUS_ADDRESS</varname> environment
 104     variable is set
 105     (cf. <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
 106     it will be used as the address of the user bus. This variable can
 107     contain multiple addresses separated by <literal>;</literal>. If
 108     this variable is not set, a suitable default for the default user
 109     D-Bus instance will be used.</para>
 110
 111     <para>If the <varname>$DBUS_SYSTEM_BUS_ADDRESS</varname> environment
 112     variable is set, it will be used as the address of the system
 113     bus. This variable uses the same syntax as
 114     <varname>$DBUS_SESSION_BUS_ADDRESS</varname>/. If this variable is
 115     not set, a suitable default for the default system D-Bus instance
 116     will be used.</para>
 117
 118     <para><function>sd_bus_open_system_remote()</function> connects to
 119     the system bus on the specified <parameter>host</parameter> using
 120     SSH. <parameter>host</parameter> consists of an optional user name
 121     followed by the <literal>@</literal> symbol, and the hostname.
 122     </para>
 123
 124     <para><function>sd_bus_open_system_remote()</function> connects to
 125     the system bus in the specified <parameter>machine</parameter>,
 126     where <parameter>machine</parameter> is the name of a container.
 127     See
 128     <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 129     for more information about "machines".</para>
 130
 131     <para><function>sd_bus_default_user()</function> returns a bus
 132     object connected to the user bus. Each thread has its own object, but it
 133     may be passed around. It is created on the first invocation of
 134     <function>sd_bus_default_user()</function>, and subsequent
 135     invocations returns a reference to the same object.</para>
 136
 137     <para><function>sd_bus_default_system()</function> is similar to
 138     <function>sd_bus_default_user()</function>, but connects to the
 139     system bus.</para>
 140   </refsect1>
 141
 142   <refsect1>
 143     <title>Return Value</title>
 144
 145     <para>On success, these calls return 0 or a positive
 146     integer. On failure, these calls return a negative
 147     errno-style error code.</para>
 148   </refsect1>
 149
 150   <refsect1>
 151     <title>Reference ownership</title>
 152     <para>Functions <function>sd_bus_open_user()</function>,
 153     <function>sd_bus_open_system()</function>,
 154     <function>sd_bus_open_system_remote()</function>, and
 155     <function>sd_bus_open_system_machine()</function> return a new
 156     object and the caller owns the sole reference. When not needed
 157     anymore, this reference should be destroyed with
 158     <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 159     </para>
 160
 161     <para>The functions <function>sd_bus_default_user()</function> and
 162     <function>sd_bus_default_system()</function> do not create a new
 163     reference.</para>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>Errors</title>
 168
 169     <para>Returned errors may indicate the following problems:</para>
 170
 171     <variablelist>
 172
 173       <varlistentry>
 174         <term><varname>-EINVAL</varname></term>
 175
 176         <listitem><para>Specified parameter is invalid
 177         (<constant>NULL</constant> in case of output
 178         parameters).</para></listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><varname>-ENOMEM</varname></term>
 183
 184         <listitem><para>Memory allocation failed.</para></listitem>
 185       </varlistentry>
 186
 187       <para>In addition, any further connection-related errors may be
 188       by returned. See <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 189     </variablelist>
 190   </refsect1>
 191
 192   <refsect1>
 193     <title>Notes</title>
 194
 195     <para><function>sd_bus_open_user()</function> and other functions
 196     described here are available as a shared library, which can be
 197     compiled and linked to with the
 198     <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 199     file.</para>
 200   </refsect1>
 201
 202   <refsect1>
 203     <title>See Also</title>
 204
 205     <para>
 206       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 207       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>sd_bus_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 210       <citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 213       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 214     </para>
 215   </refsect1>
 216
 217 </refentry>