'\" t .TH "SD_BUS_REQUEST_NAME" "3" "" "elogind 246.9.1" "sd_bus_request_name" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" 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 .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .HP \w'typedef\ int\ (*sd_bus_message_handler_t)('u .BI "typedef int (*sd_bus_message_handler_t)(sd_bus_message\ *" "m" ", void\ *" "userdata" ", sd_bus_error\ *" "ret_error" ");" .HP \w'int\ sd_bus_request_name('u .BI "int sd_bus_request_name(sd_bus\ *" "bus" ", const\ char\ *" "name" ", uint64_t\ " "flags" ");" .HP \w'int\ sd_bus_request_name_async('u .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" ");" .HP \w'int\ sd_bus_release_name('u .BI "int sd_bus_release_name(sd_bus\ *" "bus" ", const\ char\ *" "name" ");" .HP \w'int\ sd_bus_release_name_async('u .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" ");" .SH "DESCRIPTION" .PP \fBsd_bus_request_name()\fR 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: .PP \fBSD_BUS_NAME_ALLOW_REPLACEMENT\fR .RS 4 After acquiring the name successfully, permit other peers to take over the name when they try to acquire it with the \fBSD_BUS_NAME_REPLACE_EXISTING\fR flag set\&. If \fBSD_BUS_NAME_ALLOW_REPLACEMENT\fR is not set on the original request, such a request by other peers will be denied\&. .RE .PP \fBSD_BUS_NAME_REPLACE_EXISTING\fR .RS 4 Take over the name if it was already acquired by another peer, and that other peer has permitted takeover by setting \fBSD_BUS_NAME_ALLOW_REPLACEMENT\fR while acquiring it\&. .RE .PP \fBSD_BUS_NAME_QUEUE\fR .RS 4 Queue the acquisition of the name when the name is already taken\&. .RE .PP \fBsd_bus_request_name()\fR operates in a synchronous fashion: a message requesting the name is sent to the bus broker, and the call waits until the broker responds\&. .PP \fBsd_bus_request_name_async()\fR is an asynchronous version of \fBsd_bus_release_name()\fR\&. Instead of waiting for the request to complete, the request message is enqueued\&. The specified \fIcallback\fR will be called when the broker\*(Aqs response is received\&. If the parameter is specified as \fBNULL\fR 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 \fIslot\fR parameter \(em if it is passed as non\-\fBNULL\fR \(em which may be used as a reference to the name request operation\&. Use \fBsd_bus_slot_unref\fR(3) to destroy this reference\&. Note that destroying the reference will not unregister the name, but simply ensure the specified callback is no longer called\&. .PP \fBsd_bus_release_name()\fR 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\&. .PP \fBsd_bus_release_name_async()\fR is an asynchronous version of \fBsd_bus_release_name()\fR\&. The specified \fIcallback\fR function is called when the name has been released successfully\&. If specified as \fBNULL\fR a generic implementation is used that ignores the result of the operation\&. As above, the \fIslot\fR (if non\-\fBNULL\fR) is set to an object that may be used to reference the operation\&. .PP These functions are supported only on bus connections, i\&.e\&. connections to a bus broker and not on direct connections\&. .SH "RETURN VALUE" .PP On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&. .PP If \fBSD_BUS_NAME_QUEUE\fR is specified, \fBsd_bus_request_name()\fR 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 "NameOwnerChanged" signals to be notified when the name is successfully acquired\&. \fBsd_bus_request_name()\fR returns > 0 when the name has immediately been acquired successfully\&. .SS "Errors" .PP Returned errors may indicate the following problems: .PP \fB\-EALREADY\fR .RS 4 The caller already is the owner of the specified name\&. .RE .PP \fB\-EEXIST\fR .RS 4 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\&. .RE .PP \fB\-ESRCH\fR .RS 4 It was attempted to release a name that is currently not registered on the bus\&. .RE .PP \fB\-EADDRINUSE\fR .RS 4 It was attempted to release a name that is owned by a different peer on the bus\&. .RE .PP \fB\-EINVAL\fR .RS 4 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\&. .RE .PP \fB\-ENOTCONN\fR .RS 4 The bus connection has been disconnected\&. .RE .PP \fB\-ECHILD\fR .RS 4 The bus connection has been created in a different process than the current one\&. .RE .SH "NOTES" .PP These APIs are implemented as a shared library, which can be compiled and linked to with the \fBlibelogind\fR\ \&\fBpkg-config\fR(1) file\&. .SH "SEE ALSO" .PP \fBelogind\fR(8), \fBsd-bus\fR(3), \fBsd_bus_new\fR(3), \fBsd_bus_slot_unref\fR(3)