x SuSE Linux 13.1-RELEASE x
x SuSE Linux 13.1-RELEASEx
SD_BUS_NEW(3) sd_bus_new SD_BUS_NEW(3)
NAME
sd_bus_new, 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
SYNOPSIS
#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 *sd_bus_close_unref(sd_bus *bus);
sd_bus *sd_bus_flush_close_unref(sd_bus *bus);
void sd_bus_unrefp(sd_bus **busp);
void sd_bus_close_unrefp(sd_bus **busp);
void sd_bus_flush_close_unrefp(sd_bus **busp);
DESCRIPTION
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 is better to use 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 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.
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_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[1]. Note that this
function is defined as an 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) {
errno = -r;
fprintf(stderr, "Failed to allocate bus: %m\n");
}
...
}
sd_bus_ref() and sd_bus_unref() execute no operation if the argument 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_close(3), 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_flush(3) as well as sd_bus_close(3), 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().
RETURN VALUE
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() and sd_bus_flush_close_unref() always return NULL.
Errors
Returned errors may indicate the following problems:
-ENOMEM
Memory allocation failed.
NOTES
Functions described here are available as a shared library, which can
be compiled against and linked to with the libsystemd pkg-config(1)
file.
The code described here uses getenv(3), which is declared to be not
multi-thread-safe. This means that the code calling the functions
described here must not call setenv(3) from a parallel thread. It is
recommended to only do calls to setenv() from an early phase of the
program when no other threads have been started.
SEE ALSO
systemd(1), sd-bus(3), sd_bus_default_user(3),
sd_bus_default_system(3), sd_bus_open_user(3), sd_bus_open_system(3),
sd_bus_close(3)
NOTES
1. Clean-up Variable Attribute
https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
systemd 254 SD_BUS_NEW(3)
Want to link to this manual page? Use this URL:
<http://star2.abcm.com/cgi-bin/bsdi-man?query=sd_bus_flush_close_unref&sektion=3&manpath=>