| <?xml version='1.0'?> <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| |
| <!-- |
| This file is part of systemd. |
| |
| Copyright 2014 Zbigniew Jędrzejewski-Szmek |
| |
| systemd is free software; you can redistribute it and/or modify it |
| under the terms of the GNU Lesser General Public License as published by |
| the Free Software Foundation; either version 2.1 of the License, or |
| (at your option) any later version. |
| |
| systemd is distributed in the hope that it will be useful, but |
| WITHOUT ANY WARRANTY; without even the implied warranty of |
| MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| Lesser General Public License for more details. |
| |
| You should have received a copy of the GNU Lesser General Public License |
| along with systemd; If not, see <http://www.gnu.org/licenses/>. |
| --> |
| |
| <refentry id="sd_bus_error" conditional="ENABLE_KDBUS"> |
| |
| <refentryinfo> |
| <title>sd_bus_error</title> |
| <productname>systemd</productname> |
| |
| <authorgroup> |
| <author> |
| <contrib>A monkey with a typewriter</contrib> |
| <firstname>Zbigniew</firstname> |
| <surname>Jędrzejewski-Szmek</surname> |
| <email>zbyszek@in.waw.pl</email> |
| </author> |
| </authorgroup> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>sd_bus_error</refentrytitle> |
| <manvolnum>3</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>sd_bus_error</refname> |
| <refname>sd_bus_error_free</refname> |
| <refname>sd_bus_error_set</refname> |
| <refname>sd_bus_error_set_const</refname> |
| <refname>sd_bus_error_set_errno</refname> |
| <refname>sd_bus_error_set_errnof</refname> |
| <refname>sd_bus_error_get_errno</refname> |
| <refname>sd_bus_error_copy</refname> |
| <refname>sd_bus_error_is_set</refname> |
| <refname>sd_bus_error_has_name</refname> |
| |
| <refpurpose>sd-bus error handling</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <funcsynopsis> |
| <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> |
| |
| <funcsynopsisinfo>typedef struct { |
| const char *name; |
| const char *message; |
| ... |
| } sd_bus_error;</funcsynopsisinfo> |
| |
| <para> |
| <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NULL</constant> |
| </para> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_free</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_set</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> |
| <paramdef>const char *<parameter>name</parameter></paramdef> |
| <paramdef>const char *<parameter>message</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_setf</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> |
| <paramdef>const char *<parameter>name</parameter></paramdef> |
| <paramdef>const char *<parameter>format</parameter></paramdef> |
| <paramdef>...</paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_set_const</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> |
| <paramdef>const char *<parameter>name</parameter></paramdef> |
| <paramdef>const char *<parameter>message</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_set_errno</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> |
| <paramdef>int <parameter>error</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> |
| <paramdef>int <parameter>error</parameter></paramdef> |
| <paramdef>const char *<parameter>format</parameter></paramdef> |
| <paramdef>...</paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_get_errno</function></funcdef> |
| <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_copy</function></funcdef> |
| <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef> |
| <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_is_set</function></funcdef> |
| <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> |
| </funcprototype> |
| |
| <funcprototype> |
| <funcdef>int <function>sd_bus_error_has_name</function></funcdef> |
| <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> |
| <paramdef>const char *<parameter>name</parameter></paramdef> |
| </funcprototype> |
| </funcsynopsis> |
| |
| <para> |
| <constant>SD_BUS_ERROR_FAILED</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NO_MEMORY</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_SERVICE_UNKNOWN</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NAME_HAS_NO_OWNER</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NO_REPLY</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_IO_ERROR</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_BAD_ADDRESS</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_LIMITS_EXCEEDED</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_ACCESS_DENIED</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_AUTH_FAILED</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NO_SERVER</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_TIMEOUT</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_NO_NETWORK</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_ADDRESS_IN_USE</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_DISCONNECTED</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_INVALID_ARGS</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_FILE_NOT_FOUND</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_FILE_EXISTS</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_UNKNOWN_METHOD</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_UNKNOWN_OBJECT</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_UNKNOWN_INTERFACE</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_UNKNOWN_PROPERTY</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_PROPERTY_READ_ONLY</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_INVALID_SIGNATURE</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_INCONSISTENT_MESSAGE</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</constant> |
| </para> |
| <para> |
| <constant>SD_BUS_ERROR_MATCH_RULE_INVALID</constant> |
| </para> |
| |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para>The <structname>sd_bus_error</structname> structure carries |
| information for a <filename>sd-bus</filename> error. The |
| functions described below can be used to set and query fields in |
| this structure. The <structfield>name</structfield> field contains a |
| short identifier of an error. It should follow the rules for error |
| names described in the D-Bus specification, subsection <ulink |
| url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid |
| Names</ulink>. The <structfield>message</structfield> is a human |
| readable string describing the details. When no longer necessary, |
| resources held by this structure should be destroyed with |
| <function>sd_bus_error_free</function>.</para> |
| |
| <para><function>sd_bus_error_set</function> will return an |
| errno-like negative value returned based on parameter |
| <parameter>name</parameter> (see |
| <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>). |
| Various well-known D-Bus errors are converted to specific values, |
| and the remaining ones to <constant>-ENXIO</constant>. Well-known |
| D-Bus error names are available as constants |
| <constant>SD_BUS_ERROR_FAILED</constant>, etc., listed above. If |
| <parameter>name</parameter> is <constant>NULL</constant>, it is |
| assumed that no error occurred, and 0 is returned. This means that |
| this function may be conveniently used in a |
| <function>return</function> statement.</para> |
| |
| <para>If <parameter>e</parameter> is not |
| <constant>NULL</constant>, <structfield>name</structfield> and |
| <structfield>message</structfield> in the |
| <structname>sd_bus_error</structname> structure |
| <parameter>e</parameter> points at will be filled in. As described above, |
| <parameter>name</parameter> may be <constant>NULL</constant>, |
| which is treated as no error. Parameter |
| <parameter>message</parameter> may also be |
| <constant>NULL</constant>, in which case no message is specified. |
| <function>sd_bus_error_set</function> will make internal copies of |
| specified strings.</para> |
| |
| <para><function>sd_bus_error_setf</function> is similar to |
| <function>sd_bus_error_set</function>, but takes a |
| <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| format string and corresponding arguments to generate |
| <structname>message</structname>.</para> |
| |
| <para><function>sd_bus_error_set_const</function> is similar to |
| <function>sd_bus_error_set</function>, but string parameters are |
| not copied internally, and must remain valid for the lifetime of |
| <parameter>e</parameter>.</para> |
| |
| <para><function>sd_bus_error_set_errno</function> will set |
| <structfield>name</structfield> based on an errno-like value. |
| <citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| will be used to set <structfield>message</structfield>. Well-known |
| D-Bus error names will be used for <structfield>name</structfield> |
| if available, otherwise a name in the |
| <literal>System.Error</literal> namespace will be generated. |
| </para> |
| |
| <para><function>sd_bus_error_set_errnof</function> is similar to |
| <function>sd_bus_error_set_errno</function>, but in addition to |
| <parameter>name</parameter>, takes a |
| <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| format and corresponding arguments. |
| <structfield>name</structfield> will be generated from |
| <parameter>format</parameter> and the arguments.</para> |
| |
| <para><function>sd_bus_error_get_errno</function> will convert |
| <structname>e->name</structname> to an errno-like value using the |
| same rules as <function>sd_bus_error_set</function>. If |
| <parameter>e</parameter> is <constant>NULL</constant>, 0 will be |
| returned.</para> |
| |
| <para><function>sd_bus_error_copy</function> will initialize |
| <parameter>dst</parameter> using the values in |
| <parameter>e</parameter>. If the strings in |
| <parameter>e</parameter> were set using |
| <function>sd_bus_set_error_const</function>, they will be shared. |
| Otherwise, they will be copied.</para> |
| |
| <para><function>sd_bus_error_is_set</function> will return |
| <constant>true</constant> if <parameter>e</parameter> is |
| non-<constant>NULL</constant> and an error has been set, |
| <constant>false</constant> otherwise.</para> |
| |
| <para><function>sd_bus_error_has_name</function> will return true |
| if <parameter>e</parameter> is non-<constant>NULL</constant> and |
| an error with the same <parameter>name</parameter> has been set, |
| <constant>false</constant> otherwise.</para> |
| |
| <para><function>sd_bus_error_free</function> will destroy resources |
| held by <parameter>e</parameter>. The parameter itself will not |
| be deallocated, and must be |
| <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d |
| by the caller if necessary.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Return Value</title> |
| |
| <para>Functions <function>sd_bus_error_set</function>, |
| <function>sd_bus_error_setf</function>, |
| <function>sd_bus_error_set_const</function>, when successful, |
| return the negative errno value corresponding to the |
| <parameter>name</parameter> parameter. Functions |
| <function>sd_bus_error_set_errno</function> and |
| <function>sd_bus_error_set_errnof</function>, when successful, |
| return the value of the <parameter>errno</parameter> parameter. If |
| an error occurs, one of the negative error values listed below |
| will be returned.</para> |
| |
| <para><function>sd_bus_error_get_errno</function> returns |
| <constant>false</constant> when <parameter>e</parameter> is |
| <constant>NULL</constant>, and a positive errno value mapped from |
| <parameter>e->name</parameter> otherwise.</para> |
| |
| <para><function>sd_bus_error_copy</function> returns 0 or a |
| positive integer on success, and one of the negative error values |
| listed below otherwise.</para> |
| |
| <para><function>sd_bus_error_is_set</function> returns |
| <constant>true</constant> when <parameter>e</parameter> and |
| <parameter>e->name</parameter> are non-<constant>NULL</constant>, |
| <constant>false</constant> otherwise.</para> |
| |
| <para><function>sd_bus_error_has_name</function> returns |
| <constant>true</constant> when <parameter>e</parameter> is |
| non-<constant>NULL</constant> and <parameter>e->name</parameter> |
| is equal to <parameter>name</parameter>, |
| <constant>false</constant> otherwise.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Reference ownership</title> |
| <para><structname>sd_bus_error</structname> is not reference |
| counted. Users should destroy resources held by it by calling |
| <function>sd_bus_error_free</function>.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Errors</title> |
| |
| <para>Returned errors may indicate the following problems:</para> |
| |
| <variablelist> |
| |
| <varlistentry> |
| <term><constant>-EINVAL</constant></term> |
| |
| <listitem><para>Error was already set in |
| <structname>sd_bus_error</structname> structure when one the |
| error-setting functions was called.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><constant>-ENOMEM</constant></term> |
| |
| <listitem><para>Memory allocation failed.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| |
| <refsect1> |
| <title>Notes</title> |
| |
| <para><function>sd_bus_set_error()</function> and other functions |
| described here are available as a shared library, which can be |
| compiled and linked to with the |
| <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| file.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
| </para> |
| </refsect1> |
| |
| </refentry> |