1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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+
8 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"sd_bus_new">
29 <title>sd_bus_new
</title>
30 <productname>systemd
</productname>
34 <contrib>A monkey with a typewriter
</contrib>
35 <firstname>Zbigniew
</firstname>
36 <surname>Jędrzejewski-Szmek
</surname>
37 <email>zbyszek@in.waw.pl
</email>
43 <refentrytitle>sd_bus_new
</refentrytitle>
44 <manvolnum>3</manvolnum>
48 <refname>sd_bus_new
</refname>
49 <refname>sd_bus_ref
</refname>
50 <refname>sd_bus_unref
</refname>
51 <refname>sd_bus_unrefp
</refname>
53 <refpurpose>Create a new bus object and create or destroy references to it
</refpurpose>
58 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
61 <funcdef>int
<function>sd_bus_new
</function></funcdef>
62 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
66 <funcdef>sd_bus *
<function>sd_bus_ref
</function></funcdef>
67 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
71 <funcdef>sd_bus *
<function>sd_bus_unref
</function></funcdef>
72 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
76 <funcdef>void
<function>sd_bus_unrefp
</function></funcdef>
77 <paramdef>sd_bus **
<parameter>bus
</parameter></paramdef>
83 <title>Description
</title>
85 <para><function>sd_bus_new()
</function> creates a new bus
86 object. This object is reference-counted, and will be destroyed
87 when all references are gone. Initially, the caller of this
88 function owns the sole reference and the bus object will not be
89 connected to any bus. To connect it to a bus, make sure
90 to set an address with
91 <citerefentry><refentrytitle>sd_bus_set_address
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
92 or a related call, and then start the connection with
93 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
95 <para>In most cases, it is a better idea to invoke
96 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
97 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
98 or related calls instead of the more low-level
99 <function>sd_bus_new()
</function> and
100 <function>sd_bus_start()
</function>. The higher-level calls not
101 only allocate a bus object but also start the connection to a
102 well-known bus in a single function invocation.
</para>
104 <para><function>sd_bus_ref()
</function> increases the reference
105 counter of
<parameter>bus
</parameter> by one.
</para>
107 <para><function>sd_bus_unref()
</function> decreases the reference
108 counter of
<parameter>bus
</parameter> by one. Once the reference
109 count has dropped to zero,
<parameter>bus
</parameter> is destroyed
110 and cannot be used anymore, so further calls to
111 <function>sd_bus_ref()
</function> or
112 <function>sd_bus_unref()
</function> are illegal.
</para>
114 <para><function>sd_bus_unrefp()
</function> is similar to
115 <function>sd_bus_unref()
</function> but takes a pointer to a
116 pointer to an
<type>sd_bus
</type> object. This call is useful in
117 conjunction with GCC's and LLVM's
<ulink
118 url=
"https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
119 Variable Attribute
</ulink>. Note that this function is defined as
120 inline function. Use a declaration like the following, in order to
121 allocate a bus object that is freed automatically as the code
122 block is left:
</para>
125 __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
128 r = sd_bus_default(
&bus);
130 fprintf(stderr,
"Failed to allocate bus: %s\n", strerror(-r));
134 <para><function>sd_bus_ref()
</function>,
135 <function>sd_bus_unref()
</function> and
136 <function>sd_bus_unrefp()
</function> execute no operation if the
137 passed in bus object is
<constant>NULL
</constant>.
</para>
141 <title>Return Value
</title>
143 <para>On success,
<function>sd_bus_new()
</function> returns
0 or a
144 positive integer. On failure, it returns a negative errno-style
147 <para><function>sd_bus_ref()
</function> always returns the argument.
150 <para><function>sd_bus_unref()
</function> always returns
151 <constant>NULL
</constant>.
</para>
155 <title>Errors
</title>
157 <para>Returned errors may indicate the following problems:
</para>
161 <term><constant>-ENOMEM
</constant></term>
163 <listitem><para>Memory allocation failed.
</para></listitem>
171 <para><function>sd_bus_new()
</function> and other functions
172 described here are available as a shared library, which can be
173 compiled and linked to with the
174 <constant>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
179 <title>See Also
</title>
182 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
185 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
186 <citerefentry><refentrytitle>sd_bus_open_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
187 <citerefentry><refentrytitle>sd_bus_open_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>