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+ -->
   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
  28     <refpurpose>Set or query properties of a bus object</refpurpose>
  29   </refnamediv>
  30
  31   <refsynopsisdiv>
  32     <funcsynopsis>
  33       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  34
  35       <funcprototype>
  36         <funcdef>int <function>sd_bus_set_description</function></funcdef>
  37         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  38         <paramdef>const char *<parameter>description</parameter></paramdef>
  39       </funcprototype>
  40
  41       <funcprototype>
  42         <funcdef>int <function>sd_bus_get_description</function></funcdef>
  43         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  44         <paramdef>const char **<parameter>description</parameter></paramdef>
  45       </funcprototype>
  46
  47       <funcprototype>
  48         <funcdef>int <function>sd_bus_set_anonymous</function></funcdef>
  49         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  50         <paramdef>int <parameter>b</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>int <function>sd_bus_is_anonymous</function></funcdef>
  55         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  56       </funcprototype>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_bus_set_trusted</function></funcdef>
  60         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  61         <paramdef>int <parameter>b</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_bus_is_trusted</function></funcdef>
  66         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  67       </funcprototype>
  68
  69       <funcprototype>
  70         <funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef>
  71         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  72         <paramdef>int <parameter>b</parameter></paramdef>
  73       </funcprototype>
  74
  75       <funcprototype>
  76         <funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef>
  77         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  78       </funcprototype>
  79     </funcsynopsis>
  80   </refsynopsisdiv>
  81
  82   <refsect1>
  83     <title>Description</title>
  84
  85     <para><function>sd_bus_set_description()</function> sets the description string that is used in
  86     logging to the specified string. The string is copied internally and freed when the bus object
  87     is deallocated. The <parameter>description</parameter> argument may be
  88     <constant>NULL</constant>, in which case the description is unset. This function must be called
  89     before the bus is started.</para>
  90
  91     <para><function>sd_bus_get_description()</function> returns a description string in
  92     <parameter>description</parameter>. This string may have been previously set with
  93     <function>sd_bus_set_description()</function> or
  94     <citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  95     or similar. If not set this way, a default string like <literal>system</literal> or
  96     <literal>user</literal> will be returned for the system or user buses, and
  97     <constant>NULL</constant> otherwise.</para>
  98
  99     <para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous authentication",
 100     i.e. lack of authentication, of the bus peer. This function must be called before the bus is
 101     started. See the
 102     <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">
 103     Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
 104
 105     <para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows
 106     anonymous authentication (in the sense described in previous paragraph).</para>
 107
 108     <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the
 109     <parameter>bus</parameter> object. If true, all connections on the bus are trusted and access to
 110     all privileged and unprivileged methods is granted. This function must be called before the bus
 111     is started.</para>
 112
 113     <para><function>sd_bus_is_trusted()</function> returns true if the bus connection is trusted (in
 114     the sense described in previous paragraph).</para>
 115
 116     <para><function>sd_bus_set_allow_interactive_authorization()</function> enables or disables
 117     interactive authorization for method calls. If true, messages are marked with the
 118     <constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the
 119     <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus</ulink>
 120     specification, informing the receiving side that the caller is prepared to wait for interactive
 121     authorization, which might take a considerable time to complete. If this flag is set, the user
 122     may be queried for passwords or confirmation via
 123     <ulink url="http://www.freedesktop.org/wiki/Software/polkit">polkit</ulink> or a similar
 124     framework.</para>
 125
 126     <para><function>sd_bus_get_allow_interactive_authorization()</function> returns true if
 127     interactive authorization is allowed and false if not.</para>
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Return Value</title>
 132
 133     <para>On success, these functions return a non-negative integer. On failure, they return a
 134     negative errno-style error code.</para>
 135
 136     <refsect2>
 137       <title>Errors</title>
 138
 139       <para>Returned errors may indicate the following problems:</para>
 140
 141       <variablelist>
 142         <varlistentry>
 143           <term><constant>-EINVAL</constant></term>
 144
 145           <listitem><para>An argument is invalid.</para></listitem>
 146         </varlistentry>
 147
 148         <varlistentry>
 149           <term><constant>-ENOPKG</constant></term>
 150
 151           <listitem><para>The bus cannot be resolved.</para></listitem>
 152         </varlistentry>
 153
 154         <varlistentry>
 155           <term><constant>-EPERM</constant></term>
 156
 157           <listitem><para>The bus has already been started.</para></listitem>
 158         </varlistentry>
 159
 160         <varlistentry>
 161           <term><constant>-ECHILD</constant></term>
 162
 163           <listitem><para>The bus was created in a different process.</para></listitem>
 164         </varlistentry>
 165
 166         <varlistentry>
 167           <term><constant>-ENOMEM</constant></term>
 168
 169           <listitem><para>Memory allocation failed.</para></listitem>
 170         </varlistentry>
 171       </variablelist>
 172
 173     </refsect2>
 174   </refsect1>
 175
 176   <xi:include href="libsystemd-pkgconfig.xml" />
 177
 178   <refsect1>
 179     <title>See Also</title>
 180
 181     <para>
 182       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 187       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 188     </para>
 189   </refsect1>
 190
 191 </refentry>