chiark / gitweb /
ca082183cca7e4f3719dd873bdcf4c002452d5e5
[elogind.git] / 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>