3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Zbigniew Jędrzejewski-Szmek
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <productname>systemd</productname>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <contrib>A monkey with a typewriter</contrib>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <surname>Jędrzejewski-Szmek</surname>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <email>zbyszek@in.waw.pl</email>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <refentrytitle>sd_bus_new</refentrytitle>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <refsynopsisdiv>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_new</function></funcdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek </funcprototype>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek </funcprototype>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek </funcprototype>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <funcprototype>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <funcdef>void <function>sd_bus_unrefp</function></funcdef>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering </funcprototype>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek </refsynopsisdiv>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <para><function>sd_bus_new()</function> creates a new bus
73e231abde39f22097df50542c745e01de879836Jan Engelhardt object. This object is reference-counted, and will be destroyed
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek when all references are gone. Initially, the caller of this
db03761e16f945fdc639f88a0c316eeda665980bUmut Tezduyar Lindskog function owns the sole reference and the bus object will not be
db03761e16f945fdc639f88a0c316eeda665980bUmut Tezduyar Lindskog connected to any bus. To connect it to a bus, make sure
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering to set an address with
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering or a related call, and then start the connection with
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
7ca4155737730ece73ae4b4ac80571005cb99b69Jan Engelhardt <para>In most cases, it is a better idea to invoke
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering or related calls instead of the more low-level
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <function>sd_bus_start()</function>. The higher-level calls not
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering only allocate a bus object but also start the connection to a
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering well-known bus in a single function invocation.</para>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <para><function>sd_bus_ref()</function> increases the reference
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering counter of <parameter>bus</parameter> by one.</para>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <para><function>sd_bus_unref()</function> decreases the reference
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering counter of <parameter>bus</parameter> by one. Once the reference
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering count has dropped to zero, <parameter>bus</parameter> is destroyed
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering and cannot be used anymore, so further calls to
db03761e16f945fdc639f88a0c316eeda665980bUmut Tezduyar Lindskog <function>sd_bus_unref()</function> are illegal.</para>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <para><function>sd_bus_unrefp()</function> is similar to
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <function>sd_bus_unref()</function> but takes a pointer to a
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering pointer to an <type>sd_bus</type> object. This call is useful in
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering conjunction with GCC's and LLVM's <ulink
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering Variable Attribute</ulink>. Note that this function is defined as
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering inline function. Use a declaration like the following, in order to
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering allocate a bus object that is freed automatically as the code
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering block is left:</para>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <programlisting>{
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering r = sd_bus_default(&bus);
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r));
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering}</programlisting>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <function>sd_bus_unrefp()</function> execute no operation if the
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering passed in bus object is <constant>NULL</constant>.</para>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <para>On success, <function>sd_bus_new()</function> returns 0 or a
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek positive integer. On failure, it returns a negative errno-style
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek error code.</para>
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <para><function>sd_bus_ref()</function> always returns the argument.
4afd3348c7506dd1d36305b7bcb9feb8952b9d6bLennart Poettering <para><function>sd_bus_unref()</function> always returns
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <constant>NULL</constant>.</para>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ENOMEM</constant></term>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <listitem><para>Memory allocation failed.</para></listitem>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <para><function>sd_bus_new()</function> and other functions
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek described here are available as a shared library, which can be
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek compiled and linked to with the
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
cd6d5e1c7631d6e74cb04be279dee22e423e08b8Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
850df10ac10aedbc2140bcd1152d6e86fdad9b48Lennart Poettering <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>