1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="sd_bus_message_new_method_error"
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>sd_bus_message_new_method_error</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>sd_bus_message_new_method_error</refentrytitle>
16    <manvolnum>3</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>sd_bus_message_new_method_error</refname>
21    <refname>sd_bus_message_new_method_errorf</refname>
22    <refname>sd_bus_message_new_method_errno</refname>
23    <refname>sd_bus_message_new_method_errnof</refname>
24
25    <refpurpose>Create an error reply for a method call</refpurpose>
26  </refnamediv>
27
28  <refsynopsisdiv>
29    <funcsynopsis>
30      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
31
32      <funcprototype>
33        <funcdef>int sd_bus_message_new_method_error</funcdef>
34        <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
35        <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
36        <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
37      </funcprototype>
38
39      <funcprototype>
40        <funcdef>int sd_bus_message_new_method_errorf</funcdef>
41        <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
42        <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
43        <paramdef>const char *<parameter>name</parameter></paramdef>
44        <paramdef>const char *<parameter>format</parameter></paramdef>
45        <paramdef>…</paramdef>
46      </funcprototype>
47
48      <funcprototype>
49        <funcdef>int sd_bus_message_new_method_errno</funcdef>
50        <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
51        <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
52        <paramdef>int <parameter>error</parameter></paramdef>
53        <paramdef>const sd_bus_error *<parameter>p</parameter></paramdef>
54      </funcprototype>
55
56      <funcprototype>
57        <funcdef>int sd_bus_message_new_method_errnof</funcdef>
58        <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
59        <paramdef>sd_bus_message **<parameter>m</parameter></paramdef>
60        <paramdef>int <parameter>error</parameter></paramdef>
61        <paramdef>const char *<parameter>format</parameter></paramdef>
62        <paramdef>…</paramdef>
63      </funcprototype>
64    </funcsynopsis>
65  </refsynopsisdiv>
66
67  <refsect1>
68    <title>Description</title>
69
70    <para>The <function>sd_bus_message_new_method_error()</function> function creates
71    a new bus message object that is an error reply to the
72    <parameter>call</parameter> message, and returns it in the
73    <parameter>m</parameter> output parameter. The error information from error
74    <parameter>e</parameter> is appended: the <parameter>name</parameter> field of
75    <parameter>e</parameter> is used as the error identifier in the reply header (for
76    example an error name such as
77    <literal>org.freedesktop.DBus.Error.NotSupported</literal> or the equivalent
78    symbolic <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant>), and the
79    <parameter>message</parameter> field is set as the human readable error message
80    string if present. The error <parameter>e</parameter> must have the
81    <parameter>name</parameter> field set, see
82    <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
83    </para>
84
85    <para>The <function>sd_bus_message_new_method_errorf()</function> function
86    creates an error reply similarly to
87    <function>sd_bus_message_new_method_error()</function>, but instead of a ready
88    error structure, it takes an error identifier string <parameter>name</parameter>,
89    plus a <citerefentry
90    project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
91    format string <parameter>format</parameter> and corresponding arguments. An error
92    reply is sent with the error identifier <parameter>name</parameter> and the
93    formatted string as the message. <parameter>name</parameter> and
94    <parameter>format</parameter> must not be <constant>NULL</constant>.
95    </para>
96
97    <para>The <function>sd_bus_message_new_method_errno()</function> function creates
98    an error reply similarly to
99    <function>sd_bus_message_new_method_error()</function>, but in addition to the
100    error structure <parameter>p</parameter>, it takes an
101    <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
102    error value in parameter <parameter>error</parameter>. If the error
103    <parameter>p</parameter> is set (see
104    <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>),
105    it is used in the reply. Otherwise, <parameter>error</parameter> is translated to
106    an error identifier and used to create a new error structure using
107    <citerefentry><refentrytitle>sd_bus_error_set_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
108    and that is used in the reply. (If <parameter>error</parameter> is zero, no error
109    is actually set, and an error reply with no information is created.)</para>
110
111    <para>The <function>sd_bus_message_new_method_errnof()</function> function
112    creates an error reply similarly to
113    <function>sd_bus_message_new_method_error()</function>. It takes an
114    <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
115    error value in parameter <parameter>error</parameter>, plus a <citerefentry
116    project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
117    format string <parameter>format</parameter> and corresponding arguments.
118    <literal>%m</literal> may be used in the format string to refer to the error
119    string corresponding to the specified errno code. The error message is initialized
120    using the error identifier generated from <constant>error</constant> and the
121    formatted string. (If <parameter>error</parameter> is zero, no error is actually
122    set, and an error reply with no information is created.)</para>
123  </refsect1>
124
125  <refsect1>
126    <title>Return Value</title>
127
128    <para>These functions return 0 if the error reply was successfully created, and a
129    negative errno-style error code otherwise.</para>
130
131    <refsect2 id='errors'>
132      <title>Errors</title>
133
134      <para>Returned errors may indicate the following problems:</para>
135
136      <variablelist>
137        <varlistentry>
138          <term><constant>-EINVAL</constant></term>
139
140          <listitem><para>The call message <parameter>call</parameter> or the output
141          parameter <parameter>m</parameter> are <constant>NULL</constant>.</para>
142
143          <para>Message <parameter>call</parameter> is not a method call
144          message.</para>
145
146          <para>The error <parameter>e</parameter> parameter to
147          <function>sd_bus_message_new_method_error()</function> is not set, see
148          <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
149          </para>
150          </listitem>
151        </varlistentry>
152
153        <varlistentry>
154          <term><constant>-EPERM</constant></term>
155
156          <listitem><para>Message <parameter>call</parameter> has been sealed.
157          </para></listitem>
158        </varlistentry>
159
160        <varlistentry>
161          <term><constant>-ENOTCONN</constant></term>
162
163          <listitem><para>The bus to which message <parameter>call</parameter> is
164          attached is not connected.</para></listitem>
165        </varlistentry>
166
167        <varlistentry>
168          <term><constant>-ENOMEM</constant></term>
169
170          <listitem><para>Memory allocation failed.</para></listitem>
171        </varlistentry>
172      </variablelist>
173    </refsect2>
174  </refsect1>
175
176  <xi:include href="libsystemd-pkgconfig.xml" />
177
178  <refsect1>
179    <title>See Also</title>
180
181    <para>
182      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
183      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
184    </para>
185  </refsect1>
186
187</refentry>
188