2013-12-03 21:01:26 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2015-06-18 20:47:44 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2019-03-14 16:29:37 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1+ -->
2013-12-03 21:01:26 +04:00
2018-08-03 18:34:40 +03:00
<refentry id= "sd_bus_request_name"
xmlns:xi="http://www.w3.org/2001/XInclude">
2013-12-03 21:01:26 +04:00
2015-02-04 05:14:13 +03:00
<refentryinfo >
<title > sd_bus_request_name</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_bus_request_name</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_request_name</refname>
2017-12-20 18:31:58 +03:00
<refname > sd_bus_request_name_async</refname>
2015-02-04 05:14:13 +03:00
<refname > sd_bus_release_name</refname>
2017-12-20 18:31:58 +03:00
<refname > sd_bus_release_name_async</refname>
2015-06-23 22:41:15 +03:00
<refpurpose > Request or release a well-known service name on a bus</refpurpose>
2015-02-04 05:14:13 +03:00
</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>
2017-12-20 18:31:58 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_request_name_async</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_slot **<parameter > slot</parameter> </paramdef>
<paramdef > const char *<parameter > name</parameter> </paramdef>
<paramdef > uint64_t <parameter > flags</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > callback</parameter> </paramdef>
<paramdef > void *<parameter > userdata</parameter> </paramdef>
</funcprototype>
2015-02-04 05:14:13 +03:00
<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>
2017-12-20 18:31:58 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_release_name_async</function> </funcdef>
<paramdef > sd_bus *<parameter > bus</parameter> </paramdef>
<paramdef > sd_bus_slot **<parameter > slot</parameter> </paramdef>
<paramdef > const char *<parameter > name</parameter> </paramdef>
<paramdef > sd_bus_message_handler_t <parameter > callback</parameter> </paramdef>
<paramdef > void *<parameter > userdata</parameter> </paramdef>
</funcprototype>
2015-02-04 05:14:13 +03:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2017-12-20 18:31:58 +03:00
<para > <function > sd_bus_request_name()</function> requests a well-known service 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>
2015-02-04 05:14:13 +03:00
<variablelist >
<varlistentry >
2019-02-13 12:27:36 +03:00
<term > <constant > SD_BUS_NAME_ALLOW_REPLACEMENT</constant> </term>
2015-02-04 05:14:13 +03:00
2017-12-20 18:31:58 +03:00
<listitem > <para > After acquiring the name successfully, permit other peers to take over the name when they try
2019-02-13 12:27:36 +03:00
to acquire it with the <constant > SD_BUS_NAME_REPLACE_EXISTING</constant> flag set. If
<constant > SD_BUS_NAME_ALLOW_REPLACEMENT</constant> is not set on the original request, such a request by other
2017-12-20 18:31:58 +03:00
peers will be denied.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
2019-02-13 12:27:36 +03:00
<term > <constant > SD_BUS_NAME_REPLACE_EXISTING</constant> </term>
2015-02-04 05:14:13 +03:00
2017-12-20 18:31:58 +03:00
<listitem > <para > Take over the name if it is already acquired by another peer, and that other peer has permitted
2019-02-13 12:27:36 +03:00
takeover by setting <constant > SD_BUS_NAME_ALLOW_REPLACEMENT</constant> while acquiring it.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
2019-02-13 12:27:36 +03:00
<term > <constant > SD_BUS_NAME_QUEUE</constant> </term>
2015-02-04 05:14:13 +03:00
2017-12-20 18:31:58 +03:00
<listitem > <para > Queue the acquisition of the name when the name is already taken.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
</variablelist>
2017-12-20 18:31:58 +03:00
<para > <function > sd_bus_request_name()</function> operates in a synchronous fashion: a message requesting the name
is sent to the bus broker, and the call waits until the broker responds.</para>
2018-06-12 17:19:21 +03:00
<para > <function > sd_bus_request_name_async()</function> is an asynchronous version of
2017-12-20 18:31:58 +03:00
<function > sd_bus_release_name()</function> . Instead of waiting for the request to complete, the request message is
enqueued. The specified <parameter > callback</parameter> will be called when the broker's response is received. If
the parameter is specified as <constant > NULL</constant> a default implementation is used instead which will
terminate the connection when the name cannot be acquired. The function returns a slot object in its
<parameter > slot</parameter> parameter — if it is passed as non-<constant > NULL</constant> — which may be used as a
reference to the name request operation. Use
<citerefentry > <refentrytitle > sd_bus_slot_unref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> to destroy
this reference. Note that destroying the reference will not unregister the name, but simply ensure the specified
callback is no longer called.</para>
<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. This function operates synchronously, sending a release request message to the
bus broker and waiting for it to reply.</para>
<para > <function > sd_bus_release_name_async()</function> is an asynchronous version of
<function > sd_bus_release_name()</function> . The specified <parameter > callback</parameter> function is called when
the name has been released successfully. If specified as <constant > NULL</constant> a generic implementation is used
that ignores the result of the operation. As above, the <parameter > slot</parameter> (if
non-<constant > NULL</constant> ) is set to an object that may be used to reference the operation.</para>
<para > These functions are supported only on bus connections, i.e. connections to a bus broker and not on direct
connections.</para>
2015-02-04 05:14:13 +03:00
</refsect1>
<refsect1 >
<title > Return Value</title>
2017-12-20 18:31:58 +03:00
<para > On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style
error code.</para>
2019-02-13 12:27:36 +03:00
<para > If <constant > SD_BUS_NAME_QUEUE</constant> is specified, <function > sd_bus_request_name()</function> will return
2017-12-20 18:31:58 +03:00
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>
2015-02-04 05:14:13 +03:00
</refsect1>
<refsect1 >
<title > Errors</title>
<para > Returned errors may indicate the following problems:</para>
<variablelist >
<varlistentry >
<term > <constant > -EALREADY</constant> </term>
2017-12-20 18:31:58 +03:00
<listitem > <para > The caller already is the owner of the specified name.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -EEXIST</constant> </term>
2017-12-20 18:31:58 +03:00
<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
2015-02-04 05:14:13 +03:00
name.</para> </listitem>
</varlistentry>
<varlistentry >
<term > <constant > -ESRCH</constant> </term>
2017-12-20 18:31:58 +03:00
<listitem > <para > It was attempted to release a name that is currently not registered on the
bus.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -EADDRINUSE</constant> </term>
2017-12-20 18:31:58 +03:00
<listitem > <para > It was attempted to release a name that is owned by a different peer on the
bus.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -EINVAL</constant> </term>
2017-12-20 18:31:58 +03:00
<listitem > <para > A specified parameter is invalid. This is also generated when the requested name is a special
service name reserved by the D-Bus specification, or when the operation is requested on a connection that does
not refer to a bus.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -ENOTCONN</constant> </term>
2017-12-20 18:31:58 +03:00
<listitem > <para > The bus connection has been disconnected.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
<varlistentry >
<term > <constant > -ECHILD</constant> </term>
2017-12-20 18:31:58 +03:00
<listitem > <para > The bus connection has been created in a different process than the current
one.</para> </listitem>
2015-02-04 05:14:13 +03:00
</varlistentry>
</variablelist>
</refsect1>
2018-08-03 18:34:40 +03:00
<xi:include href= "libsystemd-pkgconfig.xml" />
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd-bus</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2017-12-20 18:31:58 +03:00
<citerefentry > <refentrytitle > sd_bus_new</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > sd_bus_slot_unref</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
2015-02-04 05:14:13 +03:00
</para>
</refsect1>
2013-12-03 21:01:26 +04:00
</refentry>