man/sd_bus_new.xml

   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" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_bus_new">
  28
  29   <refentryinfo>
  30     <title>sd_bus_new</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>A monkey with a typewriter</contrib>
  36         <firstname>Zbigniew</firstname>
  37         <surname>Jędrzejewski-Szmek</surname>
  38         <email>zbyszek@in.waw.pl</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_bus_new</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_bus_new</refname>
  50     <refname>sd_bus_ref</refname>
  51     <refname>sd_bus_unref</refname>
  52
  53     <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
  54   </refnamediv>
  55
  56   <refsynopsisdiv>
  57     <funcsynopsis>
  58       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_bus_new</function></funcdef>
  62         <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>sd_bus *<function>sd_bus_ref</function></funcdef>
  67         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  68       </funcprototype>
  69
  70       <funcprototype>
  71         <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
  72         <paramdef>sd_bus *<parameter>bus</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.</para>
  84
  85     <para><function>sd_bus_ref()</function> creates a new reference to
  86     <parameter>bus</parameter>. This bus object will not be destroyed
  87     until <function>sd_bus_unref()</function> has been called as many
  88     times plus once more. Once the reference count has dropped to
  89     zero, <parameter>bus</parameter> cannot be used anymore, so
  90     further calls to <function>sd_bus_ref()</function> or
  91     <function>sd_bus_unref()</function> are illegal.</para>
  92
  93     <para><function>sd_bus_unref()</function> destroys a reference to
  94     <parameter>bus</parameter>.</para>
  95   </refsect1>
  96
  97   <refsect1>
  98     <title>Return Value</title>
  99
 100     <para>On success, <function>sd_bus_new()</function> returns 0 or a
 101     positive integer. On failure, it returns a negative errno-style
 102     error code.</para>
 103
 104     <para><function>sd_bus_ref</function> always returns the argument.
 105     </para>
 106
 107     <para><function>sd_bus_unref</function> always returns
 108     <constant>NULL</constant>.</para>
 109   </refsect1>
 110
 111   <refsect1>
 112     <title>Errors</title>
 113
 114     <para>Returned errors may indicate the following problems:</para>
 115
 116     <variablelist>
 117       <varlistentry>
 118         <term><constant>-ENOMEM</constant></term>
 119
 120         <listitem><para>Memory allocation failed.</para></listitem>
 121       </varlistentry>
 122     </variablelist>
 123   </refsect1>
 124
 125   <refsect1>
 126     <title>Notes</title>
 127
 128     <para><function>sd_bus_new()</function> and other functions
 129     described here are available as a shared library, which can be
 130     compiled and linked to with the
 131     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 132     file.</para>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>See Also</title>
 137
 138     <para>
 139       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 140       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 143       <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 144       <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 145     </para>
 146   </refsect1>
 147
 148 </refentry>