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