picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge pull request #10711 from poettering/sd-bus-close-man

Browse source 
sd-bus: add docs for a couple of sd-bus APIs
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-11-09 20:46:45 +01:00 committed by GitHub
parent 067e995c72 48c3512269
commit 826bc13135
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 253 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
man/rules/meson.build
View file

@ -114,6 +114,8 @@ manpages = [
'sd_bus_match_signal',
'sd_bus_match_signal_async'],
''],
['sd_bus_attach_event', '3', ['sd_bus_detach_event', 'sd_bus_get_event'], ''],
['sd_bus_close', '3', ['sd_bus_flush'], ''],
['sd_bus_creds_get_pid',
'3',
['sd_bus_creds_get_audit_login_uid',
@ -271,7 +273,14 @@ manpages = [
'3',
['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'],
''],
['sd_bus_new', '3', ['sd_bus_ref', 'sd_bus_unref', 'sd_bus_unrefp'], ''],
['sd_bus_new',
'3',
['sd_bus_flush_close_unref',
'sd_bus_flush_close_unrefp',
'sd_bus_ref',
'sd_bus_unref',
'sd_bus_unrefp'],
''],
['sd_bus_path_encode',
'3',
['sd_bus_path_decode', 'sd_bus_path_decode_many', 'sd_bus_path_encode_many'],

1
man/sd-bus.xml
View file

@ -44,6 +44,7 @@
<para>See
<literallayout><citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_creds_new_from_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

114
man/sd_bus_attach_event.xml Normal file
View file

@ -0,0 +1,114 @@
<?xml version='1.0'?>
<!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+
-->
<refentry id="sd_bus_attach_event"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_attach_event</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_attach_event</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_attach_event</refname>
<refname>sd_bus_detach_event</refname>
<refname>sd_bus_get_event</refname>
<refpurpose>Attach a bus connection object to an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_attach_event</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_event *<parameter>e</parameter></paramdef>
<paramdef>int <parameter>priority</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_detach_event</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_event *<function>sd_bus_get_event</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_attach_event()</function> attaches the specified bus connection object to an
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry> event loop object at
the specified priority (see
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for details on event loop priorities). When a bus connection object is attached to an event loop incoming messages
will be automatically read and processed, and outgoing messages written, whenever the event loop is run. When the
event loop is about to terminate, the bus connection is automatically flushed and closed (see
<citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
details on this). By default bus connection objects are not attached to any event loop. When a bus connection
object is attached to one it is not necessary to invoke
<citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
<citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> as this
functionality is handled automatically by the event loop.</para>
<para><function>sd_bus_detach_event()</function> detaches a bus object from its event loop.</para>
<para>The <function>sd_bus_get_event()</function> returns the event loop object the specified bus object is
currently attached to, or <constant>NULL</constant> if it is currently not attached to any.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_bus_attach_event()</function> and <function>sd_bus_detach_event()</function> return
0 or a positive integer. On failure, they return a negative errno-style error code.</para>
<para><function>sd_bus_get_event()</function> returns an event loop object or <constant>NULL</constant>.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<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-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

101
man/sd_bus_close.xml Normal file
View file

@ -0,0 +1,101 @@
<?xml version='1.0'?>
<!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+
-->
<refentry id="sd_bus_close"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_close</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_close</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_close</refname>
<refname>sd_bus_flush</refname>
<refpurpose>Close and flush a bus connection</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>sd_bus_close</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_flush</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_close()</function> disconnects the specified bus connection. When this call is invoked and
the specified bus object refers to an active connection it is immediately terminated. No further messages may be
sent or receieved on it. Any messages queued in the bus object (both incoming and outgoing) are released. If
invoked on <constant>NULL</constant> bus object or when the bus connection is already closed this function executes
no operation. This call does not free or unreference the bus object itself. Use
<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> for that.</para>
<para><function>sd_bus_flush()</function> synchronously writes out all outgoing queued message on a bus connection
if there are any. This function call may block if the peer is not processing bus messages quickly.</para>
<para>Before a program exits it is usually a good idea to flush any pending messages with
<function>sd_bus_flush()</function> and then close connections with <function>sd_bus_close()</function> to ensure
that no unwritten messages are lost, no further messages may be queued and all incoming but unprocessed messages
are released. After both operations have been done, it is a good idea to also drop any remaining references to the
bus object so that it may be freed. Since these three operations are frequently done together a helper call
<citerefentry><refentrytitle>sd_bus_flush_close_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> is
provided that combines them into one.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_bus_flush()</function> returns 0 or a positive integer. On failure, it returns a
negative errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<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_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

29
man/sd_bus_new.xml
View file

@ -23,6 +23,8 @@
<refname>sd_bus_ref</refname>
<refname>sd_bus_unref</refname>
<refname>sd_bus_unrefp</refname>
<refname>sd_bus_flush_close_unref</refname>
<refname>sd_bus_flush_close_unrefp</refname>
<refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
</refnamediv>
@ -50,6 +52,16 @@
<funcdef>void <function>sd_bus_unrefp</function></funcdef>
<paramdef>sd_bus **<parameter>busp</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef>
<paramdef>sd_bus **<parameter>busp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
@ -111,6 +123,18 @@
dereference its argument, which must not be <constant>NULL</constant>, and will
execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>.
</para>
<para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but first
executes <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well
as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, ensuring that
any pending messages are properly flushed out before the reference to the connection is dropped and possibly the
object freed. This call is particularly useful immediately before exiting from a program as it ensures that any
pending outgoing messages are written out, and unprocessed but queued incoming messages released before the
connection is terminated and released.</para>
<para><function>sd_bus_flush_close_unrefp()</function> is similar to
<function>sd_bus_flush_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable Attribute,
see above.</para>
</refsect1>
<refsect1>
@ -123,7 +147,7 @@
<para><function>sd_bus_ref()</function> always returns the argument.
</para>
<para><function>sd_bus_unref()</function> always returns
<para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return
<constant>NULL</constant>.</para>
</refsect1>
@ -152,7 +176,8 @@
<citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>