man/sd_event_add_signal.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright © 2014 Zbigniew Jędrzejewski-Szmek
   9 -->
  10
  11 <refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude">
  12
  13   <refentryinfo>
  14     <title>sd_event_add_signal</title>
  15     <productname>systemd</productname>
  16
  17     <authorgroup>
  18       <author>
  19         <contrib>More text</contrib>
  20         <firstname>Zbigniew</firstname>
  21         <surname>Jędrzejewski-Szmek</surname>
  22         <email>zbyszek@in.waw.pl</email>
  23       </author>
  24     </authorgroup>
  25   </refentryinfo>
  26
  27   <refmeta>
  28     <refentrytitle>sd_event_add_signal</refentrytitle>
  29     <manvolnum>3</manvolnum>
  30   </refmeta>
  31
  32   <refnamediv>
  33     <refname>sd_event_add_signal</refname>
  34     <refname>sd_event_source_get_signal</refname>
  35     <refname>sd_event_signal_handler_t</refname>
  36
  37     <refpurpose>Add a UNIX process signal event source to an event
  38     loop</refpurpose>
  39   </refnamediv>
  40
  41   <refsynopsisdiv>
  42     <funcsynopsis>
  43       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  44
  45       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  46
  47       <funcprototype>
  48         <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
  49         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  50         <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
  51         <paramdef>void *<parameter>userdata</parameter></paramdef>
  52       </funcprototype>
  53
  54       <funcprototype>
  55         <funcdef>int <function>sd_event_add_signal</function></funcdef>
  56         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  57         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  58         <paramdef>int <parameter>signal</parameter></paramdef>
  59         <paramdef>sd_event_signal_handler_t <parameter>handler</parameter></paramdef>
  60         <paramdef>void *<parameter>userdata</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_event_source_get_signal</function></funcdef>
  65         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  66       </funcprototype>
  67
  68     </funcsynopsis>
  69   </refsynopsisdiv>
  70
  71   <refsect1>
  72     <title>Description</title>
  73
  74     <para><function>sd_event_add_signal()</function> adds a new UNIX
  75     process signal event source to an event loop. The event loop
  76     object is specified in the <parameter>event</parameter> parameter,
  77     and the event source object is returned in the
  78     <parameter>source</parameter> parameter. The
  79     <parameter>signal</parameter> parameter specifies the numeric
  80     signal to be handled (see <citerefentry
  81     project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
  82     The <parameter>handler</parameter> parameter must reference a
  83     function to call when the signal is received or be
  84     <constant>NULL</constant>.  The handler function will be passed
  85     the <parameter>userdata</parameter> pointer, which may be chosen
  86     freely by the caller. The handler also receives a pointer to a
  87     <structname>signalfd_siginfo</structname> structure containing
  88     information about the received signal. See <citerefentry
  89     project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  90     for further information.</para>
  91
  92     <para>Only a single handler may be installed for a specific
  93     signal. The signal will be unblocked by this call, and must be
  94     blocked before this function is called in all threads (using
  95     <citerefentry
  96     project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If
  97     the handler is not specified (<parameter>handler</parameter> is
  98     <constant>NULL</constant>), a default handler which causes the
  99     program to exit cleanly will be used.</para>
 100
 101     <para>By default, the event source is enabled permanently
 102     (<constant>SD_EVENT_ON</constant>), but this may be changed with
 103     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 104     If the handler function returns a negative error code, it will be
 105     disabled after the invocation, even if the
 106     <constant>SD_EVENT_ON</constant> mode was requested before.
 107     </para>
 108
 109     <para>To destroy an event source object use
 110     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 111     but note that the event source is only removed from the event loop
 112     when all references to the event source are dropped. To make sure
 113     an event source does not fire anymore, even if it is still referenced,
 114     disable the event source using
 115     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 116     with <constant>SD_EVENT_OFF</constant>.</para>
 117
 118     <para>If the second parameter of
 119     <function>sd_event_add_signal()</function> is
 120     <constant>NULL</constant> no reference to the event source object
 121     is returned. In this case the event source is considered
 122     "floating", and will be destroyed implicitly when the event loop
 123     itself is destroyed.</para>
 124
 125     <para><function>sd_event_source_get_signal()</function> returns
 126     the configured signal number of an event source created previously
 127     with <function>sd_event_add_signal()</function>. It takes the
 128     event source object as the <parameter>source</parameter>
 129     parameter.</para>
 130   </refsect1>
 131
 132   <refsect1>
 133     <title>Return Value</title>
 134
 135     <para>On success, these functions return 0 or a positive
 136     integer. On failure, they return a negative errno-style error
 137     code.</para>
 138   </refsect1>
 139
 140   <refsect1>
 141     <title>Errors</title>
 142
 143     <para>Returned errors may indicate the following problems:</para>
 144
 145     <variablelist>
 146       <varlistentry>
 147         <term><constant>-ENOMEM</constant></term>
 148
 149         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><constant>-EINVAL</constant></term>
 154
 155         <listitem><para>An invalid argument has been passed.</para></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><constant>-EBUSY</constant></term>
 160
 161         <listitem><para>A handler is already installed for this
 162         signal or the signal was not blocked previously.</para></listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term><constant>-ESTALE</constant></term>
 167
 168         <listitem><para>The event loop is already terminated.</para></listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><constant>-ECHILD</constant></term>
 173
 174         <listitem><para>The event loop has been created in a different process.</para></listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term><constant>-EDOM</constant></term>
 179
 180         <listitem><para>The passed event source is not a signal event source.</para></listitem>
 181       </varlistentry>
 182
 183     </variablelist>
 184   </refsect1>
 185
 186   <xi:include href="libsystemd-pkgconfig.xml" />
 187
 188   <refsect1>
 189     <title>See Also</title>
 190
 191     <para>
 192       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 195       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 196       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 197       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 198       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 199       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 200       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 201       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 202       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 203       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 204       <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 205       <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 206     </para>
 207   </refsect1>
 208
 209 </refentry>