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_QUEUE</varname></term>
 110
 111                                 <listitem><para>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>If <varname>SD_BUS_NAME_QUEUE</varname> is
 130                 specified <function>sd_bus_request_name()</function>
 131                 will return 0 when the name is already taken by
 132                 another peer and the client has been added to the
 133                 queue for the name. In that case the caller can
 134                 subscribe to <literal>NameOwnerChanged</literal>
 135                 signals to be notified when the name is successfully
 136                 acquired. <function>sd_bus_request_name()</function>
 137                 returns &gt; 0 when the name has immediately been
 138                 acquired successfully.</para>
 139         </refsect1>
 140
 141         <refsect1>
 142                 <title>Errors</title>
 143
 144                 <para>Returned errors may indicate the following problems:</para>
 145
 146                 <variablelist>
 147                         <varlistentry>
 148                                 <term><varname>-EALREADY</varname></term>
 149
 150                                 <listitem><para>The caller already is
 151                                 the owner of the specified
 152                                 name.</para></listitem>
 153                         </varlistentry>
 154
 155                         <varlistentry>
 156                                 <term><varname>-EEXIST</varname></term>
 157
 158                                 <listitem><para>The name has already
 159                                 been acquired by a different peer, and
 160                                 SD_BUS_NAME_REPLACE_EXISTING was not
 161                                 specified or the other peer did not
 162                                 specify SD_BUS_NAME_ALLOW_REPLACEMENT
 163                                 while acquiring the
 164                                 name.</para></listitem>
 165                         </varlistentry>
 166
 167                         <varlistentry>
 168                                 <term><varname>-EINVAL</varname></term>
 169
 170                                 <listitem><para>A specified parameter
 171                                 is invalid.</para></listitem>
 172                         </varlistentry>
 173
 174                         <varlistentry>
 175                                 <term><varname>-ENOTCONN</varname></term>
 176
 177                                 <listitem><para>The bus connection has
 178                                 been disconnected.</para></listitem>
 179                         </varlistentry>
 180
 181                         <varlistentry>
 182                                 <term><varname>-ECHILD</varname></term>
 183
 184                                 <listitem><para>The bus connection has
 185                                 been created in a different process
 186                                 than the current.</para></listitem>
 187                         </varlistentry>
 188                 </variablelist>
 189         </refsect1>
 190
 191         <refsect1>
 192                 <title>Notes</title>
 193
 194                 <para>The <function>sd_bus_acquire_name()</function>
 195                 and <function>sd_bus_release_bame()</function>
 196                 interfaces are available as shared library, which can
 197                 be compiled and linked to with the
 198                 <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 199                 file.</para>
 200         </refsect1>
 201
 202         <refsect1>
 203                 <title>See Also</title>
 204
 205                 <para>
 206                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 207                         <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208                         <citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 209                 </para>
 210         </refsect1>
 211
 212 </refentry>