X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_new.xml;h=2eeba78e8764d619244b28b054bb538fd8f9ac13;hb=91d60274701a12d2bbcd2b8e40f8b8abe00be0e7;hp=ad1e70080900c3ba3a7a2d21cbb9f39587465fb9;hpb=4cf8496d0a5e85ec7610d166c5d35df3e6d02d1a;p=elogind.git diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index ad1e70080..2eeba78e8 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -1,24 +1,24 @@ - + @@ -46,6 +46,7 @@ along with systemd; If not, see . sd_bus_new sd_bus_ref sd_bus_unref + sd_bus_unrefp Create a new bus object and create or destroy references to it @@ -56,17 +57,22 @@ along with systemd; If not, see . int sd_bus_new - sd_bus** bus + sd_bus **bus - sd_bus* sd_bus_ref - sd_bus* bus + sd_bus *sd_bus_ref + sd_bus *bus - sd_bus* sd_bus_unref - sd_bus* bus + sd_bus *sd_bus_unref + sd_bus *bus + + + + void sd_bus_unrefp + sd_bus **bus @@ -75,20 +81,58 @@ along with systemd; If not, see . Description sd_bus_new() creates a new bus - object. This object is reference counted, and will be destroyed + 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 @@ along with systemd; If not, see . 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. @@ -112,7 +156,7 @@ along with systemd; If not, see . - -ENOMEM + -ENOMEM Memory allocation failed. @@ -125,7 +169,7 @@ along with systemd; If not, see . sd_bus_new() and other functions described here are available as a shared library, which can be compiled and linked to with the - libsystemd-bus pkg-config1 + libelogind pkg-config1 file. @@ -135,10 +179,10 @@ along with systemd; If not, see . 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