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 This file is part of systemd.
   7
   8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10 systemd is free software; you can redistribute it and/or modify it
  11 under the terms of the GNU Lesser General Public License as published by
  12 the Free Software Foundation; either version 2.1 of the License, or
  13 (at your option) any later version.
  14
  15 systemd is distributed in the hope that it will be useful, but
  16 WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18 Lesser General Public License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public License
  21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_event_add_signal" conditional="ENABLE_KDBUS">
  25
  26   <refentryinfo>
  27     <title>sd_event_add_signal</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>More text</contrib>
  33         <firstname>Zbigniew</firstname>
  34         <surname>Jędrzejewski-Szmek</surname>
  35         <email>zbyszek@in.waw.pl</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_event_add_signal</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_event_add_signal</refname>
  47     <refname>sd_event_source_get_signal</refname>
  48
  49     <refpurpose>Add a signal event source to an event loop</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <funcsynopsis>
  54       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_event_add_signal</function></funcdef>
  58         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  59         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  60         <paramdef>int <parameter>signal</parameter></paramdef>
  61         <paramdef>sd_event_signal_handler_t <parameter>handler</parameter></paramdef>
  62         <paramdef>void *<parameter>userdata</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
  67         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  68         <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
  69         <paramdef>void *<parameter>userdata</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_event_source_get_signal</function></funcdef>
  74         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  75       </funcprototype>
  76
  77     </funcsynopsis>
  78   </refsynopsisdiv>
  79
  80   <refsect1>
  81     <title>Description</title>
  82
  83     <para><function>sd_event_add_signal()</function> adds a new signal
  84     event source to an event loop object. The event loop is specified
  85     in <parameter>event</parameter>, the event source is returned in
  86     the <parameter>source</parameter> parameter. The
  87     <parameter>signal</parameter> parameter specifies the signal to be handled
  88     (see
  89     <citerefentry><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
  90     The <parameter>handler</parameter> must reference a function to
  91     call when the signal is delivered or be <constant>NULL</constant>.
  92     The handler function will be passed the
  93     <parameter>userdata</parameter> pointer, which may be chosen
  94     freely by the caller. The handler also receives a pointer to a
  95     <structname>const struct signalfd_siginfo</structname> containing
  96     the information about the received signal. See
  97     <citerefentry><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  98     for further information.</para>
  99
 100     <para>Only a single handler may be installed for a specific
 101     signal. The signal will be unblocked, and must be
 102     blocked when the function is called. If the handler is not
 103     specified (<parameter>handler</parameter> is
 104     <constant>NULL</constant>), a default handler which causes the
 105     program to exit will be used.  By default, the handler is enabled
 106     permanently (<constant>SD_EVENT_ON</constant>), but this may be
 107     changed with
 108     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 109     If the handler function returns a negative error code, it will be
 110     disabled after the invocation, even if
 111     <constant>SD_EVENT_ON</constant> mode is set.
 112     </para>
 113
 114     <para><function>sd_event_source_get_signal()</function> retrieves
 115     the configured signal number of a signal event source created
 116     previously with <function>sd_event_add_signal()</function>. It
 117     takes the event source object as the <parameter>source</parameter>
 118     parameter.</para>
 119
 120   </refsect1>
 121
 122   <refsect1>
 123     <title>Return Value</title>
 124
 125     <para>On success, these functions return 0 or a positive
 126     integer. On failure, they return a negative errno-style error
 127     code. </para>
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Errors</title>
 132
 133     <para>Returned errors may indicate the following problems:</para>
 134
 135     <variablelist>
 136       <varlistentry>
 137         <term><constant>-ENOMEM</constant></term>
 138
 139         <listitem><para>Not enough memory to allocate an object.</para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><constant>-EINVAL</constant></term>
 144
 145         <listitem><para>An invalid argument has been passed.</para></listitem>
 146
 147       </varlistentry>
 148
 149       <varlistentry>
 150         <term><constant>-EBUSY</constant></term>
 151
 152         <listitem><para>An handler is already installed for this
 153         signal or the signal was not blocked previously.</para></listitem>
 154
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><constant>-ESTALE</constant></term>
 159
 160         <listitem><para>The event loop is already terminated.</para></listitem>
 161
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term><constant>-ECHILD</constant></term>
 166
 167         <listitem><para>The event loop has been created in a different process.</para></listitem>
 168
 169       </varlistentry>
 170
 171     </variablelist>
 172   </refsect1>
 173
 174   <refsect1>
 175     <title>Notes</title>
 176
 177     <para><function>sd_event_add_signal()</function> and the other functions
 178     described here are available as a shared library, which can be
 179     compiled and linked to with the
 180     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 181     file.</para>
 182   </refsect1>
 183
 184   <refsect1>
 185     <title>See Also</title>
 186
 187     <para>
 188       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 195     </para>
 196   </refsect1>
 197
 198 </refentry>