chiark / gitweb /
f39751d681c9a733064231f27b6fdb416f1a1594
[elogind.git] / 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 futher 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>