Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_request_name.3

raw
1 '\" t
2 .TH "SD_BUS_REQUEST_NAME" "3" "" "systemd 261~rc3" "sd_bus_request_name"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_request_name, sd_bus_request_name_async, sd_bus_release_name, sd_bus_release_name_async \- Request or release a well\-known service name on a bus
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'typedef\ int\ (*sd_bus_message_handler_t)('u
32 .BI "typedef int (*sd_bus_message_handler_t)(sd_bus_message\ *" "m" ", void\ *" "userdata" ", sd_bus_error\ *" "ret_error" ");"
33 .HP \w'int\ sd_bus_request_name('u
34 .BI "int sd_bus_request_name(sd_bus\ *" "bus" ", const\ char\ *" "name" ", uint64_t\ " "flags" ");"
35 .HP \w'int\ sd_bus_request_name_async('u
36 .BI "int sd_bus_request_name_async(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "name" ", uint64_t\ " "flags" ", sd_bus_message_handler_t\ " "callback" ", void\ *" "userdata" ");"
37 .HP \w'int\ sd_bus_release_name('u
38 .BI "int sd_bus_release_name(sd_bus\ *" "bus" ", const\ char\ *" "name" ");"
39 .HP \w'int\ sd_bus_release_name_async('u
40 .BI "int sd_bus_release_name_async(sd_bus\ *" "bus" ", sd_bus_slot\ **" "slot" ", const\ char\ *" "name" ", sd_bus_message_handler_t\ " "callback" ", void\ *" "userdata" ");"
41 .SH "DESCRIPTION"
42 .PP
43 \fBsd_bus_request_name()\fR
44 requests a well\-known service name on a bus\&. It takes a bus connection, a valid bus name, and a flags parameter\&. The flags parameter is a combination of zero or more of the following flags:
45 .PP
46 \fBSD_BUS_NAME_ALLOW_REPLACEMENT\fR
47 .RS 4
48 After acquiring the name successfully, permit other peers to take over the name when they try to acquire it with the
49 \fBSD_BUS_NAME_REPLACE_EXISTING\fR
50 flag set\&. If
51 \fBSD_BUS_NAME_ALLOW_REPLACEMENT\fR
52 is not set on the original request, such a request by other peers will be denied\&.
53 .sp
54 Added in version 209\&.
55 .RE
56 .PP
57 \fBSD_BUS_NAME_REPLACE_EXISTING\fR
58 .RS 4
59 Take over the name if it was already acquired by another peer, and that other peer has permitted takeover by setting
60 \fBSD_BUS_NAME_ALLOW_REPLACEMENT\fR
61 while acquiring it\&.
62 .sp
63 Added in version 209\&.
64 .RE
65 .PP
66 \fBSD_BUS_NAME_QUEUE\fR
67 .RS 4
68 Queue the acquisition of the name when the name is already taken\&.
69 .sp
70 Added in version 209\&.
71 .RE
72 .PP
73 \fBsd_bus_request_name()\fR
74 operates in a synchronous fashion: a message requesting the name is sent to the bus broker, and the call waits until the broker responds\&.
75 .PP
76 \fBsd_bus_request_name_async()\fR
77 is an asynchronous version of
78 \fBsd_bus_request_name()\fR\&. Instead of waiting for the request to complete, the request message is enqueued\&. The specified
79 \fIcallback\fR
80 will be called when the broker\*(Aqs response is received\&. If the parameter is specified as
81 \fBNULL\fR
82 a default implementation is used instead which will terminate the connection when the name cannot be acquired\&. The function returns a slot object in its
83 \fIslot\fR
84 parameter \(em if it is passed as non\-\fBNULL\fR
85 \(em which may be used as a reference to the name request operation\&. Use
86 \fBsd_bus_slot_unref\fR(3)
87 to destroy this reference\&. Note that destroying the reference will not unregister the name, but simply ensure the specified callback is no longer called\&.
88 .PP
89 \fBsd_bus_release_name()\fR
90 releases an acquired well\-known name\&. It takes a bus connection and a valid bus name as parameters\&. This function operates synchronously, sending a release request message to the bus broker and waiting for it to reply\&.
91 .PP
92 \fBsd_bus_release_name_async()\fR
93 is an asynchronous version of
94 \fBsd_bus_release_name()\fR\&. The specified
95 \fIcallback\fR
96 function is called when the name has been released successfully\&. If specified as
97 \fBNULL\fR
98 a generic implementation is used that ignores the result of the operation\&. As above, the
99 \fIslot\fR
100 (if non\-\fBNULL\fR) is set to an object that may be used to reference the operation\&.
101 .PP
102 These functions are supported only on bus connections, i\&.e\&. connections to a bus broker and not on direct connections\&.
103 .SH "RETURN VALUE"
104 .PP
105 On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
106 .PP
107 If
108 \fBSD_BUS_NAME_QUEUE\fR
109 is specified,
110 \fBsd_bus_request_name()\fR
111 will return 0 when the name is already taken by another peer and the client has been added to the queue for the name\&. In that case, the caller can subscribe to
112 "NameOwnerChanged"
113 signals to be notified when the name is successfully acquired\&.
114 \fBsd_bus_request_name()\fR
115 returns > 0 when the name has immediately been acquired successfully\&.
116 .SS "Errors"
117 .PP
118 Returned errors may indicate the following problems:
119 .PP
120 \fB\-EALREADY\fR
121 .RS 4
122 The caller already is the owner of the specified name\&.
123 .RE
124 .PP
125 \fB\-EEXIST\fR
126 .RS 4
127 The name has already been acquired by a different peer, and SD_BUS_NAME_REPLACE_EXISTING was not specified or the other peer did not specify SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the name\&.
128 .RE
129 .PP
130 \fB\-ESRCH\fR
131 .RS 4
132 It was attempted to release a name that is currently not registered on the bus\&.
133 .RE
134 .PP
135 \fB\-EADDRINUSE\fR
136 .RS 4
137 It was attempted to release a name that is owned by a different peer on the bus\&.
138 .RE
139 .PP
140 \fB\-EINVAL\fR
141 .RS 4
142 A specified parameter is invalid\&. This is also generated when the requested name is a special service name reserved by the D\-Bus specification, or when the operation is requested on a connection that does not refer to a bus\&.
143 .RE
144 .PP
145 \fB\-ENOTCONN\fR
146 .RS 4
147 The bus connection has been disconnected\&.
148 .RE
149 .PP
150 \fB\-ECHILD\fR
151 .RS 4
152 The bus connection has been created in a different process than the current one\&.
153 .RE
154 .SH "NOTES"
155 .PP
156 Functions described here are available as a shared library, which can be compiled against and linked to with the
157 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
158 file\&.
159 .PP
160 The code described here uses
161 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
162 \fBsetenv\fR(3)
163 from a parallel thread\&. It is recommended to only do calls to
164 \fBsetenv()\fR
165 from an early phase of the program when no other threads have been started\&.
166 .SH "HISTORY"
167 .PP
168 \fBsd_bus_request_name()\fR
169 and
170 \fBsd_bus_release_name()\fR
171 were added in version 209\&.
172 .PP
173 \fBsd_bus_request_name_async()\fR
174 and
175 \fBsd_bus_release_name_async()\fR
176 were added in version 237\&.
177 .SH "SEE ALSO"
178 .PP
179 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_new\fR(3), \fBsd_bus_slot_unref\fR(3)