X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsd_bus_request_name.xml;h=6aa132bb2649caf2ae07fe4d97cab801d557eb7f;hp=6e61a88737a3fda177acf7748618d3314e5e804a;hb=f4f01ec146d91cb6943828851d98eee6a1ad4dd9;hpb=e7176abbe818c75c6acd90227a7a84c3e05fee31 diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml index 6e61a8873..6aa132bb2 100644 --- a/man/sd_bus_request_name.xml +++ b/man/sd_bus_request_name.xml @@ -1,6 +1,6 @@ + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - - - - 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 - unsigned 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 successuflly, 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 a the name - if it is already acquired by a another - peer, and that other peer permitted - taking it over by setting - SD_BUS_NAME_ALLOW_REPLACEMENT - while acquiring it. - - - - SD_BUS_NAME_DO_NOT_QUEUE - - Do not queue name - acquisition 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. - - 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, unless - SD_BUS_NAME_DO_NOT_QUEUE has been - set. 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 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. - - - - -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. - - - - - - Notes - - The sd_bus_acquire_name() - and sd_bus_release_bame() - interfaces are available as shared library, which can - be compiled and linked to with the - libsystemd-bus pkg-config1 - file. - - - - See Also - - - systemd1, - sd-bus3, - sd_bus_new3 - - + + + + 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-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3 + +