man/sd_bus_reply_method_error.xml

   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+ -->
   5
   6 <refentry id="sd_bus_reply_method_error"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_bus_reply_method_error</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_bus_reply_method_error</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_bus_reply_method_error</refname>
  21     <refname>sd_bus_reply_method_errorf</refname>
  22     <refname>sd_bus_reply_method_errorfv</refname>
  23     <refname>sd_bus_reply_method_errno</refname>
  24     <refname>sd_bus_reply_method_errnof</refname>
  25     <refname>sd_bus_reply_method_errnofv</refname>
  26
  27     <refpurpose>Reply with an error to a D-Bus method call</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  33
  34       <funcprototype>
  35         <funcdef>int sd_bus_reply_method_error</funcdef>
  36         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  37         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>int sd_bus_reply_method_errorf</funcdef>
  42         <paramdef>sd_bus_message *<parameter>call</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_reply_method_errorfv</funcdef>
  50         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  51         <paramdef>const char *<parameter>name</parameter></paramdef>
  52         <paramdef>const char *<parameter>format</parameter></paramdef>
  53         <paramdef>va_list <parameter>ap</parameter></paramdef>
  54       </funcprototype>
  55
  56       <funcprototype>
  57         <funcdef>int sd_bus_reply_method_errno</funcdef>
  58         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  59         <paramdef>int <parameter>error</parameter></paramdef>
  60         <paramdef>const sd_bus_error *<parameter>p</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int sd_bus_reply_method_errnof</funcdef>
  65         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  66         <paramdef>int <parameter>error</parameter></paramdef>
  67         <paramdef>const char *<parameter>format</parameter></paramdef>
  68         <paramdef>...</paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int sd_bus_reply_method_errnofv</funcdef>
  73         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  74         <paramdef>int <parameter>error</parameter></paramdef>
  75         <paramdef>const char *<parameter>format</parameter></paramdef>
  76         <paramdef>va_list <parameter>ap</parameter></paramdef>
  77       </funcprototype>
  78     </funcsynopsis>
  79   </refsynopsisdiv>
  80
  81   <refsect1>
  82     <title>Description</title>
  83
  84     <para>The <function>sd_bus_reply_method_error()</function> function sends an error reply to the
  85     <parameter>call</parameter> message. The error structure <parameter>e</parameter> specifies the
  86     error to send, and is used as described in
  87     <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  88     If no reply is expected to <parameter>call</parameter>, this function succeeds without sending a
  89     reply.</para>
  90
  91     <para>The <function>sd_bus_reply_method_errorf()</function> is to
  92     <function>sd_bus_reply_method_error()</function> what
  93     <function>sd_bus_message_new_method_errorf()</function> is to
  94     <function>sd_bus_message_new_method_error()</function>.</para>
  95
  96     <para>The <function>sd_bus_reply_method_errno()</function> is to
  97     <function>sd_bus_reply_method_error()</function> what
  98     <function>sd_bus_message_new_method_errno()</function> is to
  99     <function>sd_bus_message_new_method_error()</function>.</para>
 100
 101     <para>The <function>sd_bus_reply_method_errnof()</function> is to
 102     <function>sd_bus_reply_method_error()</function> what
 103     <function>sd_bus_message_new_method_errnof()</function> is to
 104     <function>sd_bus_message_new_method_error()</function>.</para>
 105   </refsect1>
 106
 107   <refsect1>
 108     <title>Return Value</title>
 109
 110     <para>This function returns a non-negative integer if the error reply was successfully sent or
 111     if <parameter>call</parameter> does not expect a reply. On failure, it returns a negative
 112     errno-style error code.</para>
 113
 114     <refsect2>
 115       <title>Errors</title>
 116
 117       <para>Returned errors may indicate the following problems:</para>
 118
 119       <variablelist>
 120         <varlistentry>
 121           <term><constant>-EINVAL</constant></term>
 122
 123           <listitem><para>The input parameter <parameter>call</parameter> is
 124           <constant>NULL</constant>.</para>
 125
 126           <para>Message <parameter>call</parameter> is not a method call message.</para>
 127
 128           <para>Message <parameter>call</parameter> is not attached to a bus.</para>
 129
 130           <para>The error parameter <parameter>error</parameter> to
 131           <function>sd_bus_reply_method_error</function> is not set, see
 132           <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 133           </para>
 134           </listitem>
 135         </varlistentry>
 136
 137         <varlistentry>
 138           <term><constant>-EPERM</constant></term>
 139
 140           <listitem><para>Message <parameter>call</parameter> has been sealed.
 141           </para></listitem>
 142         </varlistentry>
 143
 144         <varlistentry>
 145           <term><constant>-ENOTCONN</constant></term>
 146
 147           <listitem><para>The bus to which message <parameter>call</parameter> is attached is not
 148           connected.</para></listitem>
 149         </varlistentry>
 150
 151         <varlistentry>
 152           <term><constant>-ENOMEM</constant></term>
 153
 154           <listitem><para>Memory allocation failed.</para></listitem>
 155         </varlistentry>
 156       </variablelist>
 157
 158       <para>In addition, any error returned by
 159       <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 160       may be returned.</para>
 161     </refsect2>
 162   </refsect1>
 163
 164   <xi:include href="libsystemd-pkgconfig.xml" />
 165
 166   <refsect1>
 167     <title>See Also</title>
 168
 169     <para>
 170       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 173     </para>
 174   </refsect1>
 175
 176 </refentry>