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">
  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>unsigned <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
  68
  69                 </funcsynopsis>
  70         </refsynopsisdiv>
  71
  72         <refsect1>
  73                 <title>Description</title>
  74
  75                 <para><function>sd_bus_request_name()</function> requests
  76                 a well-known name on a bus. It takes a bus connection,
  77                 a valid bus name and a flags parameter. The flags
  78                 parameter is a combination of the following
  79                 flags:</para>
  80
  81                 <variablelist>
  82                         <varlistentry>
  83                                 <term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term>
  84
  85                                 <listitem><para>After acquiring the
  86                                 name successuflly, permit other peers
  87                                 to take over the name when they try to
  88                                 acquire it with the
  89                                 <varname>SD_BUS_NAME_REPLACE_EXISTING</varname>
  90                                 flag set. If
  91                                 <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname>
  92                                 is not set on the original request
  93                                 such a request by other peers will be
  94                                 denied.</para></listitem>
  95                         </varlistentry>
  96
  97                         <varlistentry>
  98                                 <term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term>
  99
 100                                 <listitem><para>Take over a the name
 101                                 if it is already acquired by a another
 102                                 peer, and that other peer permitted
 103                                 taking it over by setting
 104                                 <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname>
 105                                 while acquiring it.</para></listitem>
 106                         </varlistentry>
 107
 108                         <varlistentry>
 109                                 <term><varname>SD_BUS_NAME_DO_NOT_QUEUE</varname></term>
 110
 111                                 <listitem><para>Do not queue name
 112                                 acquisition when the name is already
 113                                 taken.</para></listitem>
 114                         </varlistentry>
 115                 </variablelist>
 116
 117                 <para><function>sd_bus_release_name()</function> releases
 118                 an acquired well-known name. It takes a bus connection
 119                 and a valid bus name as parameters.</para>
 120         </refsect1>
 121
 122         <refsect1>
 123                 <title>Return Value</title>
 124
 125                 <para>On success, these calls return 0 or a positive
 126                 integer. On failure, these calls return a negative
 127                 errno-style error code.</para>
 128
 129                 <para><function>sd_bus_request_name()</function> will
 130                 return 0 when the name is already taken by another
 131                 peer and the client has been added to the queue for
 132                 the name, unless
 133                 <varname>SD_BUS_NAME_DO_NOT_QUEUE</varname> has been
 134                 set. The caller can subscribe to
 135                 <literal>NameOwnerChanged</literal> signals to be
 136                 notified when the name is successfully
 137                 acquired. <function>sd_bus_request_name()</function> returns
 138                 &gt; 0 when the name has been
 139                 acquired successfully.</para>
 140         </refsect1>
 141
 142         <refsect1>
 143                 <title>Errors</title>
 144
 145                 <para>Returned errors may indicate the following problems:</para>
 146
 147                 <variablelist>
 148                         <varlistentry>
 149                                 <term><varname>-EALREADY</varname></term>
 150
 151                                 <listitem><para>The caller already is
 152                                 the owner of the specified
 153                                 name.</para></listitem>
 154                         </varlistentry>
 155
 156                         <varlistentry>
 157                                 <term><varname>-EEXIST</varname></term>
 158
 159                                 <listitem><para>The name has already
 160                                 been acquired by a different peer, and
 161                                 SD_BUS_NAME_REPLACE_EXISTING was not
 162                                 specified or the other peer did not
 163                                 specify SD_BUS_NAME_ALLOW_REPLACEMENT
 164                                 while acquiring the
 165                                 name.</para></listitem>
 166                         </varlistentry>
 167
 168                         <varlistentry>
 169                                 <term><varname>-EINVAL</varname></term>
 170
 171                                 <listitem><para>A specified parameter
 172                                 is invalid.</para></listitem>
 173                         </varlistentry>
 174
 175                         <varlistentry>
 176                                 <term><varname>-ENOTCONN</varname></term>
 177
 178                                 <listitem><para>The bus connection has
 179                                 been disconnected.</para></listitem>
 180                         </varlistentry>
 181
 182                         <varlistentry>
 183                                 <term><varname>-ECHILD</varname></term>
 184
 185                                 <listitem><para>The bus connection has
 186                                 been created in a different process
 187                                 than the current.</para></listitem>
 188                         </varlistentry>
 189                 </variablelist>
 190         </refsect1>
 191
 192         <refsect1>
 193                 <title>Notes</title>
 194
 195                 <para>The <function>sd_bus_acquire_name()</function>
 196                 and <function>sd_bus_release_bame()</function>
 197                 interfaces are available as shared library, which can
 198                 be compiled and linked to with the
 199                 <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 200                 file.</para>
 201         </refsect1>
 202
 203         <refsect1>
 204                 <title>See Also</title>
 205
 206                 <para>
 207                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 208                         <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 209                         <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 210                 </para>
 211         </refsect1>
 212
 213 </refentry>