sd_bus_flush_close_unref(3) — Linux manual page


SD_BUS_NEW(3)                    sd_bus_new                    SD_BUS_NEW(3)

NAME         top

       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         top

       #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         top

       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 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() 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_close(3), ensuring that the connection is terminated before
       the reference to the connection is dropped and possibly the object

       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

RETURN VALUE         top

       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.

       Returned errors may indicate the following problems:

           Memory allocation failed.

NOTES         top

       These APIs are implemented as a shared library, which can be compiled
       and linked to with the libsystemd pkg-config(1) file.

SEE ALSO         top

       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),

NOTES         top

        1. Clean-up Variable Attribute

COLOPHON         top

       This page is part of the systemd (systemd system and service manager)
       project.  Information about the project can be found at 
       ⟨⟩.  If you have a bug
       report for this manual page, see
       ⟨⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨⟩ on 2020-11-01.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-11-01.)  If you discover any rendering problems in
       this HTML version of the page, or you believe there is a better or
       more up-to-date source for the page, or you have corrections or im‐
       provements to the information in this COLOPHON (which is not part of
       the original manual page), send a mail to

systemd 247                                                    SD_BUS_NEW(3)

Pages that refer to this page: sd_bus_close(3)sd_bus_default_flush_close(3)sd_bus_flush(3)30-systemd-environment-d-generator(7)systemd.index(7)