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