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