man/sd_bus_message_new_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-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>