-<?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">
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
-<!--
- 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">
+<refentry id="sd_bus_error" xmlns:xi="http://www.w3.org/2001/XInclude">
<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>
<refname>sd_bus_error_set_errnofv</refname>
<refname>sd_bus_error_get_errno</refname>
<refname>sd_bus_error_copy</refname>
+ <refname>sd_bus_error_move</refname>
<refname>sd_bus_error_is_set</refname>
<refname>sd_bus_error_has_name</refname>
<funcsynopsisinfo>typedef struct {
const char *name;
const char *message;
- ...
+ …
} sd_bus_error;</funcsynopsisinfo>
<para>
<paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
- <paramdef>...</paramdef>
+ <paramdef>…</paramdef>
</funcprototype>
<funcprototype>
<paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
<paramdef>int <parameter>error</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
- <paramdef>...</paramdef>
+ <paramdef>…</paramdef>
</funcprototype>
<funcprototype>
<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>
+ <paramdef>va_list <parameter>ap</parameter></paramdef>
</funcprototype>
<funcprototype>
<paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
</funcprototype>
+ <funcprototype>
+ <funcdef>int <function>sd_bus_error_move</function></funcdef>
+ <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
+ <paramdef>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>
<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
+ 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
+ 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
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
+ <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
+ <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 returned. Do not use this call on error
+ 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
+ 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
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
+ 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
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 returned.</para>
+ 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>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
+ <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>
<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.
+ <function>sd_bus_error_set_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_move()</function> is similar to <function>sd_bus_error_copy()</function>, but will
+ move any error information from <parameter>e</parameter> into <parameter>dst</parameter>, resetting the
+ former. This function cannot fail, as no new memory is allocated. Note that if <parameter>e</parameter> is not set
+ (or <constant>NULL</constant>) <parameter>dst</parameter> is initializated to
+ <constant>SD_BUS_ERROR_NULL</constant>. Moreover, if <parameter>dst</parameter> is <constant>NULL</constant> no
+ operation is executed on it and and resources held by <parameter>e</parameter> are freed and reset. 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,
<title>Return Value</title>
<para>The functions <function>sd_bus_error_set()</function>,
- <function>sd_bus_error_setf()</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. Functions
+ <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,
<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_copy()</function> and <function>sd_bus_error_move()</function> return 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
<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
+ <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>
+ <refsect2>
+ <title>Errors</title>
- <para>Returned errors may indicate the following problems:</para>
+
<para>Returned errors may indicate the following problems:</para>
- <variablelist>
+ <variablelist>
- <varlistentry>
- <term><constant>-EINVAL</constant></term>
+ <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>
+ <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>
+ <varlistentry>
+ <term><constant>-ENOMEM</constant></term>
- <listitem><para>Memory allocation failed.</para></listitem>
- </varlistentry>
- </variablelist>
+ <listitem><para>Memory allocation failed.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
</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>
+ <xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
projects / thirdparty / systemd.git / blobdiff