man/sd_event_add_signal.xml

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