man/sd_bus_request_name.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2013 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="sd_bus_request_name">
  27
  28   <refentryinfo>
  29     <title>sd_bus_request_name</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_bus_request_name</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_bus_request_name</refname>
  49     <refname>sd_bus_release_name</refname>
  50     <refpurpose>Request or release a well-known service name on a bus</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <funcsynopsis>
  55       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_bus_request_name</function></funcdef>
  59         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  60         <paramdef>const char *<parameter>name</parameter></paramdef>
  61         <paramdef>uint64_t <parameter>flags</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_bus_release_name</function></funcdef>
  66         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  67         <paramdef>const char *<parameter>name</parameter></paramdef>
  68       </funcprototype>
  69     </funcsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para><function>sd_bus_request_name()</function> requests a
  76     well-known service name on a bus. It takes a bus connection, a
  77     valid bus name and a flags parameter. The flags parameter is a
  78     combination of the following flags:</para>
  79
  80     <variablelist>
  81       <varlistentry>
  82         <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term>
  83
  84         <listitem><para>After acquiring the name successfully, permit
  85         other peers to take over the name when they try to acquire it
  86         with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag
  87         set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is
  88         not set on the original request, such a request by other peers
  89         will be denied.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term>
  94
  95         <listitem><para>Take over the name if it is already acquired
  96         by another peer, and that other peer has permitted takeover by
  97         setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while
  98         acquiring it.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><varname>SD_BUS_NAME_QUEUE</varname></term>
 103
 104         <listitem><para>Queue the acquisition of the name when the
 105         name is already taken.</para></listitem>
 106       </varlistentry>
 107     </variablelist>
 108
 109     <para><function>sd_bus_release_name()</function> releases an
 110     acquired well-known name. It takes a bus connection and a valid
 111     bus name as parameters.</para>
 112   </refsect1>
 113
 114   <refsect1>
 115     <title>Return Value</title>
 116
 117     <para>On success, these calls return 0 or a positive integer. On
 118     failure, these calls return a negative errno-style error
 119     code.</para>
 120
 121     <para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified,
 122     <function>sd_bus_request_name()</function> will return 0 when the
 123     name is already taken by another peer and the client has been
 124     added to the queue for the name. In that case, the caller can
 125     subscribe to <literal>NameOwnerChanged</literal> signals to be
 126     notified when the name is successfully acquired.
 127     <function>sd_bus_request_name()</function> returns &gt; 0 when the
 128     name has immediately been acquired successfully.</para>
 129   </refsect1>
 130
 131   <refsect1>
 132     <title>Errors</title>
 133
 134     <para>Returned errors may indicate the following problems:</para>
 135
 136     <variablelist>
 137       <varlistentry>
 138         <term><constant>-EALREADY</constant></term>
 139
 140         <listitem><para>The caller already is the owner of the
 141         specified name.</para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><constant>-EEXIST</constant></term>
 146
 147         <listitem><para>The name has already been acquired by a
 148         different peer, and SD_BUS_NAME_REPLACE_EXISTING was not
 149         specified or the other peer did not specify
 150         SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the
 151         name.</para></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><constant>-ESRCH</constant></term>
 156
 157         <listitem><para>It was attempted to release a name that is
 158         currently not registered on the bus.</para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><constant>-EADDRINUSE</constant></term>
 163
 164         <listitem><para>It was attempted to release a name that is
 165         owned by a different peer on the bus.</para></listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><constant>-EINVAL</constant></term>
 170
 171         <listitem><para>A specified parameter is invalid. This is also
 172         generated when the requested name is a special service name
 173         reserved by the D-Bus specification, or when the operation is
 174         requested on a connection that does not refer to a
 175         bus.</para></listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term><constant>-ENOTCONN</constant></term>
 180
 181         <listitem><para>The bus connection has been
 182         disconnected.</para></listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><constant>-ECHILD</constant></term>
 187
 188         <listitem><para>The bus connection has been created in a
 189         different process than the current one.</para></listitem>
 190       </varlistentry>
 191     </variablelist>
 192   </refsect1>
 193
 194   <refsect1>
 195     <title>Notes</title>
 196
 197     <para>The <function>sd_bus_acquire_name()</function> and
 198     <function>sd_bus_release_name()</function> interfaces are
 199     available as a shared library, which can be compiled and linked to
 200     with the
 201     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 202     file.</para>
 203   </refsect1>
 204
 205   <refsect1>
 206     <title>See Also</title>
 207
 208     <para>
 209       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 210       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 212     </para>
 213   </refsect1>
 214
 215 </refentry>