Merge pull request #9530 from keszybz/sd-bus-doc
More documentation for sd-bus
This commit is contained in:
Lennart Poettering
+2
-2
@@ -117,8 +117,8 @@ systemd_index_xml = custom_target(
|
||||
output : 'systemd.index.xml',
|
||||
command : [make_man_index_py, '@OUTPUT@'] + nonindex_xml_files)
|
||||
|
||||
foreach tuple : want_man or want_html ? [['systemd.directives', '7', systemd_directives_xml],
|
||||
['systemd.index', '7', systemd_index_xml]] : []
|
||||
foreach tuple : xsltproc.found() ? [['systemd.directives', '7', systemd_directives_xml],
|
||||
['systemd.index', '7', systemd_index_xml]] : []
|
||||
stem = tuple[0]
|
||||
section = tuple[1]
|
||||
xml = tuple[2]
|
||||
|
||||
@@ -204,11 +204,18 @@ manpages = [
|
||||
['sd_bus_message_append_string_iovec', 'sd_bus_message_append_string_space'],
|
||||
''],
|
||||
['sd_bus_message_append_strv', '3', [], ''],
|
||||
['sd_bus_message_copy', '3', [], ''],
|
||||
['sd_bus_message_get_cookie', '3', ['sd_bus_message_get_reply_cookie'], ''],
|
||||
['sd_bus_message_get_monotonic_usec',
|
||||
'3',
|
||||
['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'],
|
||||
''],
|
||||
['sd_bus_message_new_method_error',
|
||||
'3',
|
||||
['sd_bus_message_new_method_errno',
|
||||
'sd_bus_message_new_method_errnof',
|
||||
'sd_bus_message_new_method_errorf'],
|
||||
''],
|
||||
['sd_bus_message_read', '3', ['sd_bus_message_readv'], ''],
|
||||
['sd_bus_message_read_basic', '3', [], ''],
|
||||
['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''],
|
||||
@@ -222,6 +229,12 @@ manpages = [
|
||||
['sd_bus_path_decode', 'sd_bus_path_decode_many', 'sd_bus_path_encode_many'],
|
||||
''],
|
||||
['sd_bus_process', '3', [], ''],
|
||||
['sd_bus_reply_method_error',
|
||||
'3',
|
||||
['sd_bus_reply_method_errno',
|
||||
'sd_bus_reply_method_errnof',
|
||||
'sd_bus_reply_method_errorf'],
|
||||
''],
|
||||
['sd_bus_request_name',
|
||||
'3',
|
||||
['sd_bus_release_name',
|
||||
@@ -229,6 +242,14 @@ manpages = [
|
||||
'sd_bus_request_name_async'],
|
||||
''],
|
||||
['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''],
|
||||
['sd_bus_set_description',
|
||||
'3',
|
||||
['sd_bus_get_allow_interactive_authorization',
|
||||
'sd_bus_get_description',
|
||||
'sd_bus_set_allow_interactive_authorization',
|
||||
'sd_bus_set_anonymous',
|
||||
'sd_bus_set_trusted'],
|
||||
''],
|
||||
['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''],
|
||||
['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
|
||||
['sd_bus_slot_set_destroy_callback',
|
||||
|
||||
+36
-28
@@ -43,34 +43,42 @@
|
||||
</para>
|
||||
|
||||
<para>See
|
||||
<citerefentry><refentrytitle>sd-bus-errors</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>,
|
||||
<citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_allow_interactive_authorization</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
<citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<literallayout><citerefentry><refentrytitle>sd_bus_add_match</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>,
|
||||
<citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_get_n_queued_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_array</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_string_memfd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_strv</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_copy</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_get_cookie</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_message_set_destination</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_negotiate_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_path_encode</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
<citerefentry><refentrytitle>sd_bus_set_slot_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_set_slot_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_track_add_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||
<citerefentry><refentrytitle>sd_bus_track_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
</literallayout>
|
||||
for more information about the functions available.</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
@@ -0,0 +1,115 @@
|
||||
<?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_message_copy" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_message_copy</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_message_copy</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_message_copy</refname>
|
||||
|
||||
<refpurpose>Copy the contents of one message to another</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_message_copy</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
|
||||
<paramdef>sd_bus_message *<parameter>source</parameter></paramdef>
|
||||
<paramdef>int <parameter>all</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><function>sd_bus_message_copy()</function> copies the contents from
|
||||
message <parameter>source</parameter> to <parameter>m</parameter>. If
|
||||
<parameter>all</parameter> is false, a single complete type is copied
|
||||
(basic or container). If <parameter>all</parameter> is true, the contents
|
||||
are copied until the end of the currently open container or the end
|
||||
of <parameter>source</parameter>.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>On success, this call returns true if anything was copied, and false if
|
||||
there was nothing to copy. On failure, it returns a negative errno-style error
|
||||
code.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id='errors'>
|
||||
<title>Errors</title>
|
||||
|
||||
<para>Returned errors may indicate the following problems:</para>
|
||||
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-EINVAL</constant></term>
|
||||
|
||||
<listitem><para><parameter>source</parameter> or <parameter>m</parameter> are
|
||||
<constant>NULL</constant>.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-EPERM</constant></term>
|
||||
|
||||
<listitem><para>Message <parameter>m</parameter> has been sealed or
|
||||
<parameter>source</parameter> has <emphasis>not</emphasis> been sealed.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ESTALE</constant></term>
|
||||
|
||||
<listitem><para>Destination message is in invalid state.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ENXIO</constant></term>
|
||||
|
||||
<listitem><para>Destination message cannot be appended to.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ENOMEM</constant></term>
|
||||
|
||||
<listitem><para>Memory allocation failed.</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_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@@ -0,0 +1,190 @@
|
||||
<?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_message_new_method_error"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_message_new_method_error</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_message_new_method_error</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_message_new_method_error</refname>
|
||||
<refname>sd_bus_message_new_method_errorf</refname>
|
||||
<refname>sd_bus_message_new_method_errno</refname>
|
||||
<refname>sd_bus_message_new_method_errnof</refname>
|
||||
|
||||
<refpurpose>Create a an error reply for a method call</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_message_new_method_error</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
|
||||
<paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_message_new_method_errorf</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>name</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>format</parameter></paramdef>
|
||||
<paramdef>…</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_message_new_method_errno</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
|
||||
<paramdef>int <parameter>error</parameter></paramdef>
|
||||
<paramdef>const sd_bus_error *<parameter>p</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_message_new_method_errnof</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
|
||||
<paramdef>int <parameter>error</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>format</parameter></paramdef>
|
||||
<paramdef>…</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>The <function>sd_bus_message_new_method_error()</function> function creates
|
||||
a new bus message object that is an error reply to the
|
||||
<parameter>call</parameter> message, and returns it in the
|
||||
<parameter>m</parameter> output parameter. The error information from error
|
||||
<parameter>e</parameter> is appended: the <parameter>name</parameter> field of
|
||||
<parameter>e</parameter> is used as the error identifier in the reply header (for
|
||||
example an error name such as
|
||||
<literal>org.freedesktop.DBus.Error.NotSupported</literal> or the equivalent
|
||||
symbolic <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant>), and the
|
||||
<parameter>message</parameter> field is set as the human readable error message
|
||||
string if present. The error <parameter>e</parameter> must have the
|
||||
<parameter>name</parameter> field set, see
|
||||
<citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>The <function>sd_bus_message_new_method_errorf()</function> function
|
||||
creates an error reply similarly to
|
||||
<function>sd_bus_message_new_method_error()</function>, but instead of a ready
|
||||
error structure, it takes an error identifier string <parameter>name</parameter>,
|
||||
plus a <citerefentry
|
||||
project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
format string <parameter>format</parameter> and corresponding arguments. An error
|
||||
reply is sent with the error identifier <parameter>name</parameter> and the
|
||||
formatted string as the message. <parameter>name</parameter> and
|
||||
<parameter>format</parameter> must not be <constant>NULL</constant>.
|
||||
</para>
|
||||
|
||||
<para>The <function>sd_bus_message_new_method_errno()</function> function creates
|
||||
an error reply similarly to
|
||||
<function>sd_bus_message_new_method_error()</function>, but in addition to the
|
||||
error structure <parameter>p</parameter>, it takes an
|
||||
<citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
error value in parameter <parameter>error</parameter>. If the error
|
||||
<parameter>p</parameter> is set (see
|
||||
<citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>),
|
||||
it is used in the reply. Otherwise, <parameter>error</parameter> is translated to
|
||||
an error identifier and used to create a new error structure using
|
||||
<citerefentry><refentrytitle>sd_bus_error_set_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
and that is used in the reply. (If <parameter>error</parameter> is zero, no error
|
||||
is actually set, and an error reply with no information is created.)</para>
|
||||
|
||||
<para>The <function>sd_bus_message_new_method_errnof()</function> function
|
||||
creates an error reply similarly to
|
||||
<function>sd_bus_message_new_method_error()</function>. It takes an
|
||||
<citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
error value in parameter <parameter>error</parameter>, plus a <citerefentry
|
||||
project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
format string <parameter>format</parameter> and corresponding arguments.
|
||||
<literal>%m</literal> may be used in the format string to refer to the error
|
||||
string corresponding to the specified errno code. The error message is initalized
|
||||
using the error identifier generated from <constant>error</constant> and the
|
||||
formatted string. (If <parameter>error</parameter> is zero, no error is actually
|
||||
set, and an error reply with no information is created.)</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>These functions return 0 if the error reply was successfully created, and a
|
||||
negative errno-style error code otherwise.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id='errors'>
|
||||
<title>Errors</title>
|
||||
|
||||
<para>Returned errors may indicate the following problems:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><constant>-EINVAL</constant></term>
|
||||
|
||||
<listitem><para>The call message <parameter>call</parameter> or the output
|
||||
parameter <parameter>m</parameter> are <constant>NULL</constant>.</para>
|
||||
|
||||
<para>Message <parameter>call</parameter> is not a method call
|
||||
message.</para>
|
||||
|
||||
<para>The error <parameter>error</parameter> parameter to
|
||||
<function>sd_bus_message_new_method_error</function> is not set, see
|
||||
<citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-EPERM</constant></term>
|
||||
|
||||
<listitem><para>Message <parameter>call</parameter> has been sealed.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ENOTCONN</constant></term>
|
||||
|
||||
<listitem><para>The bus to which message <parameter>call</parameter> is
|
||||
attached is not connected.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ENOMEM</constant></term>
|
||||
|
||||
<listitem><para>Memory allocation failed.</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>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@@ -0,0 +1,161 @@
|
||||
<?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_reply_method_error"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_reply_method_error</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_reply_method_error</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_reply_method_error</refname>
|
||||
<refname>sd_bus_reply_method_errorf</refname>
|
||||
<refname>sd_bus_reply_method_errno</refname>
|
||||
<refname>sd_bus_reply_method_errnof</refname>
|
||||
|
||||
<refpurpose>Reply with an error to a method call</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_reply_method_error</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_reply_method_errorf</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>name</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>format</parameter></paramdef>
|
||||
<paramdef>…</paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_reply_method_errno</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>int <parameter>error</parameter></paramdef>
|
||||
<paramdef>const sd_bus_error *<parameter>p</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int sd_bus_reply_method_errnof</funcdef>
|
||||
<paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
|
||||
<paramdef>int <parameter>error</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>format</parameter></paramdef>
|
||||
<paramdef>…</paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para>The <function>sd_bus_reply_method_error()</function> function sends an
|
||||
error reply to the <parameter>call</parameter> message. The error structure
|
||||
<parameter>e</parameter> specifies the error to send, and is used as described in
|
||||
<citerefentry><refentrytitle>sd_bus_message_new_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
If no reply is expected to <parameter>call</parameter>, this function returns
|
||||
success without sending reply.</para>
|
||||
|
||||
<para>The <function>sd_bus_reply_method_errorf()</function> is to
|
||||
<function>sd_bus_reply_method_error()</function> what
|
||||
<function>sd_bus_message_new_method_errorf()</function> is to
|
||||
<function>sd_bus_message_new_method_error()</function>.</para>
|
||||
|
||||
<para>The <function>sd_bus_reply_method_errno()</function> is to
|
||||
<function>sd_bus_reply_method_error()</function> what
|
||||
<function>sd_bus_message_new_method_errno()</function> is to
|
||||
<function>sd_bus_message_new_method_error()</function>.</para>
|
||||
|
||||
<para>The <function>sd_bus_reply_method_errnof()</function> is to
|
||||
<function>sd_bus_reply_method_error()</function> what
|
||||
<function>sd_bus_message_new_method_errnof()</function> is to
|
||||
<function>sd_bus_message_new_method_error()</function>.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>These functions return 0 if the error reply was successfully sent or if
|
||||
none was expected, and a negative errno-style error code otherwise.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id='errors'>
|
||||
<title>Errors</title>
|
||||
|
||||
<para>Returned errors may indicate the following problems:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><constant>-EINVAL</constant></term>
|
||||
|
||||
<listitem><para>The call message <parameter>call</parameter> is
|
||||
<constant>NULL</constant>.</para>
|
||||
|
||||
<para>Message <parameter>call</parameter> is not a method call message.
|
||||
</para>
|
||||
|
||||
<para>Message <parameter>call</parameter> is not attached to a bus.</para>
|
||||
|
||||
<para>The error <parameter>error</parameter> parameter to
|
||||
<function>sd_bus_reply_method_error</function> is not set, see
|
||||
<citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-EPERM</constant></term>
|
||||
|
||||
<listitem><para>Message <parameter>call</parameter> has been sealed.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ENOTCONN</constant></term>
|
||||
|
||||
<listitem><para>The bus to which message <parameter>call</parameter> is
|
||||
attached is not connected.</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><constant>-ENOMEM</constant></term>
|
||||
|
||||
<listitem><para>Memory allocation failed.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>In addition, any error message returned by
|
||||
<citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
may be returned.</para>
|
||||
</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_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@@ -0,0 +1,188 @@
|
||||
<?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_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd_bus_set_description</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd_bus_set_description</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd_bus_set_description</refname>
|
||||
<refname>sd_bus_get_description</refname>
|
||||
<refname>sd_bus_set_anonymous</refname>
|
||||
<refname>sd_bus_set_trusted</refname>
|
||||
<refname>sd_bus_set_allow_interactive_authorization</refname>
|
||||
<refname>sd_bus_get_allow_interactive_authorization</refname>
|
||||
|
||||
<refpurpose>Set or query properties of a bus object</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_set_description</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>const char *<parameter>description</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_get_description</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>const char **<parameter>description</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_set_anonymous</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>int <parameter>b</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_set_trusted</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>int <parameter>b</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
<paramdef>int <parameter>b</parameter></paramdef>
|
||||
</funcprototype>
|
||||
|
||||
<funcprototype>
|
||||
<funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef>
|
||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><function>sd_bus_set_description()</function> sets the description string
|
||||
that is used in logging to the specified string. The string is copied internally
|
||||
and freed when the bus object is deallocated. The
|
||||
<parameter>description</parameter> argument may be <constant>NULL</constant>, in
|
||||
which case the description is unset. This function must be called before the bus
|
||||
has been started.</para>
|
||||
|
||||
<para><function>sd_bus_get_description()</function> returns a description string
|
||||
in <parameter>description</parameter>. This string may have been previously set
|
||||
with <function>sd_bus_set_description()</function> or
|
||||
<citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
or similar. If not set this way, a default string like <literal>system</literal>
|
||||
or <literal>user</literal> will be returned for the system or user buses,
|
||||
and <constant>NULL</constant> otherwise.</para>
|
||||
|
||||
<para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous
|
||||
authentication", i.e. lack of authentication, of the bus peer. This function must
|
||||
be called before the bus has been started. See the <ulink
|
||||
url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">Authentication
|
||||
Mechanisms</ulink> section of the D-Bus specification for details.</para>
|
||||
|
||||
<para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the
|
||||
<parameter>bus</parameter> object. If true, all connections on the bus are
|
||||
trusted and access to all privileged and unprivileged methods is granted. This
|
||||
function must be called before the bus has been started.</para>
|
||||
|
||||
<para><function>sd_bus_set_allow_interactive_authorization()</function>
|
||||
enables or disables interactive authorization for method calls. If true,
|
||||
messages are marked with the
|
||||
<constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the
|
||||
<ulink
|
||||
url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus</ulink>
|
||||
specification, informing the receiving side that the caller is prepared to
|
||||
wait for interactive authorization, which might take a considerable time to
|
||||
complete. If this flag is set, the user may be queried for passwords or
|
||||
confirmation via <ulink
|
||||
url="http://www.freedesktop.org/wiki/Software/polkit">polkit</ulink> or a
|
||||
similar framework.</para>
|
||||
|
||||
<para><function>sd_bus_get_allow_interactive_authorization()</function> returns
|
||||
true if interactive authorization is allowed and false if not.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Return Value</title>
|
||||
|
||||
<para>On success, these functions return 0 or a positive integer. On failure,
|
||||
they return 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>-EINVAL</constant></term>
|
||||
|
||||
<listitem><para>An argument is invalid.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><constant>-ENOPKG</constant></term>
|
||||
|
||||
<listitem><para>The bus cannot be resolved.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><constant>-EPERM</constant></term>
|
||||
|
||||
<listitem><para>The bus has already been started.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><constant>-ECHILD</constant></term>
|
||||
|
||||
<listitem><para>The bus was created in a different process.</para></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><constant>-ENOMEM</constant></term>
|
||||
|
||||
<listitem><para>Memory allocation failed.</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_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>
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@@ -45,8 +45,10 @@
|
||||
a session, then this ID is reused as the session ID. Otherwise, an independent session counter is
|
||||
used.</para></listitem>
|
||||
|
||||
<listitem><para>Providing PolicyKit-based access for users for
|
||||
operations such as system shutdown or sleep</para></listitem>
|
||||
<listitem><para>Providing <ulink
|
||||
url="http://www.freedesktop.org/wiki/Software/polkit">polkit</ulink>-based
|
||||
access for users for operations such as system shutdown or sleep</para>
|
||||
</listitem>
|
||||
|
||||
<listitem><para>Implementing a shutdown/sleep inhibition logic
|
||||
for applications</para></listitem>
|
||||
|
||||
Reference in New Issue
Block a user