1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_bus_new" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_bus_new</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_bus_new</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_bus_new</refname> 20 <refname>sd_bus_ref</refname> 21 <refname>sd_bus_unref</refname> 22 <refname>sd_bus_unrefp</refname> 23 <refname>sd_bus_close_unref</refname> 24 <refname>sd_bus_close_unrefp</refname> 25 <refname>sd_bus_flush_close_unref</refname> 26 <refname>sd_bus_flush_close_unrefp</refname> 27 28 <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> 29 </refnamediv> 30 31 <refsynopsisdiv> 32 <funcsynopsis> 33 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 34 35 <funcprototype> 36 <funcdef>int <function>sd_bus_new</function></funcdef> 37 <paramdef>sd_bus **<parameter>bus</parameter></paramdef> 38 </funcprototype> 39 40 <funcprototype> 41 <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef> 42 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 43 </funcprototype> 44 45 <funcprototype> 46 <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef> 47 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 48 </funcprototype> 49 50 <funcprototype> 51 <funcdef>sd_bus *<function>sd_bus_close_unref</function></funcdef> 52 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 53 </funcprototype> 54 55 <funcprototype> 56 <funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef> 57 <paramdef>sd_bus *<parameter>bus</parameter></paramdef> 58 </funcprototype> 59 60 <funcprototype> 61 <funcdef>void <function>sd_bus_unrefp</function></funcdef> 62 <paramdef>sd_bus **<parameter>busp</parameter></paramdef> 63 </funcprototype> 64 65 <funcprototype> 66 <funcdef>void <function>sd_bus_close_unrefp</function></funcdef> 67 <paramdef>sd_bus **<parameter>busp</parameter></paramdef> 68 </funcprototype> 69 70 <funcprototype> 71 <funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef> 72 <paramdef>sd_bus **<parameter>busp</parameter></paramdef> 73 </funcprototype> 74 </funcsynopsis> 75 </refsynopsisdiv> 76 77 <refsect1> 78 <title>Description</title> 79 80 <para><function>sd_bus_new()</function> creates a new bus 81 object. This object is reference-counted, and will be destroyed 82 when all references are gone. Initially, the caller of this 83 function owns the sole reference and the bus object will not be 84 connected to any bus. To connect it to a bus, make sure 85 to set an address with 86 <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry> 87 or a related call, and then start the connection with 88 <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 89 90 <para>In most cases, it is better to use 91 <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 92 <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> 93 or related calls instead of the more low-level <function>sd_bus_new()</function> and 94 <function>sd_bus_start()</function>. The higher-level functions not only allocate a bus object but also 95 start the connection to a well-known bus in a single function call.</para> 96 97 <para><function>sd_bus_ref()</function> increases the reference 98 counter of <parameter>bus</parameter> by one.</para> 99 100 <para><function>sd_bus_unref()</function> decreases the reference 101 counter of <parameter>bus</parameter> by one. Once the reference 102 count has dropped to zero, <parameter>bus</parameter> is destroyed 103 and cannot be used anymore, so further calls to 104 <function>sd_bus_ref()</function> or 105 <function>sd_bus_unref()</function> are illegal.</para> 106 107 <para><function>sd_bus_unrefp()</function> is similar to 108 <function>sd_bus_unref()</function> but takes a pointer to a 109 pointer to an <type>sd_bus</type> object. This call is useful in 110 conjunction with GCC's and LLVM's <ulink 111 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up 112 Variable Attribute</ulink>. Note that this function is defined as an 113 inline function. Use a declaration like the following, in order to 114 allocate a bus object that is freed automatically as the code 115 block is left:</para> 116 117 <programlisting>{ 118 __attribute__((cleanup(sd_bus_unrefp))) sd_bus *bus = NULL; 119 int r; 120 … 121 r = sd_bus_default(&bus); 122 if (r < 0) 123 fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); 124 … 125}</programlisting> 126 127 <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function> execute no operation if 128 the argument is <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first dereference 129 its argument, which must not be <constant>NULL</constant>, and will execute no operation if 130 <emphasis>that</emphasis> is <constant>NULL</constant>.</para> 131 132 <para><function>sd_bus_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but 133 first executes 134 <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 135 ensuring that the connection is terminated before the reference to the connection is dropped and possibly 136 the object freed.</para> 137 138 <para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>, 139 but first executes 140 <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well 141 as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 142 ensuring that any pending messages are synchronously flushed out before the reference to the connection 143 is dropped and possibly the object freed. This call is particularly useful immediately before exiting 144 from a program as it ensures that any pending outgoing messages are written out, and unprocessed but 145 queued incoming messages released before the connection is terminated and released.</para> 146 147 <para><function>sd_bus_close_unrefp()</function> is similar to 148 <function>sd_bus_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable 149 Attribute, see above. Similarly, <function>sd_bus_flush_close_unrefp()</function> is similar to 150 <function>sd_bus_flush_close_unref()</function>.</para> 151 </refsect1> 152 153 <refsect1> 154 <title>Return Value</title> 155 156 <para>On success, <function>sd_bus_new()</function> returns 0 or a 157 positive integer. On failure, it returns a negative errno-style 158 error code.</para> 159 160 <para><function>sd_bus_ref()</function> always returns the argument. 161 </para> 162 163 <para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return 164 <constant>NULL</constant>.</para> 165 166 <refsect2> 167 <title>Errors</title> 168 169 <para>Returned errors may indicate the following problems:</para> 170 171 <variablelist> 172 <varlistentry> 173 <term><constant>-ENOMEM</constant></term> 174 175 <listitem><para>Memory allocation failed.</para></listitem> 176 </varlistentry> 177 </variablelist> 178 </refsect2> 179 </refsect1> 180 181 <xi:include href="libsystemd-pkgconfig.xml" /> 182 183 <refsect1> 184 <title>See Also</title> 185 186 <para> 187 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 188 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 189 <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 190 <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 191 <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 192 <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 193 <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry> 194 </para> 195 </refsect1> 196 197</refentry> 198