diff options
Diffstat (limited to 'man/sd_bus_request_name.xml')
| -rw-r--r-- | man/sd_bus_request_name.xml | 386 |
1 files changed, 184 insertions, 202 deletions
diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index ca082183cc..6aa132bb26 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 <systemd/sd-bus.h></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 > 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> + <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 <systemd/sd-bus.h></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 > 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> |