+++ /dev/null
-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
-<!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 project='die-net'><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 project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- </para>
- </refsect1>
-
-</refentry>
~ianmdlvl / elogind.git / blobdiff