diff options
Diffstat (limited to 'man/sd_bus_error.xml')
| -rw-r--r-- | man/sd_bus_error.xml | 415 |
1 files changed, 0 insertions, 415 deletions
diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml deleted file mode 100644 index dc5a93d617..0000000000 --- a/man/sd_bus_error.xml +++ /dev/null @@ -1,415 +0,0 @@ -<?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> |