2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_bus_new" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_bus_new
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_bus_new
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_bus_new
</refname>
23 <refname>sd_bus_ref
</refname>
24 <refname>sd_bus_unref
</refname>
25 <refname>sd_bus_unrefp
</refname>
26 <refname>sd_bus_close_unref
</refname>
27 <refname>sd_bus_close_unrefp
</refname>
28 <refname>sd_bus_flush_close_unref
</refname>
29 <refname>sd_bus_flush_close_unrefp
</refname>
31 <refpurpose>Create a new bus object and create or destroy references to it
</refpurpose>
36 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
39 <funcdef>int
<function>sd_bus_new
</function></funcdef>
40 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
44 <funcdef>sd_bus *
<function>sd_bus_ref
</function></funcdef>
45 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
49 <funcdef>sd_bus *
<function>sd_bus_unref
</function></funcdef>
50 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
54 <funcdef>sd_bus *
<function>sd_bus_close_unref
</function></funcdef>
55 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
59 <funcdef>sd_bus *
<function>sd_bus_flush_close_unref
</function></funcdef>
60 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
64 <funcdef>void
<function>sd_bus_unrefp
</function></funcdef>
65 <paramdef>sd_bus **
<parameter>busp
</parameter></paramdef>
69 <funcdef>void
<function>sd_bus_close_unrefp
</function></funcdef>
70 <paramdef>sd_bus **
<parameter>busp
</parameter></paramdef>
74 <funcdef>void
<function>sd_bus_flush_close_unrefp
</function></funcdef>
75 <paramdef>sd_bus **
<parameter>busp
</parameter></paramdef>
81 <title>Description
</title>
83 <para><function>sd_bus_new()
</function> creates a new bus
84 object. This object is reference-counted, and will be destroyed
85 when all references are gone. Initially, the caller of this
86 function owns the sole reference and the bus object will not be
87 connected to any bus. To connect it to a bus, make sure
88 to set an address with
89 <citerefentry><refentrytitle>sd_bus_set_address
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
90 or a related call, and then start the connection with
91 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
93 <para>In most cases, it is a better idea to invoke
94 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
95 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
96 or related calls instead of the more low-level
97 <function>sd_bus_new()
</function> and
98 <function>sd_bus_start()
</function>. The higher-level calls not
99 only allocate a bus object but also start the connection to a
100 well-known bus in a single function invocation.
</para>
102 <para><function>sd_bus_ref()
</function> increases the reference
103 counter of
<parameter>bus
</parameter> by one.
</para>
105 <para><function>sd_bus_unref()
</function> decreases the reference
106 counter of
<parameter>bus
</parameter> by one. Once the reference
107 count has dropped to zero,
<parameter>bus
</parameter> is destroyed
108 and cannot be used anymore, so further calls to
109 <function>sd_bus_ref()
</function> or
110 <function>sd_bus_unref()
</function> are illegal.
</para>
112 <para><function>sd_bus_unrefp()
</function> is similar to
113 <function>sd_bus_unref()
</function> but takes a pointer to a
114 pointer to an
<type>sd_bus
</type> object. This call is useful in
115 conjunction with GCC's and LLVM's
<ulink
116 url=
"https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
117 Variable Attribute
</ulink>. Note that this function is defined as
118 inline function. Use a declaration like the following, in order to
119 allocate a bus object that is freed automatically as the code
120 block is left:
</para>
123 __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
126 r = sd_bus_default(
&bus);
128 fprintf(stderr,
"Failed to allocate bus: %s\n", strerror(-r));
132 <para><function>sd_bus_ref()
</function> and
<function>sd_bus_unref()
</function>
133 execute no operation if the passed in bus object address is
134 <constant>NULL
</constant>.
<function>sd_bus_unrefp()
</function> will first
135 dereference its argument, which must not be
<constant>NULL
</constant>, and will
136 execute no operation if
<emphasis>that
</emphasis> is
<constant>NULL
</constant>.
139 <para><function>sd_bus_close_unref()
</function> is similar to
<function>sd_bus_unref()
</function>, but
141 <citerefentry><refentrytitle>sd_bus_close
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
142 ensuring that the connection is terminated before the reference to the connection is dropped and possibly
143 the object freed.
</para>
145 <para><function>sd_bus_flush_close_unref()
</function> is similar to
<function>sd_bus_unref()
</function>,
147 <citerefentry><refentrytitle>sd_bus_flush
</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well
148 as
<citerefentry><refentrytitle>sd_bus_close
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149 ensuring that any pending messages are synchronously flushed out before the reference to the connection
150 is dropped and possibly the object freed. This call is particularly useful immediately before exiting
151 from a program as it ensures that any pending outgoing messages are written out, and unprocessed but
152 queued incoming messages released before the connection is terminated and released.
</para>
154 <para><function>sd_bus_close_unrefp()
</function> is similar to
155 <function>sd_bus_close_unref()
</function>, but may be used in GCC's and LLVM's Clean-up Variable
156 Attribute, see above. Similarly,
<function>sd_bus_flush_close_unrefp()
</function> is similar to
157 <function>sd_bus_flush_close_unref()
</function>.
</para>
161 <title>Return Value
</title>
163 <para>On success,
<function>sd_bus_new()
</function> returns
0 or a
164 positive integer. On failure, it returns a negative errno-style
167 <para><function>sd_bus_ref()
</function> always returns the argument.
170 <para><function>sd_bus_unref()
</function> and
<function>sd_bus_flush_close_unref()
</function> always return
171 <constant>NULL
</constant>.
</para>
175 <title>Errors
</title>
177 <para>Returned errors may indicate the following problems:
</para>
181 <term><constant>-ENOMEM
</constant></term>
183 <listitem><para>Memory allocation failed.
</para></listitem>
188 <xi:include href=
"libsystemd-pkgconfig.xml" />
191 <title>See Also
</title>
194 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
195 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
196 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
197 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
198 <citerefentry><refentrytitle>sd_bus_open_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
199 <citerefentry><refentrytitle>sd_bus_open_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
200 <citerefentry><refentrytitle>sd_bus_close
</refentrytitle><manvolnum>3</manvolnum></citerefentry>