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_errno</refname>
  23     <refname>sd_bus_reply_method_errnof</refname>
  24
  25     <refpurpose>Reply with an error to 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_reply_method_error</funcdef>
  34         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  35         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
  36       </funcprototype>
  37
  38       <funcprototype>
  39         <funcdef>int sd_bus_reply_method_errorf</funcdef>
  40         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  41         <paramdef>const char *<parameter>name</parameter></paramdef>
  42         <paramdef>const char *<parameter>format</parameter></paramdef>
  43         <paramdef>…</paramdef>
  44       </funcprototype>
  45
  46       <funcprototype>
  47         <funcdef>int sd_bus_reply_method_errno</funcdef>
  48         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  49         <paramdef>int <parameter>error</parameter></paramdef>
  50         <paramdef>const sd_bus_error *<parameter>p</parameter></paramdef>
  51       </funcprototype>
  52
  53       <funcprototype>
  54         <funcdef>int sd_bus_reply_method_errnof</funcdef>
  55         <paramdef>sd_bus_message *<parameter>call</parameter></paramdef>
  56         <paramdef>int <parameter>error</parameter></paramdef>
  57         <paramdef>const char *<parameter>format</parameter></paramdef>
  58         <paramdef>…</paramdef>
  59       </funcprototype>
  60     </funcsynopsis>
  61   </refsynopsisdiv>
  62
  63   <refsect1>
  64     <title>Description</title>
  65
  66     <para>The <function>sd_bus_reply_method_error()</function> function sends an
  67     error reply to the <parameter>call</parameter> message. The error structure
  68     <parameter>e</parameter> specifies the error to send, and is used as described in
  69     <citerefentry><refentrytitle>sd_bus_message_new_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  70     If no reply is expected to <parameter>call</parameter>, this function returns
  71     success without sending reply.</para>
  72
  73     <para>The <function>sd_bus_reply_method_errorf()</function> is to
  74     <function>sd_bus_reply_method_error()</function> what
  75     <function>sd_bus_message_new_method_errorf()</function> is to
  76     <function>sd_bus_message_new_method_error()</function>.</para>
  77
  78     <para>The <function>sd_bus_reply_method_errno()</function> is to
  79     <function>sd_bus_reply_method_error()</function> what
  80     <function>sd_bus_message_new_method_errno()</function> is to
  81     <function>sd_bus_message_new_method_error()</function>.</para>
  82
  83     <para>The <function>sd_bus_reply_method_errnof()</function> is to
  84     <function>sd_bus_reply_method_error()</function> what
  85     <function>sd_bus_message_new_method_errnof()</function> is to
  86     <function>sd_bus_message_new_method_error()</function>.</para>
  87   </refsect1>
  88
  89   <refsect1>
  90     <title>Return Value</title>
  91
  92     <para>These functions return 0 if the error reply was successfully sent or if
  93     none was expected, and a negative errno-style error code otherwise.</para>
  94
  95     <refsect2>
  96       <title>Errors</title>
  97
  98       <para>Returned errors may indicate the following problems:</para>
  99
 100       <variablelist>
 101         <varlistentry>
 102           <term><constant>-EINVAL</constant></term>
 103
 104           <listitem><para>The call message <parameter>call</parameter> is
 105           <constant>NULL</constant>.</para>
 106
 107           <para>Message <parameter>call</parameter> is not a method call message.
 108           </para>
 109
 110           <para>Message <parameter>call</parameter> is not attached to a bus.</para>
 111
 112           <para>The error <parameter>error</parameter> parameter to
 113           <function>sd_bus_reply_method_error</function> is not set, see
 114           <citerefentry><refentrytitle>sd_bus_error_is_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 115           </para>
 116           </listitem>
 117         </varlistentry>
 118
 119         <varlistentry>
 120           <term><constant>-EPERM</constant></term>
 121
 122           <listitem><para>Message <parameter>call</parameter> has been sealed.
 123           </para></listitem>
 124         </varlistentry>
 125
 126         <varlistentry>
 127           <term><constant>-ENOTCONN</constant></term>
 128
 129           <listitem><para>The bus to which message <parameter>call</parameter> is attached is not
 130           connected.</para></listitem>
 131         </varlistentry>
 132
 133         <varlistentry>
 134           <term><constant>-ENOMEM</constant></term>
 135
 136           <listitem><para>Memory allocation failed.</para></listitem>
 137         </varlistentry>
 138       </variablelist>
 139
 140       <para>In addition, any error message returned by
 141       <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 142       may be returned.</para>
 143     </refsect2>
 144   </refsect1>
 145
 146   <xi:include href="libsystemd-pkgconfig.xml" />
 147
 148   <refsect1>
 149     <title>See Also</title>
 150
 151     <para>
 152       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 153       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 154       <citerefentry><refentrytitle>sd_bus_message_new_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 155     </para>
 156   </refsect1>
 157
 158 </refentry>