sd_bus_new, sd_bus_ref, sd_bus_unref — Create a new bus object and create or destroy references to it
#include <systemd/sd-bus.h>
int sd_bus_new( | sd_bus **bus) ; |
sd_bus *sd_bus_ref( | sd_bus *bus) ; |
sd_bus *sd_bus_unref( | sd_bus *bus) ; |
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 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_address(3)
or a related call, and then start the connection with
sd_bus_start(3).
In most cases it's a better idea to invoke
sd_bus_default_user(3),
sd_bus_default_system(3)
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()
creates a new reference to
bus
.
sd_bus_unref()
destroys a reference to
bus
. Once the reference count has dropped
to zero, bus
cannot be used anymore, so
further calls to sd_bus_ref()
or
sd_bus_unref()
are illegal.
On success, sd_bus_new()
returns 0 or a
positive integer. On failure, it returns a negative errno-style
error code.
sd_bus_ref
always returns the argument.
sd_bus_unref
always returns
NULL
.
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-config(1)
file.