sd_bus_request_name, sd_bus_release_name — Request or release a well-known name on a bus
#include <systemd/sd-bus.h>
int sd_bus_request_name( | sd_bus *bus, |
| const char *name, | |
uint64_t flags); |
int sd_bus_release_name( | sd_bus *bus, |
const char *name); |
sd_bus_request_name() requests
a well-known name on a bus. It takes a bus connection,
a valid bus name and a flags parameter. The flags
parameter is a combination of the following
flags:
SD_BUS_NAME_ALLOW_REPLACEMENT¶After acquiring the
name successfully, permit other peers
to take over the name when they try to
acquire it with the
SD_BUS_NAME_REPLACE_EXISTING
flag set. If
SD_BUS_NAME_ALLOW_REPLACEMENT
is not set on the original request,
such a request by other peers will be
denied.
SD_BUS_NAME_REPLACE_EXISTING¶Take over the name
if it is already acquired by another
peer, and that other peer has permitted
takeover by setting
SD_BUS_NAME_ALLOW_REPLACEMENT
while acquiring it.
SD_BUS_NAME_QUEUE¶Queue the acquisition of the name when the name is already taken.
sd_bus_release_name() releases
an acquired well-known name. It takes a bus connection
and a valid bus name as parameters.
On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style error code.
If SD_BUS_NAME_QUEUE is
specified, sd_bus_request_name()
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. sd_bus_request_name()
returns > 0 when the name has immediately been
acquired successfully.
Returned errors may indicate the following problems:
-EALREADY¶The caller already is the owner of the specified name.
-EEXIST¶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.
-ESRCH¶It was attempted to release a name that is currently not registered on the bus.
-EADDRINUSE¶It was attempted to release a name that is owned by a different peer on the bus.
-EINVAL¶A specified parameter is invalid.
-ENOTCONN¶The bus connection has been disconnected.
-ECHILD¶The bus connection has been created in a different process than the current one.
The sd_bus_acquire_name()
and sd_bus_release_name()
interfaces are available as a shared library, which can
be compiled and linked to with the
libsystemd pkg-config(1)
file.