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