systemd/man/sd_bus_set_description.xml
Luca Boccassi 48e5ef14af man: correct return value of sd_bus_open_with_description
Since f4b2933ee7
if a description is not set, sd_bus_open_with_description returns -ENXIO, but the
documnetation stated that it returned successfully with a NULL string.
2021-07-06 15:18:35 +02:00

250 lines
11 KiB
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">
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="http://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.</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></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></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<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>