1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_add_signal</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_add_signal</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_add_signal</refname> 20 <refname>sd_event_source_get_signal</refname> 21 <refname>sd_event_signal_handler_t</refname> 22 23 <refpurpose>Add a UNIX process signal event source to an event 24 loop</refpurpose> 25 </refnamediv> 26 27 <refsynopsisdiv> 28 <funcsynopsis> 29 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 30 31 <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> 32 33 <funcprototype> 34 <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> 35 <paramdef>sd_event_source *<parameter>s</parameter></paramdef> 36 <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> 37 <paramdef>void *<parameter>userdata</parameter></paramdef> 38 </funcprototype> 39 40 <funcprototype> 41 <funcdef>int <function>sd_event_add_signal</function></funcdef> 42 <paramdef>sd_event *<parameter>event</parameter></paramdef> 43 <paramdef>sd_event_source **<parameter>source</parameter></paramdef> 44 <paramdef>int <parameter>signal</parameter></paramdef> 45 <paramdef>sd_event_signal_handler_t <parameter>handler</parameter></paramdef> 46 <paramdef>void *<parameter>userdata</parameter></paramdef> 47 </funcprototype> 48 49 <funcprototype> 50 <funcdef>int <function>sd_event_source_get_signal</function></funcdef> 51 <paramdef>sd_event_source *<parameter>source</parameter></paramdef> 52 </funcprototype> 53 54 </funcsynopsis> 55 </refsynopsisdiv> 56 57 <refsect1> 58 <title>Description</title> 59 60 <para><function>sd_event_add_signal()</function> adds a new UNIX 61 process signal event source to an event loop. The event loop 62 object is specified in the <parameter>event</parameter> parameter, 63 and the event source object is returned in the 64 <parameter>source</parameter> parameter. The 65 <parameter>signal</parameter> parameter specifies the numeric 66 signal to be handled (see <citerefentry 67 project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).</para> 68 69 <para>The <parameter>handler</parameter> parameter is a function to call when the signal is received or 70 <constant>NULL</constant>. The handler function will be passed the <parameter>userdata</parameter> 71 pointer, which may be chosen freely by the caller. The handler also receives a pointer to a 72 <structname>signalfd_siginfo</structname> structure containing information about the received signal. See 73 <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> 74 for further information. The handler may return negative to signal an error (see below), other return 75 values are ignored. If <parameter>handler</parameter> is <constant>NULL</constant>, a default handler 76 that calls 77 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be 78 used.</para> 79 80 <para>Only a single handler may be installed for a specific signal. The signal must be blocked in all 81 threads before this function is called (using <citerefentry 82 project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry> or 83 <citerefentry 84 project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry>).</para> 85 86 <para>By default, the event source is enabled permanently 87 (<constant>SD_EVENT_ON</constant>), but this may be changed with 88 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 89 If the handler function returns a negative error code, it will either be disabled after the 90 invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested before, or it will cause the 91 loop to terminate, see 92 <citerefentry><refentrytitle>sd_event_source_set_exit_on_failure</refentrytitle><manvolnum>3</manvolnum></citerefentry>. 93 </para> 94 95 <para>To destroy an event source object use 96 <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 97 but note that the event source is only removed from the event loop 98 when all references to the event source are dropped. To make sure 99 an event source does not fire anymore, even if it is still referenced, 100 disable the event source using 101 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> 102 with <constant>SD_EVENT_OFF</constant>.</para> 103 104 <para>If the second parameter of 105 <function>sd_event_add_signal()</function> is 106 <constant>NULL</constant> no reference to the event source object 107 is returned. In this case the event source is considered 108 "floating", and will be destroyed implicitly when the event loop 109 itself is destroyed.</para> 110 111 <para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_signal()</function> is 112 <constant>NULL</constant>, and the event source fires, this will be considered a request to exit the 113 event loop. In this case, the <parameter>userdata</parameter> parameter, cast to an integer, is passed as 114 the exit code parameter to 115 <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 116 117 <para><function>sd_event_source_get_signal()</function> returns 118 the configured signal number of an event source created previously 119 with <function>sd_event_add_signal()</function>. It takes the 120 event source object as the <parameter>source</parameter> 121 parameter.</para> 122 </refsect1> 123 124 <refsect1> 125 <title>Return Value</title> 126 127 <para>On success, these functions return 0 or a positive 128 integer. On failure, they return a negative errno-style error 129 code.</para> 130 131 <refsect2> 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 </refsect2> 176 </refsect1> 177 178 <xi:include href="libsystemd-pkgconfig.xml" /> 179 180 <refsect1> 181 <title>See Also</title> 182 183 <para> 184 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 185 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 186 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 187 <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 188 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 189 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 190 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 191 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 192 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 193 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 194 <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 195 <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 196 <citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 197 <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, 198 <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 199 <citerefentry project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>, 200 <citerefentry project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry> 201 </para> 202 </refsect1> 203 204</refentry> 205