e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering This file is part of systemd.
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering Copyright 2013 Lennart Poettering
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering systemd is free software; you can redistribute it and/or modify it
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering under the terms of the GNU Lesser General Public License as published by
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering (at your option) any later version.
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering systemd is distributed in the hope that it will be useful, but
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering Lesser General Public License for more details.
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering You should have received a copy of the GNU Lesser General Public License
e7176abbe818c75c6acd90227a7a84c3e05fee31Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>sd_bus_request_name</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sd_bus_request_name</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_request_name</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>sd_bus_release_name</refname>
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering <refpurpose>Request or release a well-known service name on a bus</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_request_name</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>name</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>uint64_t <parameter>flags</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_release_name</function></funcdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <paramdef>const char *<parameter>name</parameter></paramdef>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </funcprototype>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_bus_request_name()</function> requests a
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering well-known service name on a bus. It takes a bus connection, a
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering valid bus name and a flags parameter. The flags parameter is a
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering combination of the following flags:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>After acquiring the name successfully, permit
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek other peers to take over the name when they try to acquire it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek not set on the original request, such a request by other peers
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek will be denied.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Take over the name if it is already acquired
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek by another peer, and that other peer has permitted takeover by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>SD_BUS_NAME_QUEUE</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Queue the acquisition of the name when the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name is already taken.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><function>sd_bus_release_name()</function> releases an
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek acquired well-known name. It takes a bus connection and a valid
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek bus name as parameters.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>On success, these calls return 0 or a positive integer. On
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek failure, these calls return a negative errno-style error
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_request_name()</function> will return 0 when the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name is already taken by another peer and the client has been
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek added to the queue for the name. In that case, the caller can
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek subscribe to <literal>NameOwnerChanged</literal> signals to be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek notified when the name is successfully acquired.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_request_name()</function> returns > 0 when the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name has immediately been acquired successfully.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-EALREADY</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>The caller already is the owner of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified name.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-EEXIST</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>The name has already been acquired by a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek different peer, and SD_BUS_NAME_REPLACE_EXISTING was not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified or the other peer did not specify
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-ESRCH</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>It was attempted to release a name that is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek currently not registered on the bus.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-EADDRINUSE</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>It was attempted to release a name that is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek owned by a different peer on the bus.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-EINVAL</constant></term>
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering <listitem><para>A specified parameter is invalid. This is also
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering generated when the requested name is a special service name
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering reserved by the D-Bus specification, or when the operation is
2a2e6a0845dedf57233d2c8a89201a563e0c3c6dLennart Poettering requested on a connection that does not refer to a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-ENOTCONN</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>The bus connection has been
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><constant>-ECHILD</constant></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>The bus connection has been created in a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek different process than the current one.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The <function>sd_bus_acquire_name()</function> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <function>sd_bus_release_name()</function> interfaces are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek available as a shared library, which can be compiled and linked to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>