2014-01-08 06:46:36 +04:00
<?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: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
2014-02-20 01:04:30 +04:00
<refentry id= "sd_bus_error" conditional= "ENABLE_KDBUS" >
2014-01-08 06:46:36 +04:00
<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>
2014-01-13 20:30:51 +04:00
<refpurpose > sd-bus error handling</refpurpose>
2014-01-08 06:46:36 +04:00
</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>
2014-02-17 06:37:18 +04:00
<para > The <structname > sd_bus_error</structname> structure carries
2014-01-13 20:30:51 +04:00
information for a <filename > sd-bus</filename> error.
2014-01-08 06:46:36 +04:00
Functions described below can be used to set and query fields in
2014-02-17 06:37:18 +04:00
this structure. The <structfield > name</structfield> field contains a
2014-01-08 06:46:36 +04:00
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 > <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
2014-02-17 06:37:18 +04:00
<parameter > name</parameter> is <constant > NULL</constant> , it is
2014-01-08 06:46:36 +04:00
assumed that no error occured, 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
2014-02-17 06:37:18 +04:00
<structfield > message</structfield> in the
2014-01-08 06:46:36 +04:00
<structname > sd_bus_error</structname> structure
2014-02-17 06:37:18 +04:00
<parameter > e</parameter> points at will be filled in. As described above,
2014-01-08 06:46:36 +04:00
<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 > <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 > <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> is will convert
2014-02-17 06:58:37 +04:00
<structname > e-> name</structname> to an errno-like value using the
2014-01-10 18:10:18 +04:00
same rules as <function > sd_bus_error_set</function> . If
<parameter > e</parameter> is <constant > NULL</constant> , 0 will be
returned.</para>
2014-01-08 06:46:36 +04:00
<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.
2014-02-17 06:37:18 +04:00
Otherwise, they will be copied.</para>
2014-01-08 06:46:36 +04:00
<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 > <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
2014-02-17 06:58:37 +04:00
<parameter > e-> name</parameter> otherwise.</para>
2014-01-08 06:46:36 +04:00
<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
2014-02-17 06:58:37 +04:00
<parameter > e-> name</parameter> are non-<constant > NULL</constant> ,
2014-01-08 06:46:36 +04:00
<constant > false</constant> otherwise.</para>
<para > <function > sd_bus_error_has_name</function> returns
<constant > true</constant> when <parameter > e</parameter> is
2014-02-17 06:58:37 +04:00
non-<constant > NULL</constant> and <parameter > e-> name</parameter>
2014-01-08 06:46:36 +04:00
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 > <varname > -EINVAL</varname> </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 > <varname > -ENOMEM</varname> </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
2014-01-13 20:30:51 +04:00
<constant > libsystemd</constant> <citerefentry > <refentrytitle > pkg-config</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2014-01-08 06:46:36 +04:00
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 > <refentrytitle > errno</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > strerror</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
</para>
</refsect1>
</refentry>
