]> git.ipfire.org Git - thirdparty/systemd.git/blobdiff - man/sd_bus_error.xml
update-utmp: remove dead conditional
[thirdparty/systemd.git] / man / sd_bus_error.xml
index 87eac1d1b8d7022b4d9074c508757ef391fb0390..8616f7ee43eab61b601debfa53dc9db604497860 100644 (file)
@@ -1,40 +1,13 @@
-<?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>
@@ -55,6 +28,7 @@
     <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>
 
@@ -68,7 +42,7 @@
       <funcsynopsisinfo>typedef struct {
         const char *name;
         const char *message;
-        ...
+        …
 } sd_bus_error;</funcsynopsisinfo>
 
       <para>
@@ -95,7 +69,7 @@
         <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-&gt;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>