man/sd_bus_set_description.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_set_description</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_set_description</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_set_description</refname>
  20     <refname>sd_bus_get_description</refname>
  21     <refname>sd_bus_set_anonymous</refname>
  22     <refname>sd_bus_is_anonymous</refname>
  23     <refname>sd_bus_set_trusted</refname>
  24     <refname>sd_bus_is_trusted</refname>
  25     <refname>sd_bus_set_allow_interactive_authorization</refname>
  26     <refname>sd_bus_get_allow_interactive_authorization</refname>
  27     <refname>sd_bus_get_scope</refname>
  28     <refname>sd_bus_get_tid</refname>
  29     <refname>sd_bus_get_unique_name</refname>
  30
  31     <refpurpose>Set or query properties of a bus object</refpurpose>
  32   </refnamediv>
  33
  34   <refsynopsisdiv>
  35     <funcsynopsis>
  36       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  37
  38       <funcprototype>
  39         <funcdef>int <function>sd_bus_set_description</function></funcdef>
  40         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  41         <paramdef>const char *<parameter>description</parameter></paramdef>
  42       </funcprototype>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_bus_get_description</function></funcdef>
  46         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  47         <paramdef>const char **<parameter>description</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_bus_set_anonymous</function></funcdef>
  52         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  53         <paramdef>int <parameter>b</parameter></paramdef>
  54       </funcprototype>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_bus_is_anonymous</function></funcdef>
  58         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_bus_set_trusted</function></funcdef>
  63         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  64         <paramdef>int <parameter>b</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_bus_is_trusted</function></funcdef>
  69         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef>
  74         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  75         <paramdef>int <parameter>b</parameter></paramdef>
  76       </funcprototype>
  77
  78       <funcprototype>
  79         <funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef>
  80         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_bus_get_scope</function></funcdef>
  85         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  86         <paramdef>const char **<parameter>scope</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_bus_get_tid</function></funcdef>
  91         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  92         <paramdef>pid_t *<parameter>tid</parameter></paramdef>
  93       </funcprototype>
  94
  95       <funcprototype>
  96         <funcdef>int <function>sd_bus_get_unique_name</function></funcdef>
  97         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  98         <paramdef>const char **<parameter>unique</parameter></paramdef>
  99       </funcprototype>
 100     </funcsynopsis>
 101   </refsynopsisdiv>
 102
 103   <refsect1>
 104     <title>Description</title>
 105
 106     <para><function>sd_bus_set_description()</function> sets the description string that is used in
 107     logging to the specified string. The string is copied internally and freed when the bus object
 108     is deallocated. The <parameter>description</parameter> argument may be
 109     <constant>NULL</constant>, in which case the description is unset. This function must be called
 110     before the bus is started.</para>
 111
 112     <para><function>sd_bus_get_description()</function> returns a description string in
 113     <parameter>description</parameter>. This string may have been previously set with
 114     <function>sd_bus_set_description()</function> or
 115     <citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 116     or similar. If not set this way, a default string like <literal>system</literal> or
 117     <literal>user</literal> will be returned for the system or user buses, and
 118     <constant>-ENXIO</constant> otherwise.</para>
 119
 120     <para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous authentication",
 121     i.e. lack of authentication, of the bus peer. This function must be called before the bus is
 122     started. See the
 123     <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">
 124     D-Bus Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
 125
 126     <para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows
 127     anonymous authentication (in the sense described in previous paragraph).</para>
 128
 129     <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the
 130     <parameter>bus</parameter> object. If true, all connections on the bus are trusted and access to
 131     all privileged and unprivileged methods is granted. This function must be called before the bus
 132     is started.</para>
 133
 134     <para><function>sd_bus_is_trusted()</function> returns true if the bus connection is trusted (in
 135     the sense described in previous paragraph).</para>
 136
 137     <para><function>sd_bus_set_allow_interactive_authorization()</function> enables or disables
 138     interactive authorization for method calls. If true, messages are marked with the
 139     <constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the
 140     <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus</ulink>
 141     specification, informing the receiving side that the caller is prepared to wait for interactive
 142     authorization, which might take a considerable time to complete. If this flag is set, the user
 143     may be queried for passwords or confirmation via
 144     <ulink url="https://www.freedesktop.org/wiki/Software/polkit">polkit</ulink> or a similar
 145     framework.</para>
 146
 147     <para><function>sd_bus_get_allow_interactive_authorization()</function> returns true if
 148     interactive authorization is allowed and false if not.</para>
 149
 150     <para><function>sd_bus_get_scope()</function> stores the scope of the given bus object in
 151     <parameter>scope</parameter>. The scope of the system bus is <literal>system</literal>. The
 152     scope of a user session bus is <literal>user</literal>. If the given bus object is not the
 153     system or a user session bus, <function>sd_bus_get_scope()</function> returns an error.</para>
 154
 155     <para><function>sd_bus_get_tid()</function> stores the kernel thread id of the thread associated
 156     with the given bus object in <parameter>tid</parameter>. If <parameter>bus</parameter> is a
 157     default bus object obtained by calling one of the functions of the
 158     <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 159     family of functions, it stores the thread id of the thread the bus object was created in.
 160     Otherwise, if the bus object is attached to an event loop, it stores the thread id of the
 161     thread the event loop object was created in. If <parameter>bus</parameter> is not a default bus
 162     object and is not attached to an event loop, <function>sd_bus_get_tid()</function> returns an
 163     error.</para>
 164
 165     <para><function>sd_bus_get_unique_name()</function> stores the unique name of the bus object on
 166     the bus in <parameter>unique</parameter>. See
 167     <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">
 168     The D-Bus specification</ulink> for more information on bus names. Note that the caller does not
 169     own the string stored in <parameter>unique</parameter> and should not free it.</para>
 170   </refsect1>
 171
 172   <refsect1>
 173     <title>Return Value</title>
 174
 175     <para>On success, these functions return a non-negative integer. On failure, they return a
 176     negative errno-style error code.</para>
 177
 178     <refsect2>
 179       <title>Errors</title>
 180
 181       <para>Returned errors may indicate the following problems:</para>
 182
 183       <variablelist>
 184         <varlistentry>
 185           <term><constant>-EINVAL</constant></term>
 186
 187           <listitem><para>An argument is invalid.</para></listitem>
 188         </varlistentry>
 189
 190         <varlistentry>
 191           <term><constant>-ENOPKG</constant></term>
 192
 193           <listitem><para>The bus cannot be resolved.</para></listitem>
 194         </varlistentry>
 195
 196         <varlistentry>
 197           <term><constant>-EPERM</constant></term>
 198
 199           <listitem><para>The bus has already been started.</para></listitem>
 200         </varlistentry>
 201
 202         <varlistentry>
 203           <term><constant>-ECHILD</constant></term>
 204
 205           <listitem><para>The bus was created in a different process, library or module instance.</para></listitem>
 206         </varlistentry>
 207
 208         <varlistentry>
 209           <term><constant>-ENOMEM</constant></term>
 210
 211           <listitem><para>Memory allocation failed.</para></listitem>
 212         </varlistentry>
 213
 214         <varlistentry>
 215           <term><constant>-ENODATA</constant></term>
 216
 217           <listitem><para>The bus object passed to <function>sd_bus_get_scope()</function> was not a
 218           system or user session bus.</para>
 219
 220           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 221         </varlistentry>
 222
 223         <varlistentry>
 224           <term><constant>-ENXIO</constant></term>
 225
 226           <listitem><para>The bus object passed to <function>sd_bus_get_tid()</function> was not a
 227           default bus object and is not attached to an event loop.</para>
 228
 229           <para>The bus object passed to <function>sd_bus_get_description()</function> did
 230           not have a <parameter>description</parameter>.</para>
 231
 232           <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 233         </varlistentry>
 234       </variablelist>
 235     </refsect2>
 236   </refsect1>
 237
 238   <xi:include href="libsystemd-pkgconfig.xml" />
 239
 240   <refsect1>
 241     <title>History</title>
 242     <para><function>sd_bus_set_description()</function>,
 243     <function>sd_bus_get_description()</function>,
 244     <function>sd_bus_set_anonymous()</function>,
 245     <function>sd_bus_set_trusted()</function>,
 246     <function>sd_bus_set_allow_interactive_authorization()</function>, and
 247     <function>sd_bus_get_allow_interactive_authorization()</function> were added in version 240.</para>
 248     <para><function>sd_bus_is_anonymous()</function>,
 249     <function>sd_bus_is_trusted()</function>,
 250     <function>sd_bus_get_scope()</function>,
 251     <function>sd_bus_get_tid()</function>, and
 252     <function>sd_bus_get_unique_name()</function> were added in version 246.</para>
 253   </refsect1>
 254
 255   <refsect1>
 256     <title>See Also</title>
 257
 258     <para>
 259       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 260       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 261       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 262       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 263       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 264       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 265     </para>
 266   </refsect1>
 267
 268 </refentry>