diff options
Diffstat (limited to 'man/sd_bus_error.xml')
| -rw-r--r-- | man/sd_bus_error.xml | 414 |
1 files changed, 414 insertions, 0 deletions
diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml new file mode 100644 index 0000000000..38bc30311b --- /dev/null +++ b/man/sd_bus_error.xml @@ -0,0 +1,414 @@ +<?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"> + + <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>libsystemd-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><structname>sd_bus_error</structname> structure carries + information for a <filename>libsystemd-bus</filename> error. + Functions described below can be used to set and query fields in + this structure. Field <structfield>name</structfield> 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 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> will be filled-in in the + <structname>sd_bus_error</structname> structure + <parameter>e</parameter> points at. 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>. + </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. + Otherwie they wil 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-bus</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> |