[systemd-commits] 2 commits - Makefile-man.am man/sd_bus_error.xml src/sleep
Zbigniew Jędrzejewski-Szmek
zbyszek at kemper.freedesktop.org
Tue Jan 7 18:54:41 PST 2014
Makefile-man.am | 47 +++++
man/sd_bus_error.xml | 414 +++++++++++++++++++++++++++++++++++++++++++++++++++
src/sleep/sleep.c | 2
3 files changed, 462 insertions(+), 1 deletion(-)
New commits:
commit 096924092b664e992cec49e2ef4ce33443877ac8
Author: Michele Curti <michele.curti at gmail.com>
Date: Tue Jan 7 17:51:41 2014 +0100
sleep.c: fix typo
diff --git a/src/sleep/sleep.c b/src/sleep/sleep.c
index bf67354..8da050c 100644
--- a/src/sleep/sleep.c
+++ b/src/sleep/sleep.c
@@ -90,7 +90,7 @@ static int execute(char **modes, char **states) {
const char* note = strappenda("SLEEP=", arg_verb);
/* This file is opened first, so that if we hit an error,
- * we can abort before modyfing any state. */
+ * we can abort before modifying any state. */
f = fopen("/sys/power/state", "we");
if (!f) {
log_error("Failed to open /sys/power/state: %m");
commit 71365a7754db5ff8e07941501063b1da2a4b4bd5
Author: Zbigniew Jędrzejewski-Szmek <zbyszek at in.waw.pl>
Date: Tue Jan 7 21:46:36 2014 -0500
man: document sd-bus error functions
diff --git a/Makefile-man.am b/Makefile-man.am
index 75cccc0..52e62f1 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -22,6 +22,7 @@ MANPAGES += \
man/sd_booted.3 \
man/sd_bus_creds_get_pid.3 \
man/sd_bus_creds_new_from_pid.3 \
+ man/sd_bus_error.3 \
man/sd_bus_message_get_cookie.3 \
man/sd_bus_new.3 \
man/sd_bus_open_user.3 \
@@ -167,6 +168,15 @@ MANPAGES_ALIAS += \
man/sd_bus_creds_unref.3 \
man/sd_bus_default_system.3 \
man/sd_bus_default_user.3 \
+ man/sd_bus_error_copy.3 \
+ man/sd_bus_error_free.3 \
+ man/sd_bus_error_get_errno.3 \
+ man/sd_bus_error_has_name.3 \
+ man/sd_bus_error_is_set.3 \
+ man/sd_bus_error_set.3 \
+ man/sd_bus_error_set_const.3 \
+ man/sd_bus_error_set_errno.3 \
+ man/sd_bus_error_set_errnof.3 \
man/sd_bus_message_get_reply_cookie.3 \
man/sd_bus_open_system.3 \
man/sd_bus_open_system_container.3 \
@@ -304,6 +314,15 @@ man/sd_bus_creds_ref.3: man/sd_bus_creds_new_from_pid.3
man/sd_bus_creds_unref.3: man/sd_bus_creds_new_from_pid.3
man/sd_bus_default_system.3: man/sd_bus_open_user.3
man/sd_bus_default_user.3: man/sd_bus_open_user.3
+man/sd_bus_error_copy.3: man/sd_bus_error.3
+man/sd_bus_error_free.3: man/sd_bus_error.3
+man/sd_bus_error_get_errno.3: man/sd_bus_error.3
+man/sd_bus_error_has_name.3: man/sd_bus_error.3
+man/sd_bus_error_is_set.3: man/sd_bus_error.3
+man/sd_bus_error_set.3: man/sd_bus_error.3
+man/sd_bus_error_set_const.3: man/sd_bus_error.3
+man/sd_bus_error_set_errno.3: man/sd_bus_error.3
+man/sd_bus_error_set_errnof.3: man/sd_bus_error.3
man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3
man/sd_bus_open_system.3: man/sd_bus_open_user.3
man/sd_bus_open_system_container.3: man/sd_bus_open_user.3
@@ -553,6 +572,33 @@ man/sd_bus_default_system.html: man/sd_bus_open_user.html
man/sd_bus_default_user.html: man/sd_bus_open_user.html
$(html-alias)
+man/sd_bus_error_copy.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_free.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_get_errno.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_has_name.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_is_set.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_set.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_set_const.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_set_errno.html: man/sd_bus_error.html
+ $(html-alias)
+
+man/sd_bus_error_set_errnof.html: man/sd_bus_error.html
+ $(html-alias)
+
man/sd_bus_message_get_reply_cookie.html: man/sd_bus_message_get_cookie.html
$(html-alias)
@@ -1283,6 +1329,7 @@ EXTRA_DIST += \
man/sd_booted.xml \
man/sd_bus_creds_get_pid.xml \
man/sd_bus_creds_new_from_pid.xml \
+ man/sd_bus_error.xml \
man/sd_bus_message_get_cookie.xml \
man/sd_bus_new.xml \
man/sd_bus_open_user.xml \
diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml
new file mode 100644
index 0000000..38bc303
--- /dev/null
+++ b/man/sd_bus_error.xml
@@ -0,0 +1,414 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!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 at 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>libsystemd-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><structname>sd_bus_error</structname> structure carries
+ information for a <filename>libsystemd-bus</filename> error.
+ Functions described below can be used to set and query fields in
+ this structure. Field <structfield>name</structfield> 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><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 is
+ assumed that no error occured, 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> will be filled-in in the
+ <structname>sd_bus_error</structname> structure
+ <parameter>e</parameter> points at. 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><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><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><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> is will convert
+ <structname>e->name</structname> to an errno-like value
+ using the same rules as <function>sd_bus_error_set</function>.
+ </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.
+ Otherwie they wil 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><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><varname>-EINVAL</varname></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><varname>-ENOMEM</varname></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-bus</constant>Â <citerefentry><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>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
More information about the systemd-commits
mailing list