diff options
Diffstat (limited to 'src/libsystemd/sd_bus_error.xml')
| -rw-r--r-- | src/libsystemd/sd_bus_error.xml | 389 |
1 files changed, 389 insertions, 0 deletions
diff --git a/src/libsystemd/sd_bus_error.xml b/src/libsystemd/sd_bus_error.xml new file mode 100644 index 0000000000..c2d7ee389b --- /dev/null +++ b/src/libsystemd/sd_bus_error.xml @@ -0,0 +1,389 @@ +<?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"> + + <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_MAKE_CONST</refname> + <refname>SD_BUS_ERROR_NULL</refname> + <refname>sd_bus_error_free</refname> + <refname>sd_bus_error_set</refname> + <refname>sd_bus_error_setf</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_set_errnofv</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>void <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_set_errnofv</function></funcdef> + <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>const char *<parameter>format</parameter></paramdef> + <paramdef>va_list ap</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> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <structname>sd_bus_error</structname> structure carries + information about a D-Bus error condition. The functions described + below may 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>. A number of common, standardized error names are + described in + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but additional domain-specific errors may be defined by + applications. The <structfield>message</structfield> field usually + contains a human-readable string describing the details, but might + be NULL. An unset <structname>sd_bus_error</structname> structure + should have both fields initialized to NULL. Set an error + structure to <constant>SD_BUS_ERROR_NULL</constant> in order to + reset both fields to NULL. When no longer necessary, resources + held by the <structname>sd_bus_error</structname>structure should + be destroyed with <function>sd_bus_error_free()</function>.</para> + + <para><function>sd_bus_error_set()</function> sets an error + structure to the specified name and message strings. The strings + will be copied into internal, newly allocated memory. It is + essential to free the error structure again when it is not + required anymore (see above). The function will return an + <varname>errno</varname>-like negative value (see <citerefentry + project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>) + determined from the specified error name. Various well-known + D-Bus errors are converted to well-known <varname>errno</varname> + counterparts, and the other ones to <constant>-EIO</constant>. See + <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry> + for a list of well-known error names. Additional error mappings + may be defined with + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If + <parameter>e</parameter> is NULL, no error structure is initialized, + but the error is still converted into an + <varname>errno</varname>-style error. 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. If + <parameter>message</parameter> is NULL, no message is set. This + call can fail if no memory may be allocated for the name and + message strings, in which case an + <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set + instead and -ENOMEM be returned. Do not use this call on error + structures that are already initialized. If you intend to reuse an + error structure, free the old data stored in it with + <function>sd_bus_error_free()</function> first.</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 the + <structfield>message</structfield> field.</para> + + <para><function>sd_bus_error_set_const()</function> is similar to + <function>sd_bus_error_set()</function>, but the string parameters + are not copied internally, and must hence remain constant and + valid for the lifetime of <parameter>e</parameter>. Use this call + to avoid memory allocations when setting error structures. Since + this call does not allocate memory, it will not fail with an + out-of-memory condition as + <function>sd_bus_error_set()</function> can, as described + above. Alternatively, the + <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used + to generate a literal, constant bus error structure + on-the-fly.</para> + + <para><function>sd_bus_error_set_errno()</function> will set + <structfield>name</structfield> from an + <varname>errno</varname>-like value that is converted to a D-Bus + error. <citerefentry + project='die-net'><refentrytitle>strerror_r</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 applicable, otherwise a name in the + <literal>System.Error.</literal> namespace will be generated. The + sign of the specified error number is ignored. The absolute value + is used implicitly. The call always returns a negative value, for + convenient usage in <function>return</function> statements. This + call might fail due to lack of memory, in which case an + <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead, + and -ENOMEM is returned.</para> + + <para><function>sd_bus_error_set_errnof()</function> is similar to + <function>sd_bus_error_set_errno()</function>, but in addition to + <parameter>error</parameter>, takes a <citerefentry + project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> + format string and corresponding arguments. The + <structfield>message</structfield> field will be generated from + <parameter>format</parameter> and the arguments.</para> + + <para><function>sd_bus_error_set_errnofv()</function> is similar to + <function>sd_bus_error_set_errnof()</function>, but takes the + format string parameters as <citerefentry + project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry> + parameter list.</para> + + <para><function>sd_bus_error_get_errno()</function> converts the + <structfield>name</structfield> field of an error structure to an + <varname>errno</varname>-like (positive) 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. Returns a converted + <varname>errno</varname>-like, negative error code.</para> + + <para><function>sd_bus_error_is_set()</function> will return a + non-zero value 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 a + non-zero value 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. The function may also be called safely + on unset errors (error structures with both fields set to NULL), + in which case it performs no operation. This call will reset the + error structure after freeing the data, so that all fields are set + to NULL. The structure may be reused afterwards.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>The functions <function>sd_bus_error_set()</function>, + <function>sd_bus_error_setf()</function>, and + <function>sd_bus_error_set_const()</function>, when successful, + return the negative errno value corresponding to the + <parameter>name</parameter> parameter. The functions + <function>sd_bus_error_set_errno()</function>, + <function>sd_bus_error_set_errnof()</function> and + <function>sd_bus_error_set_errnofv()</function>, when successful, + return the negative value of the <parameter>error</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 a negative error value converted + from the error name otherwise.</para> + + <para><function>sd_bus_error_is_set()</function> returns a + non-zero value when <parameter>e</parameter> and the + <structfield>name</structfield> field are + non-<constant>NULL</constant>, zero otherwise.</para> + + <para><function>sd_bus_error_has_name()</function> returns a + non-zero value when <parameter>e</parameter> is + non-<constant>NULL</constant> and the + <structfield>name</structfield> field is equal to + <parameter>name</parameter>, zero 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>. Usually, error structures + are allocated on the stack or passed in as function parameters, + but they may also be allocated dynamically, in which case it is + the duty of the caller to <citerefentry + project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> + the memory held by the structure itself after freeing its contents + with <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><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |