systemd/0391-man-add-sd_event_add_signal-3.patch
Zbigniew Jędrzejewski-Szmek 62fe9450da Update to latest git
2014-10-07 15:51:56 -04:00

317 lines
13 KiB
Diff
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

From 3144ebcad37422dd85220915d37e7e9eea36564a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 25 Sep 2014 17:27:27 -0400
Subject: [PATCH] man: add sd_event_add_signal(3)
---
Makefile-man.am | 7 ++
man/sd_event_add_signal.xml | 196 ++++++++++++++++++++++++++++++++++++++++++++
man/sd_event_add_time.xml | 24 ++++--
3 files changed, 221 insertions(+), 6 deletions(-)
create mode 100644 man/sd_event_add_signal.xml
diff --git a/Makefile-man.am b/Makefile-man.am
index 199c731e7e..85a3612f39 100644
--- a/Makefile-man.am
+++ b/Makefile-man.am
@@ -741,6 +741,7 @@ MANPAGES += \
man/sd_bus_open_user.3 \
man/sd_bus_path_encode.3 \
man/sd_bus_request_name.3 \
+ man/sd_event_add_signal.3 \
man/sd_event_add_time.3 \
man/sd_event_new.3 \
man/systemd-bus-proxyd.8 \
@@ -802,6 +803,7 @@ MANPAGES_ALIAS += \
man/sd_bus_unref.3 \
man/sd_event_default.3 \
man/sd_event_ref.3 \
+ man/sd_event_source_get_signal.3 \
man/sd_event_source_get_time.3 \
man/sd_event_source_get_time_accuracy.3 \
man/sd_event_source_get_time_clock.3 \
@@ -865,6 +867,7 @@ man/sd_bus_release_name.3: man/sd_bus_request_name.3
man/sd_bus_unref.3: man/sd_bus_new.3
man/sd_event_default.3: man/sd_event_new.3
man/sd_event_ref.3: man/sd_event_new.3
+man/sd_event_source_get_signal.3: man/sd_event_add_signal.3
man/sd_event_source_get_time.3: man/sd_event_add_time.3
man/sd_event_source_get_time_accuracy.3: man/sd_event_add_time.3
man/sd_event_source_get_time_clock.3: man/sd_event_add_time.3
@@ -1040,6 +1043,9 @@ man/sd_event_default.html: man/sd_event_new.html
man/sd_event_ref.html: man/sd_event_new.html
$(html-alias)
+man/sd_event_source_get_signal.html: man/sd_event_add_signal.html
+ $(html-alias)
+
man/sd_event_source_get_time.html: man/sd_event_add_time.html
$(html-alias)
@@ -1542,6 +1548,7 @@ EXTRA_DIST += \
man/sd_bus_open_user.xml \
man/sd_bus_path_encode.xml \
man/sd_bus_request_name.xml \
+ man/sd_event_add_signal.xml \
man/sd_event_add_time.xml \
man/sd_event_new.xml \
man/sd_get_seats.xml \
diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
new file mode 100644
index 0000000000..2344fb3c02
--- /dev/null
+++ b/man/sd_event_add_signal.xml
@@ -0,0 +1,196 @@
+<?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_event_add_signal" conditional="ENABLE_KDBUS">
+
+ <refentryinfo>
+ <title>sd_event_add_signal</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>More text</contrib>
+ <firstname>Zbigniew</firstname>
+ <surname>Jędrzejewski-Szmek</surname>
+ <email>zbyszek@in.waw.pl</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sd_event_add_signal</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sd_event_add_signal</refname>
+ <refname>sd_event_source_get_signal</refname>
+
+ <refpurpose>Add a signal event source to an event loop</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_add_signal</function></funcdef>
+ <paramdef>sd_event *<parameter>event</parameter></paramdef>
+ <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+ <paramdef>int <parameter>signal</parameter></paramdef>
+ <paramdef>sd_event_signal_handler_t <parameter>handler</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
+ <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+ <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
+ <funcdef>int <function>sd_event_source_get_signal</function></funcdef>
+ <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><function>sd_event_add_signal()</function> adds a new signal
+ event source to an event loop object. The event loop is specified
+ in <parameter>event</parameter>, the event source is returned in
+ the <parameter>source</parameter> parameter. The
+ <parameter>signal</parameter> parameter specifies the signal to be handled
+ (see
+ <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ The <parameter>handler</parameter> must reference a function to
+ call when the signal is delivered or be <constant>NULL</constant>.
+ The handler function will be passed the
+ <parameter>userdata</parameter> pointer, which may be chosen
+ freely by the caller. The handler also receives a pointer to a
+ <structname>const struct signalfd_siginfo</structname> containing
+ the information about the received signal. See
+ <citerefentry><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ for futher information.</para>
+
+ <para>Only a single handler may be installed for a specific
+ signal. The signal will be unblocked, and must be
+ blocked when the function is called. If the handler is not
+ specified (<parameter>handler</parameter> is
+ <constant>NULL</constant>), a default handler which causes the
+ program to exit will be used. By default, the handler is enabled
+ permanently (<constant>SD_EVENT_ON</constant>), but this may be
+ changed with
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ If the handler function returns a negative error code, it will be
+ disabled after the invocation, even if
+ <constant>SD_EVENT_ON</constant> mode is set.
+ </para>
+
+ <para><function>sd_event_source_get_signal()</function> retrieves
+ the configured signal number of a signal event source created
+ previously with <function>sd_event_add_signal()</function>. It
+ takes the event source object as the <parameter>source</parameter>
+ parameter.</para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+
+ <para>On success, these functions return 0 or a positive
+ integer. On failure, they return a negative errno-style error
+ code. </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Errors</title>
+
+ <para>Returned errors may indicate the following problems:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>-ENOMEM</varname></term>
+
+ <listitem><para>Not enough memory to allocate an object.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EINVAL</varname></term>
+
+ <listitem><para>An invalid argument has been passed.</para></listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-EBUSY</varname></term>
+
+ <listitem><para>An handler is already installed for this
+ signal or the signal was not blocked previously.</para></listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ESTALE</varname></term>
+
+ <listitem><para>The event loop is already terminated.</para></listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>-ECHILD</varname></term>
+
+ <listitem><para>The event loop has been created in a different process.</para></listitem>
+
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para><function>sd_event_add_signal()</function> and the 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-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml
index a3304f7985..d3775e5d5f 100644
--- a/man/sd_event_add_time.xml
+++ b/man/sd_event_add_time.xml
@@ -69,6 +69,13 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
</funcprototype>
<funcprototype>
+ <funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
+ <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
+ <paramdef>uint64_t <parameter>usec</parameter></paramdef>
+ <paramdef>void *<parameter>userdata</parameter></paramdef>
+ </funcprototype>
+
+ <funcprototype>
<funcdef>int <function>sd_event_source_get_time</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>usec_t *<parameter>usec</parameter></paramdef>
@@ -132,11 +139,15 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
actually have been called at a slightly later time, subject to the
specified accuracy value, the kernel timer slack (see
<citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
- and additional scheduling latencies. By default, the timer will
- elapse once (SD_EVENT_ONESHOT), but this may be changed with
- <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
- the handler function returns a negative error code, it will be
- disabled after the invocation, even if SD_EVENT_ON mode is set.
+ and additional scheduling latencies.</para>
+
+ <para>By default, the timer will elapse once
+ (<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
+ with
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
+ If the handler function returns a negative error code, it will be
+ disabled after the invocation, even if
+ <constant>SD_EVENT_ON</constant> mode is set.
</para>
<para><function>sd_event_source_get_time()</function> retrieves
@@ -187,7 +198,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<varlistentry>
<term><varname>-ENOMEM</varname></term>
- <listitem><para>Not enough memory to allocate object.</para></listitem>
+ <listitem><para>Not enough memory to allocate an object.</para></listitem>
</varlistentry>
<varlistentry>
@@ -237,6 +248,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>.
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>