mirror of
https://github.com/systemd/systemd.git
synced 2024-12-25 01:34:28 +03:00
11a1589223
Files which are installed as-is (any .service and other unit files, .conf files, .policy files, etc), are left as is. My assumption is that SPDX identifiers are not yet that well known, so it's better to retain the extended header to avoid any doubt. I also kept any copyright lines. We can probably remove them, but it'd nice to obtain explicit acks from all involved authors before doing that.
253 lines
12 KiB
XML
253 lines
12 KiB
XML
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||
|
||
<!--
|
||
SPDX-License-Identifier: LGPL-2.1+
|
||
|
||
This file is part of systemd.
|
||
|
||
Copyright 2016 Lennart Poettering
|
||
-->
|
||
|
||
<refentry id="sd_bus_track_new">
|
||
|
||
<refentryinfo>
|
||
<title>sd_bus_track_new</title>
|
||
<productname>systemd</productname>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<contrib>Developer</contrib>
|
||
<firstname>Lennart</firstname>
|
||
<surname>Poettering</surname>
|
||
<email>lennart@poettering.net</email>
|
||
</author>
|
||
</authorgroup>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>sd_bus_track_new</refentrytitle>
|
||
<manvolnum>3</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>sd_bus_track_new</refname>
|
||
<refname>sd_bus_track_ref</refname>
|
||
<refname>sd_bus_track_unref</refname>
|
||
<refname>sd_bus_track_unrefp</refname>
|
||
<refname>sd_bus_track_set_recursive</refname>
|
||
<refname>sd_bus_track_get_recursive</refname>
|
||
<refname>sd_bus_track_get_bus</refname>
|
||
<refname>sd_bus_track_get_userdata</refname>
|
||
<refname>sd_bus_track_set_userdata</refname>
|
||
|
||
<refpurpose>Track bus peers</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<funcsynopsis>
|
||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||
|
||
<funcprototype>
|
||
<funcdef>int <function>sd_bus_track_new</function></funcdef>
|
||
<paramdef>sd_bus* <parameter>bus</parameter></paramdef>
|
||
<paramdef>sd_bus_track** <parameter>ret</parameter></paramdef>
|
||
<paramdef>sd_bus_track_handler_t <parameter>handler</parameter></paramdef>
|
||
<paramdef>void* <parameter>userdata</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>sd_bus_track *<function>sd_bus_track_ref</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>sd_bus_track *<function>sd_bus_track_unref</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>void <function>sd_bus_track_unrefp</function></funcdef>
|
||
<paramdef>sd_bus_track **<parameter>t</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>int <function>sd_bus_track_get_recursive</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>int <function>sd_bus_track_set_recursive</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
<paramdef>int <parameter>b</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>sd_bus* <function>sd_bus_track_get_bus</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>void* <function>sd_bus_track_get_userdata</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
</funcprototype>
|
||
|
||
<funcprototype>
|
||
<funcdef>void* <function>sd_bus_track_set_userdata</function></funcdef>
|
||
<paramdef>sd_bus_track *<parameter>t</parameter></paramdef>
|
||
<paramdef>void *userdata</paramdef>
|
||
</funcprototype>
|
||
|
||
</funcsynopsis>
|
||
</refsynopsisdiv>
|
||
|
||
<refsect1>
|
||
<title>Description</title>
|
||
|
||
<para><function>sd_bus_track_new()</function> creates a new bus peer tracking object. The object is allocated for
|
||
the specified bus, and returned in the <parameter>*ret</parameter> parameter. After use, the object should be freed
|
||
again by dropping the acquired reference with <function>sd_bus_track_unref()</function> (see below). A bus peer
|
||
tracking object may be used to keep track of peers on a specific IPC bus, for cases where peers are making use of
|
||
one or more local objects, in order to control the lifecycle of the local objects and ensure they stay around as
|
||
long as the peers needing them are around, and unreferenced (and possibly destroyed) as soon as all relevant peers
|
||
have vanished. Each bus peer tracking object may be used to track zero, one or more peers add a time. References to
|
||
specific bus peers are added via
|
||
<citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
|
||
<function>sd_bus_track_add_sender()</function>. They may be dropped again via
|
||
<function>sd_bus_track_remove_name()</function> and
|
||
<function>sd_bus_track_remove_sender()</function>. Alternatively, references on peers are removed automatically
|
||
when they disconnect from the bus. If non-NULL the <parameter>handler</parameter> may specify a function that is
|
||
invoked whenever the last reference is dropped, regardless whether the reference is dropped explicitly via
|
||
<function>sd_bus_track_remove_name()</function> or implicitly because the peer disconnected from the bus. The final
|
||
argument <parameter>userdata</parameter> may be used to attach a generic user data pointer to the object. This
|
||
pointer is passed to the handler callback when it is invoked.</para>
|
||
|
||
<para><function>sd_bus_track_ref()</function> creates a new reference to a bus peer tracking object. This object
|
||
will not be destroyed until <function>sd_bus_track_unref()</function> has been called as many times plus once
|
||
more. Once the reference count has dropped to zero, the specified object cannot be used anymore, further calls to
|
||
<function>sd_bus_track_ref()</function> or <function>sd_bus_track_unref()</function> on the same object are
|
||
illegal.</para>
|
||
|
||
<para><function>sd_bus_track_unref()</function> destroys a reference to a bus peer tracking object.</para>
|
||
|
||
<para><function>sd_bus_track_unrefp()</function> is similar to <function>sd_bus_track_unref()</function> but takes
|
||
a pointer to a pointer to an <type>sd_bus_track</type> object. This call is useful in conjunction with GCC's and
|
||
LLVM's <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable
|
||
Attribute</ulink>. Note that this function is defined as inline function.</para>
|
||
|
||
<para><function>sd_bus_track_ref()</function>, <function>sd_bus_track_unref()</function> and
|
||
<function>sd_bus_track_unrefp()</function> execute no operation if the passed in bus peer tracking object is
|
||
<constant>NULL</constant>.</para>
|
||
|
||
<para>Bus peer tracking objects may exist in two modes: by default they operate in non-recursive mode, but may
|
||
optionally be switched into recursive mode. If operating in the default non-recursive mode a peer is either tracked
|
||
or not tracked. In this mode invoking <function>sd_bus_track_add_name()</function> multiple times in a row for the
|
||
same peer is fully equivalent to calling it just once, as the call adds the peer to the set of tracked peers if
|
||
necessary, and executes no operation if the peer is already being tracked. A single invocation of
|
||
<function>sd_bus_track_remove_name()</function> removes the reference on the peer again, regardless how many times
|
||
<function>sd_bus_track_add_name()</function> was called before. If operating in recursive mode, the number of times
|
||
<function>sd_bus_track_add_name()</function> is invoked for the same peer name is counted and
|
||
<function>sd_bus_track_remove_name()</function> must be called the same number of times before the peer is not
|
||
tracked anymore, with the exception when the tracked peer vanishes from the bus, in which case the count is
|
||
irrelevant and the tracking of the specific peer is immediately
|
||
removed. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking
|
||
object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or
|
||
disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and
|
||
<function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to
|
||
zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It
|
||
takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which
|
||
<function>sd_bus_track_add_name()</function> was already invoked at least once (and which hence track already one
|
||
or more peers) may not be switched from recursive to non-recursive mode anymore.</para>
|
||
|
||
<para><function>sd_bus_track_get_bus()</function> returns the bus object the bus peer tracking object belongs
|
||
to. It returns the bus object initially passed to <function>sd_bus_track_new()</function> when the object was
|
||
allocated.</para>
|
||
|
||
<para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer set on the bus peer
|
||
tracking object at the time of creation using <function>sd_bus_track_new()</function> or at a later time, using
|
||
<function>sd_bus_track_set_userdata()</function>.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Return Value</title>
|
||
|
||
<para>On success, <function>sd_bus_track_new()</function> and <function>sd_bus_track_set_recursive()</function>
|
||
return 0 or a positive integer. On failure, they return a negative errno-style error code.</para>
|
||
|
||
<para><function>sd_bus_track_ref()</function> always returns the argument.</para>
|
||
|
||
<para><function>sd_bus_track_unref()</function> always returns <constant>NULL</constant>.</para>
|
||
|
||
<para><function>sd_bus_track_get_recursive()</function> returns 0 if non-recursive mode is selected (default), and
|
||
greater than 0 if recursive mode is selected. On failure a negative errno-style error code is returned.</para>
|
||
|
||
<para><function>sd_bus_track_get_bus()</function> returns the bus object associated to the bus peer tracking
|
||
object.</para>
|
||
|
||
<para><function>sd_bus_track_get_userdata()</function> returns the generic user data pointer associated with the
|
||
bus peer tracking object. <function>sd_bus_track_set_userdata()</function> returns the previous user data pointer
|
||
set.</para>
|
||
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Reference ownership</title>
|
||
|
||
<para>The <function>sd_bus_track_new()</function> function creates a new object and the caller owns the sole
|
||
reference. When not needed anymore, this reference should be destroyed with
|
||
<function>sd_bus_track_unref()</function>.
|
||
</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Errors</title>
|
||
|
||
<para>Returned errors may indicate the following problems:</para>
|
||
|
||
<variablelist>
|
||
|
||
<varlistentry>
|
||
<term><constant>-EBUSY</constant></term>
|
||
|
||
<listitem><para>Bus peers have already been added to the bus peer tracking object and
|
||
<function>sd_bus_track_set_recursive()</function> was called to change tracking mode.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><constant>-EINVAL</constant></term>
|
||
|
||
<listitem><para>Specified parameter is invalid
|
||
(<constant>NULL</constant> in case of output
|
||
parameters).</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><constant>-ENOMEM</constant></term>
|
||
|
||
<listitem><para>Memory allocation failed.</para></listitem>
|
||
</varlistentry>
|
||
|
||
</variablelist>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Notes</title>
|
||
|
||
<para><function>sd_bus_track_new()</function> and the other calls described here are available as a shared library,
|
||
which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
|
||
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>See Also</title>
|
||
|
||
<para>
|
||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
<citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||
</para>
|
||
</refsect1>
|
||
|
||
</refentry>
|