sd_bus_request_name

systemd
Developer Lennart Poettering lennart@poettering.net
sd_bus_request_name 3
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

## Description

`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.

## Return Value

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.

## Errors

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.

## Notes

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.

## See Also

systemd 1, sd-bus 3, sd_bus_new 3