mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-24 02:33:36 +08:00
Code Issues Packages Projects Releases Wiki Activity
a61869d4a5
systemd/man/sd_bus_track_new.xml

245 lines
12 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 05:15:39 +08:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: use same version in public and system ident.
2023-12-25 22:48:33 +08:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: xinclude the generic text to talk about libsystemd pkgconfig The only difference is that functions are not individually listed by name, but that seems completely pointless, since all functions that are documented are always exported, so the generic text tells the user all she or he needs to know.
2018-06-06 17:59:04 +08:00
<refentry id="sd_bus_track_new" xmlns:xi="http://www.w3.org/2001/XInclude">
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
<refentryinfo>
<title>sd_bus_track_new</title>
<productname>systemd</productname>
</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 &lt;systemd/sd-bus.h&gt;</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
man: set constant tag to NUL or NULL
2020-11-12 15:58:00 +08:00
when they disconnect from the bus. If non-<constant>NULL</constant> 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>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
<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>
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<refsect2>
<title>Errors</title>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<para>Returned errors may indicate the following problems:</para>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<variablelist>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-EBUSY</constant></term>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<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>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-EINVAL</constant></term>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>Specified parameter is invalid
(<constant>NULL</constant> in case of output
parameters).</para></listitem>
</varlistentry>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ENOMEM</constant></term>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>Memory allocation failed.</para></listitem>
</varlistentry>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
</variablelist>
</refsect2>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
</refsect1>
man: xinclude the generic text to talk about libsystemd pkgconfig The only difference is that functions are not individually listed by name, but that seems completely pointless, since all functions that are documented are always exported, so the generic text tells the user all she or he needs to know.
2018-06-06 17:59:04 +08:00
<xi:include href="libsystemd-pkgconfig.xml" />
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
man: add version information for functions
2023-09-04 20:46:35 +08:00
<refsect1>
<title>History</title>
man: condense version information for functions Use a more compact form like 'a, b, and c were added in version x'
2023-09-19 00:44:26 +08:00
<para><function>sd_bus_track_new()</function>,
<function>sd_bus_track_ref()</function>,
<function>sd_bus_track_unref()</function>,
<function>sd_bus_track_unrefp()</function>,
<function>sd_bus_track_get_recursive()</function>,
<function>sd_bus_track_set_recursive()</function>,
<function>sd_bus_track_get_bus()</function>,
<function>sd_bus_track_get_userdata()</function>, and
<function>sd_bus_track_set_userdata()</function> were added in version 232.</para>
man: add version information for functions
2023-09-04 20:46:35 +08:00
</refsect1>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
<refsect1>
<title>See Also</title>
man: use <simplelist> for 'See also' sections This is just a slight markup improvement; there should be no difference in rendering.
2023-12-23 02:09:32 +08:00
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
</simplelist></para>
man: document sd_bus_track objects And while ware at it, also drop some references to kdbus, and stop claiming sd-bus wasn't stable yet. Also order man page references in the main sd-bus man page alphabetically.
2016-08-15 20:59:59 +08:00
</refsect1>
</refentry>
Reference in New Issue Copy Permalink