systemd/man/sd_bus_set_description.xml
Zbigniew Jędrzejewski-Szmek c8cd6d7bab man: use meaningful titles for <ulink>s
As pointed out in https://github.com/systemd/systemd/issues/29814, we need to
use phrases are are meaningful on their own, because the man page formatter
creates a list at the bottom. With <ulink>see docs</ulink>, we end up with:
  NOTES:
    1. see docs
       https://some.url/page
    2. see docs
       https://some.url/page2
which is not very useful :(

Also, the text inside the tag should not include punctuation.

Python helper:
  from xml_helper import xml_parse
  for p in glob.glob('../man/*.xml'):
       t = xml_parse(p)
       ulinks = t.iterfind('.//ulink')
       for ulink in ulinks:
           if ulink.text is None: continue
           text = ' '.join(ulink.text.split())
           print(f'{p}: {text}')
2023-11-06 20:16:34 +01:00

269 lines
12 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">
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>