X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fsd_bus_new.xml;h=355b34bad8e14be987d895cbcdd2d6bbf7ba97d2;hb=db9ecf050165fd1033c6f81485917e229c4be537;hp=b095518f8fed0069ee5d1be4dd7c0bbf5c982515;hpb=514094f933a2b7ba55141bb7ecf867bb28496e9f;p=thirdparty%2Fsystemd.git diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index b095518f8fe..355b34bad8e 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -1,10 +1,7 @@ - - - + + @@ -23,6 +20,10 @@ sd_bus_ref sd_bus_unref sd_bus_unrefp + sd_bus_close_unref + sd_bus_close_unrefp + sd_bus_flush_close_unref + sd_bus_flush_close_unrefp Create a new bus object and create or destroy references to it @@ -46,9 +47,29 @@ sd_bus *bus + + sd_bus *sd_bus_close_unref + sd_bus *bus + + + + sd_bus *sd_bus_flush_close_unref + sd_bus *bus + + void sd_bus_unrefp - sd_bus **bus + sd_bus **busp + + + + void sd_bus_close_unrefp + sd_bus **busp + + + + void sd_bus_flush_close_unrefp + sd_bus **busp @@ -66,14 +87,12 @@ or a related call, and then start the connection with sd_bus_start3. - In most cases, it is a better idea to invoke + In most cases, it is better to use 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. + or related calls instead of the more low-level sd_bus_new() and + sd_bus_start(). The higher-level functions not only allocate a bus object but also + start the connection to a well-known bus in a single function call. sd_bus_ref() increases the reference counter of bus by one. @@ -96,19 +115,41 @@ 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)); - … + __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. + sd_bus_ref() and sd_bus_unref() + execute no operation if the passed in bus object address is + NULL. sd_bus_unrefp() will first + dereference its argument, which must not be NULL, and will + execute no operation if that is NULL. + + + sd_bus_close_unref() is similar to sd_bus_unref(), but + first executes + sd_bus_close3, + ensuring that the connection is terminated before the reference to the connection is dropped and possibly + the object freed. + + sd_bus_flush_close_unref() is similar to sd_bus_unref(), + but first executes + sd_bus_flush3 as well + as sd_bus_close3, + ensuring that any pending messages are synchronously flushed out before the reference to the connection + is dropped and possibly the object freed. This call is particularly useful immediately before exiting + from a program as it ensures that any pending outgoing messages are written out, and unprocessed but + queued incoming messages released before the connection is terminated and released. + + sd_bus_close_unrefp() is similar to + sd_bus_close_unref(), but may be used in GCC's and LLVM's Clean-up Variable + Attribute, see above. Similarly, sd_bus_flush_close_unrefp() is similar to + sd_bus_flush_close_unref(). @@ -121,22 +162,22 @@ sd_bus_ref() always returns the argument. - sd_bus_unref() always returns + sd_bus_unref() and sd_bus_flush_close_unref() always return NULL. - - - Errors + + Errors - Returned errors may indicate the following problems: + Returned errors may indicate the following problems: - - - -ENOMEM + + + -ENOMEM - Memory allocation failed. - - + Memory allocation failed. + + + @@ -150,7 +191,8 @@ sd_bus_default_user3, sd_bus_default_system3, sd_bus_open_user3, - sd_bus_open_system3 + sd_bus_open_system3, + sd_bus_close3