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