X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_new.xml;h=2eeba78e8764d619244b28b054bb538fd8f9ac13;hb=d04b238170998e0cbcc86db0f8ae66c3ee4a14d6;hp=91ca8161dcd3e50153c19ef1dfad3fcd815a965e;hpb=b975b0d514321f169b3c4599a8ea92e13741b4e4;p=elogind.git diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 91ca8161d..2eeba78e8 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_bus_new @@ -46,6 +46,7 @@ sd_bus_new sd_bus_ref sd_bus_unref + sd_bus_unrefp Create a new bus object and create or destroy references to it @@ -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. @@ -135,10 +179,10 @@ systemd1, 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