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