-<?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>
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
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
<function>sd_bus_error_free()</function> first.</para>
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>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
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>