2013-12-03 21:01:26 +04:00
<?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">
<!--
This file is part of systemd.
Copyright 2013 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
<refentry id= "sd_bus_request_name" >
<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 > unsigned <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 successuflly, 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 a the name
if it is already acquired by a another
peer, and that other peer permitted
taking it over by setting
<varname > SD_BUS_NAME_ALLOW_REPLACEMENT</varname>
while acquiring it.</para> </listitem>
</varlistentry>
<varlistentry >
2013-12-13 01:01:40 +04:00
<term > <varname > SD_BUS_NAME_QUEUE</varname> </term>
2013-12-03 21:01:26 +04:00
2013-12-13 01:01:40 +04:00
<listitem > <para > Queue name
2013-12-03 21:01:26 +04:00
acquisition 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>
2013-12-13 01:01:40 +04:00
<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
2013-12-03 21:01:26 +04:00
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 > -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.</para> </listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 >
<title > Notes</title>
<para > The <function > sd_bus_acquire_name()</function>
and <function > sd_bus_release_bame()</function>
interfaces are available as shared library, which can
be compiled and linked to with the
<constant > libsystemd-bus</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>
</refentry>
