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