path: root/man/sd_bus_set_description.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->

<refentry id="sd_bus_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sd_bus_set_description</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_bus_set_description</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_bus_set_description</refname>
    <refname>sd_bus_get_description</refname>
    <refname>sd_bus_set_anonymous</refname>
    <refname>sd_bus_is_anonymous</refname>
    <refname>sd_bus_set_trusted</refname>
    <refname>sd_bus_is_trusted</refname>
    <refname>sd_bus_set_allow_interactive_authorization</refname>
    <refname>sd_bus_get_allow_interactive_authorization</refname>
    <refname>sd_bus_get_scope</refname>
    <refname>sd_bus_get_tid</refname>
    <refname>sd_bus_get_unique_name</refname>

    <refpurpose>Set or query properties of a bus object</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_bus_set_description</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>const char *<parameter>description</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_get_description</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>const char **<parameter>description</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_set_anonymous</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>int <parameter>b</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_is_anonymous</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_set_trusted</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>int <parameter>b</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_is_trusted</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>int <parameter>b</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_get_scope</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>const char **<parameter>scope</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_get_tid</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>pid_t *<parameter>tid</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>int <function>sd_bus_get_unique_name</function></funcdef>
        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
        <paramdef>const char **<parameter>unique</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><function>sd_bus_set_description()</function> sets the description string that is used in
    logging to the specified string. The string is copied internally and freed when the bus object
    is deallocated. The <parameter>description</parameter> argument may be
    <constant>NULL</constant>, in which case the description is unset. This function must be called
    before the bus is started.</para>

    <para><function>sd_bus_get_description()</function> returns a description string in
    <parameter>description</parameter>. This string may have been previously set with
    <function>sd_bus_set_description()</function> or
    <citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    or similar. If not set this way, a default string like <literal>system</literal> or
    <literal>user</literal> will be returned for the system or user buses, and
    <constant>-ENXIO</constant> otherwise.</para>

    <para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous authentication",
    i.e. lack of authentication, of the bus peer. This function must be called before the bus is
    started. See the
    <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">
    D-Bus Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>

    <para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows
    anonymous authentication (in the sense described in previous paragraph).</para>

    <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the
    <parameter>bus</parameter> object. If true, all connections on the bus are trusted and access to
    all privileged and unprivileged methods is granted. This function must be called before the bus
    is started.</para>

    <para><function>sd_bus_is_trusted()</function> returns true if the bus connection is trusted (in
    the sense described in previous paragraph).</para>

    <para><function>sd_bus_set_allow_interactive_authorization()</function> enables or disables
    interactive authorization for method calls. If true, messages are marked with the
    <constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the
    <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus</ulink>
    specification, informing the receiving side that the caller is prepared to wait for interactive
    authorization, which might take a considerable time to complete. If this flag is set, the user
    may be queried for passwords or confirmation via
    <ulink url="https://www.freedesktop.org/wiki/Software/polkit">polkit</ulink> or a similar
    framework.</para>

    <para><function>sd_bus_get_allow_interactive_authorization()</function> returns true if
    interactive authorization is allowed and false if not.</para>

    <para><function>sd_bus_get_scope()</function> stores the scope of the given bus object in
    <parameter>scope</parameter>. The scope of the system bus is <literal>system</literal>. The
    scope of a user session bus is <literal>user</literal>. If the given bus object is not the
    system or a user session bus, <function>sd_bus_get_scope()</function> returns an error.</para>

    <para><function>sd_bus_get_tid()</function> stores the kernel thread id of the thread associated
    with the given bus object in <parameter>tid</parameter>. If <parameter>bus</parameter> is a
    default bus object obtained by calling one of the functions of the
    <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    family of functions, it stores the thread id of the thread the bus object was created in.
    Otherwise, if the bus object is attached to an event loop, it stores the thread id of the
    thread the event loop object was created in. If <parameter>bus</parameter> is not a default bus
    object and is not attached to an event loop, <function>sd_bus_get_tid()</function> returns an
    error.</para>

    <para><function>sd_bus_get_unique_name()</function> stores the unique name of the bus object on
    the bus in <parameter>unique</parameter>. See
    <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">
    The D-Bus specification</ulink> for more information on bus names. Note that the caller does not
    own the string stored in <parameter>unique</parameter> and should not free it.</para>
  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, these functions return a non-negative integer. On failure, they return a
    negative errno-style error code.</para>

    <refsect2>
      <title>Errors</title>

      <para>Returned errors may indicate the following problems:</para>

      <variablelist>
        <varlistentry>
          <term><constant>-EINVAL</constant></term>

          <listitem><para>An argument is invalid.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENOPKG</constant></term>

          <listitem><para>The bus cannot be resolved.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-EPERM</constant></term>

          <listitem><para>The bus has already been started.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ECHILD</constant></term>

          <listitem><para>The bus was created in a different process, library or module instance.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENOMEM</constant></term>

          <listitem><para>Memory allocation failed.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENODATA</constant></term>

          <listitem><para>The bus object passed to <function>sd_bus_get_scope()</function> was not a
          system or user session bus.</para>

          <xi:include href="version-info.xml" xpointer="v246"/></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENXIO</constant></term>

          <listitem><para>The bus object passed to <function>sd_bus_get_tid()</function> was not a
          default bus object and is not attached to an event loop.</para>

          <para>The bus object passed to <function>sd_bus_get_description()</function> did
          not have a <parameter>description</parameter>.</para>

          <xi:include href="version-info.xml" xpointer="v246"/></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <refsect1>
    <title>History</title>
    <para><function>sd_bus_set_description()</function>,
    <function>sd_bus_get_description()</function>,
    <function>sd_bus_set_anonymous()</function>,
    <function>sd_bus_set_trusted()</function>,
    <function>sd_bus_set_allow_interactive_authorization()</function>, and
    <function>sd_bus_get_allow_interactive_authorization()</function> were added in version 240.</para>
    <para><function>sd_bus_is_anonymous()</function>,
    <function>sd_bus_is_trusted()</function>,
    <function>sd_bus_get_scope()</function>,
    <function>sd_bus_get_tid()</function>, and
    <function>sd_bus_get_unique_name()</function> were added in version 246.</para>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>