X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_new.xml;h=6be915ac910d82d2d3ca418c5145f301fcf825dc;hb=eb0e417895c37dbdb64f18ae95c6b1a7a99f871e;hp=91ca8161dcd3e50153c19ef1dfad3fcd815a965e;hpb=b975b0d514321f169b3c4599a8ea92e13741b4e4;p=elogind.git diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 91ca8161d..6be915ac9 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -3,29 +3,29 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - + sd_bus_new - systemd + elogind @@ -46,13 +46,14 @@ sd_bus_new sd_bus_ref sd_bus_unref + sd_bus_unrefp Create a new bus object and create or destroy references to it - #include <systemd/sd-bus.h> + #include <elogind/sd-bus.h> int sd_bus_new @@ -68,6 +69,11 @@ sd_bus *sd_bus_unref sd_bus *bus + + + void sd_bus_unrefp + sd_bus **bus + @@ -77,18 +83,56 @@ sd_bus_new() creates a new bus object. This object is reference-counted, and will be destroyed when all references are gone. Initially, the caller of this - function owns the sole reference. - - sd_bus_ref() creates a new reference to - bus. This bus object will not be destroyed - until sd_bus_unref() has been called as many - times plus once more. Once the reference count has dropped to - zero, bus cannot be used anymore, so - further calls to sd_bus_ref() or + function owns the sole reference and the bus object will not be + connected to any bus. To connect it to a bus, make sure + to set an address with + sd_bus_set_address3 + or a related call, and then start the connection with + sd_bus_start3. + + In most cases, it is a better idea to invoke + sd_bus_default_user3, + sd_bus_default_system3 + or related calls instead of the more low-level + sd_bus_new() and + sd_bus_start(). The higher-level calls not + only allocate a bus object but also start the connection to a + well-known bus in a single function invocation. + + sd_bus_ref() increases the reference + counter of bus by one. + + sd_bus_unref() decreases the reference + counter of bus by one. Once the reference + count has dropped to zero, bus is destroyed + and cannot be used anymore, so further calls to + sd_bus_ref() or sd_bus_unref() are illegal. - sd_bus_unref() destroys a reference to - bus. + sd_bus_unrefp() is similar to + sd_bus_unref() but takes a pointer to a + pointer to an sd_bus object. This call is useful in + conjunction with GCC's and LLVM's Clean-up + Variable Attribute. Note that this function is defined as + inline function. Use a declaration like the following, in order to + allocate a bus object that is freed automatically as the code + block is left: + + { + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … +} + + sd_bus_ref(), + sd_bus_unref() and + sd_bus_unrefp() execute no operation if the + passed in bus object is NULL. @@ -98,10 +142,10 @@ positive integer. On failure, it returns a negative errno-style error code. - sd_bus_ref always returns the argument. + sd_bus_ref() always returns the argument. - sd_bus_unref always returns + sd_bus_unref() always returns NULL. @@ -125,7 +169,7 @@ sd_bus_new() and other functions described here are available as a shared library, which can be compiled and linked to with the - libsystemd pkg-config1 + libelogind pkg-config1 file. @@ -133,12 +177,12 @@ See Also - systemd1, + elogind8, sd-bus3, - sd_bus_open_user3, - sd_bus_open_system3, sd_bus_default_user3, - sd_bus_default_system3 + sd_bus_default_system3, + sd_bus_open_user3, + sd_bus_open_system3