<?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">

<refentry id="sd_bus_error">

<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 &lt;systemd/sd-bus.h&gt;</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.

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><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 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

<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><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

<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><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><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

<constant>libsystemd</constant> <citerefentry><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><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>