X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_request_name.xml;h=6aa132bb2649caf2ae07fe4d97cab801d557eb7f;hb=5c3072eab6d2e11d89452987b017541d4654ac05;hp=e3a9266e4728b612c91d396cafb06aff426e3c1f;hpb=3b3d7d069d10d53336dbada1c67f739e3492b218;p=elogind.git

diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml
index e3a9266e4..6aa132bb2 100644
--- a/man/sd_bus_request_name.xml
+++ b/man/sd_bus_request_name.xml
@@ -1,6 +1,6 @@
 <?xml version='1.0'?> <!--*-nxml-*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
 <!--
   This file is part of systemd.
@@ -23,206 +23,188 @@
 
 <refentry id="sd_bus_request_name" conditional="ENABLE_KDBUS">
 
-        <refentryinfo>
-                <title>sd_bus_request_name</title>
-                <productname>systemd</productname>
-
-                <authorgroup>
-                        <author>
-                                <contrib>Developer</contrib>
-                                <firstname>Lennart</firstname>
-                                <surname>Poettering</surname>
-                                <email>lennart@poettering.net</email>
-                        </author>
-                </authorgroup>
-        </refentryinfo>
-
-        <refmeta>
-                <refentrytitle>sd_bus_request_name</refentrytitle>
-                <manvolnum>3</manvolnum>
-        </refmeta>
-
-        <refnamediv>
-                <refname>sd_bus_request_name</refname>
-                <refname>sd_bus_release_name</refname>
-                <refpurpose>Request or release a well-known name on a bus</refpurpose>
-        </refnamediv>
-
-        <refsynopsisdiv>
-                <funcsynopsis>
-                        <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_bus_request_name</function></funcdef>
-                                <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
-                                <paramdef>const char *<parameter>name</parameter></paramdef>
-                                <paramdef>uint64_t <parameter>flags</parameter></paramdef>
-                        </funcprototype>
-
-                        <funcprototype>
-                                <funcdef>int <function>sd_bus_release_name</function></funcdef>
-                                <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
-                                <paramdef>const char *<parameter>name</parameter></paramdef>
-                        </funcprototype>
-                </funcsynopsis>
-        </refsynopsisdiv>
-
-        <refsect1>
-                <title>Description</title>
-
-                <para><function>sd_bus_request_name()</function> requests
-                a well-known name on a bus. It takes a bus connection,
-                a valid bus name and a flags parameter. The flags
-                parameter is a combination of the following
-                flags:</para>
-
-                <variablelist>
-                        <varlistentry>
-                                <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term>
-
-                                <listitem><para>After acquiring the
-                                name successfully, permit other peers
-                                to take over the name when they try to
-                                acquire it with the
-                                <varname>SD_BUS_NAME_REPLACE_EXISTING</varname>
-                                flag set. If
-                                <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname>
-                                is not set on the original request,
-                                such a request by other peers will be
-                                denied.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term>
-
-                                <listitem><para>Take over the name
-                                if it is already acquired by another
-                                peer, and that other peer has permitted
-                                takeover by setting
-                                <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname>
-                                while acquiring it.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>SD_BUS_NAME_QUEUE</varname></term>
-
-                                <listitem><para>Queue the acquisition
-                                of the name when the name is already
-                                taken.</para></listitem>
-                        </varlistentry>
-                </variablelist>
-
-                <para><function>sd_bus_release_name()</function> releases
-                an acquired well-known name. It takes a bus connection
-                and a valid bus name as parameters.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Return Value</title>
-
-                <para>On success, these calls return 0 or a positive
-                integer. On failure, these calls return a negative
-                errno-style error code.</para>
-
-                <para>If <varname>SD_BUS_NAME_QUEUE</varname> is
-                specified, <function>sd_bus_request_name()</function>
-                will return 0 when the name is already taken by
-                another peer and the client has been added to the
-                queue for the name. In that case, the caller can
-                subscribe to <literal>NameOwnerChanged</literal>
-                signals to be notified when the name is successfully
-                acquired. <function>sd_bus_request_name()</function>
-                returns &gt; 0 when the name has immediately been
-                acquired successfully.</para>
-        </refsect1>
-
-        <refsect1>
-                <title>Errors</title>
-
-                <para>Returned errors may indicate the following problems:</para>
-
-                <variablelist>
-                        <varlistentry>
-                                <term><varname>-EALREADY</varname></term>
-
-                                <listitem><para>The caller already is
-                                the owner of the specified
-                                name.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>-EEXIST</varname></term>
-
-                                <listitem><para>The name has already
-                                been acquired by a different peer, and
-                                SD_BUS_NAME_REPLACE_EXISTING was not
-                                specified or the other peer did not
-                                specify SD_BUS_NAME_ALLOW_REPLACEMENT
-                                while acquiring the
-                                name.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>-ESRCH</varname></term>
-
-                                <listitem><para>It was attempted to
-                                release a name that is currently not
-                                registered on the
-                                bus.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>-EADDRINUSE</varname></term>
-
-                                <listitem><para>It was attempted to
-                                release a name that is owned by a
-                                different peer on the
-                                bus.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>-EINVAL</varname></term>
-
-                                <listitem><para>A specified parameter
-                                is invalid.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>-ENOTCONN</varname></term>
-
-                                <listitem><para>The bus connection has
-                                been disconnected.</para></listitem>
-                        </varlistentry>
-
-                        <varlistentry>
-                                <term><varname>-ECHILD</varname></term>
-
-                                <listitem><para>The bus connection has
-                                been created in a different process
-                                than the current one.</para></listitem>
-                        </varlistentry>
-                </variablelist>
-        </refsect1>
-
-        <refsect1>
-                <title>Notes</title>
-
-                <para>The <function>sd_bus_acquire_name()</function>
-                and <function>sd_bus_release_name()</function>
-                interfaces are available as a shared library, which can
-                be compiled and linked to with the
-                <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                file.</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_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-                </para>
-        </refsect1>
+  <refentryinfo>
+    <title>sd_bus_request_name</title>
+    <productname>systemd</productname>
+
+    <authorgroup>
+      <author>
+        <contrib>Developer</contrib>
+        <firstname>Lennart</firstname>
+        <surname>Poettering</surname>
+        <email>lennart@poettering.net</email>
+      </author>
+    </authorgroup>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_bus_request_name</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_bus_request_name</refname>
+    <refname>sd_bus_release_name</refname>
+    <refpurpose>Request or release a well-known name on a bus</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_request_name</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>name</parameter></paramdef>
+        <paramdef>uint64_t <parameter>flags</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>sd_bus_release_name</function></funcdef>
+        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
+        <paramdef>const char *<parameter>name</parameter></paramdef>
+      </funcprototype>
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><function>sd_bus_request_name()</function> requests a
+    well-known name on a bus. It takes a bus connection, a valid bus
+    name and a flags parameter. The flags parameter is a combination
+    of the following flags:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term>
+
+        <listitem><para>After acquiring the name successfully, permit
+        other peers to take over the name when they try to acquire it
+        with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag
+        set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is
+        not set on the original request, such a request by other peers
+        will be denied.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term>
+
+        <listitem><para>Take over the name if it is already acquired
+        by another peer, and that other peer has permitted takeover by
+        setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while
+        acquiring it.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>SD_BUS_NAME_QUEUE</varname></term>
+
+        <listitem><para>Queue the acquisition of the name when the
+        name is already taken.</para></listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para><function>sd_bus_release_name()</function> releases an
+    acquired well-known name. It takes a bus connection and a valid
+    bus name as parameters.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>On success, these calls return 0 or a positive integer. On
+    failure, these calls return a negative errno-style error
+    code.</para>
+
+    <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified,
+    <function>sd_bus_request_name()</function> will return 0 when the
+    name is already taken by another peer and the client has been
+    added to the queue for the name. In that case, the caller can
+    subscribe to <literal>NameOwnerChanged</literal> signals to be
+    notified when the name is successfully acquired.
+    <function>sd_bus_request_name()</function> returns &gt; 0 when the
+    name has immediately been acquired successfully.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-EALREADY</constant></term>
+
+        <listitem><para>The caller already is the owner of the
+        specified name.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EEXIST</constant></term>
+
+        <listitem><para>The name has already been acquired by a
+        different peer, and SD_BUS_NAME_REPLACE_EXISTING was not
+        specified or the other peer did not specify
+        SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the
+        name.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ESRCH</constant></term>
+
+        <listitem><para>It was attempted to release a name that is
+        currently not registered on the bus.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EADDRINUSE</constant></term>
+
+        <listitem><para>It was attempted to release a name that is
+        owned by a different peer on the bus.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>A specified parameter is
+        invalid.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ENOTCONN</constant></term>
+
+        <listitem><para>The bus connection has been
+        disconnected.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><constant>-ECHILD</constant></term>
+
+        <listitem><para>The bus connection has been created in a
+        different process than the current one.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Notes</title>
+
+    <para>The <function>sd_bus_acquire_name()</function> and
+    <function>sd_bus_release_name()</function> interfaces are
+    available as a shared library, which can be compiled and linked to
+    with the
+    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    file.</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_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+    </para>
+  </refsect1>
 
 </refentry>