sd_bus_new.xml revision 7ca4155737730ece73ae4b4ac80571005cb99b69
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor This file is part of systemd.
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor Copyright 2014 Zbigniew Jędrzejewski-Szmek
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor systemd is free software; you can redistribute it and/or modify it
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor under the terms of the GNU Lesser General Public License as published by
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor the Free Software Foundation; either version 2.1 of the License, or
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor (at your option) any later version.
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor systemd is distributed in the hope that it will be useful, but
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor WITHOUT ANY WARRANTY; without even the implied warranty of
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor Lesser General Public License for more details.
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor You should have received a copy of the GNU Lesser General Public License
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor along with systemd; If not, see <http://www.gnu.org/licenses/>.
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <refentryinfo>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <authorgroup>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </authorgroup>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refentryinfo>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <refnamediv>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refnamediv>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <refsynopsisdiv>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcsynopsis>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcprototype>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcdef>int <function>sd_bus_new</function></funcdef>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </funcprototype>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcprototype>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </funcprototype>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcprototype>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
49e0808304aa03348896a20c69a03e895cc20beelgentis <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </funcprototype>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </funcsynopsis>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refsynopsisdiv>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <para><function>sd_bus_new()</function> creates a new bus
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis object. This object is reference-counted, and will be destroyed
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis when all references are gone. Initially, the caller of this
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor function owns the sole reference and the bus object will not be
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis connected to any bus. To connect it to a bus, make sure
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis to set an address with
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis or a related call, and then start the connection with
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis <para>In most cases, it is a better idea to invoke
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor or related calls instead of the more low-level
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <function>sd_bus_start()</function>. The higher-level calls not
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor only allocate a bus object but also start the connection to a
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis well-known bus in a single function invocation.</para>
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis <para><function>sd_bus_ref()</function> creates a new reference to
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis <para><function>sd_bus_unref()</function> destroys a reference to
92a7702da86bfc911826050b5c6f6593d3fa3ff5lgentis <parameter>bus</parameter>. Once the reference count has dropped
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor to zero, <parameter>bus</parameter> cannot be used anymore, so
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor further calls to <function>sd_bus_ref()</function> or
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <function>sd_bus_unref()</function> are illegal.</para>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refsect1>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <para>On success, <function>sd_bus_new()</function> returns 0 or a
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor positive integer. On failure, it returns a negative errno-style
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor error code.</para>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <para><function>sd_bus_ref</function> always returns the argument.
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <para><function>sd_bus_unref</function> always returns
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refsect1>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <para>Returned errors may indicate the following problems:</para>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <variablelist>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <varlistentry>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <listitem><para>Memory allocation failed.</para></listitem>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </varlistentry>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </variablelist>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refsect1>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <para><function>sd_bus_new()</function> and other functions
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor described here are available as a shared library, which can be
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor compiled and linked to with the
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor file.</para>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refsect1>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
ad2457b31e661c56befa8291e86ac72a3ad53926gryzor </refsect1>