summaryrefslogtreecommitdiff
path: root/man/sd_event_add_signal.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/sd_event_add_signal.xml')
-rw-r--r--man/sd_event_add_signal.xml118
1 files changed, 73 insertions, 45 deletions
diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml
index 0923fe0ae7..b5312735d2 100644
--- a/man/sd_event_add_signal.xml
+++ b/man/sd_event_add_signal.xml
@@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="sd_event_add_signal">
+<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_signal</title>
@@ -45,13 +45,24 @@
<refnamediv>
<refname>sd_event_add_signal</refname>
<refname>sd_event_source_get_signal</refname>
+ <refname>sd_event_signal_handler_t</refname>
- <refpurpose>Add a signal event source to an event loop</refpurpose>
+ <refpurpose>Add a UNIX process signal event source to an event
+ loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
- <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
+ <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
+
+ <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
+
+ <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_add_signal</function></funcdef>
@@ -63,13 +74,6 @@
</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>
@@ -80,41 +84,61 @@
<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>, and the event source is returned in
- the <parameter>source</parameter> parameter. The
- <parameter>signal</parameter> parameter specifies the signal to be handled
- (see
- <citerefentry project='man-pages'><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
+ <para><function>sd_event_add_signal()</function> adds a new UNIX
+ process signal event source to an event loop. The event loop
+ object is specified in the <parameter>event</parameter> parameter,
+ and the event source object is returned in the
+ <parameter>source</parameter> parameter. The
+ <parameter>signal</parameter> parameter specifies the numeric
+ signal to be handled (see <citerefentry
+ project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
+ The <parameter>handler</parameter> parameter must reference a
+ function to call when the signal is received 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 project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ <structname>signalfd_siginfo</structname> structure containing
+ information about the received signal. See <citerefentry
+ project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for further 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
+ signal. The signal will be unblocked by this call, and must be
+ blocked before this function is called in all threads (using
+ <citerefentry
+ project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). 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
+ program to exit cleanly will be used.</para>
+
+ <para>By default, the event source 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.
+ disabled after the invocation, even if the
+ <constant>SD_EVENT_ON</constant> mode was requested before.
</para>
+ <para>To destroy an event source object use
+ <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ but note that the event source is only removed from the event loop
+ when all references to the event source are dropped. To make sure
+ an event source does not fire anymore, even when there's still a
+ reference to it kept, consider setting the event source to
+ <constant>SD_EVENT_OFF</constant> with
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+ <para>If the the second parameter of
+ <function>sd_event_add_signal()</function> is passed as NULL no
+ reference to the event source object is returned. In this case the
+ event source is considered "floating", and will be destroyed
+ implicitly when the event loop itself is destroyed.</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>
+ the configured UNIX process 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>
@@ -168,19 +192,17 @@
</varlistentry>
- </variablelist>
- </refsect1>
+ <varlistentry>
+ <term><constant>-EDOM</constant></term>
- <refsect1>
- <title>Notes</title>
+ <listitem><para>The passed event source is not a signal event source.</para></listitem>
+ </varlistentry>
- <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>
+ </variablelist>
</refsect1>
+ <xi:include href="libsystemd-pkgconfig.xml" />
+
<refsect1>
<title>See Also</title>
@@ -188,10 +210,16 @@
<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_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>