diff options
Diffstat (limited to 'man/sd_event_add_signal.xml')
| -rw-r--r-- | man/sd_event_add_signal.xml | 118 |
1 files changed, 73 insertions, 45 deletions
diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 0923fe0ae7..b5312735d2 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -21,7 +21,7 @@ along with systemd; If not, see <http://www.gnu.org/licenses/>. --> -<refentry id="sd_event_add_signal"> +<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_event_add_signal</title> @@ -45,13 +45,24 @@ <refnamediv> <refname>sd_event_add_signal</refname> <refname>sd_event_source_get_signal</refname> + <refname>sd_event_signal_handler_t</refname> - <refpurpose>Add a signal event source to an event loop</refpurpose> + <refpurpose>Add a UNIX process signal event source to an event + loop</refpurpose> </refnamediv> <refsynopsisdiv> <funcsynopsis> - <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> + <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> + + <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> + <paramdef>sd_event_source *<parameter>s</parameter></paramdef> + <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> <funcprototype> <funcdef>int <function>sd_event_add_signal</function></funcdef> @@ -63,13 +74,6 @@ </funcprototype> <funcprototype> - <funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef> - <paramdef>sd_event_source *<parameter>s</parameter></paramdef> - <paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef> - <paramdef>void *<parameter>userdata</parameter></paramdef> - </funcprototype> - - <funcprototype> <funcdef>int <function>sd_event_source_get_signal</function></funcdef> <paramdef>sd_event_source *<parameter>source</parameter></paramdef> </funcprototype> @@ -80,41 +84,61 @@ <refsect1> <title>Description</title> - <para><function>sd_event_add_signal()</function> adds a new signal - event source to an event loop object. The event loop is specified - in <parameter>event</parameter>, and the event source is returned in - the <parameter>source</parameter> parameter. The - <parameter>signal</parameter> parameter specifies the signal to be handled - (see - <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>). - The <parameter>handler</parameter> must reference a function to - call when the signal is delivered or be <constant>NULL</constant>. - The handler function will be passed the - <parameter>userdata</parameter> pointer, which may be chosen + <para><function>sd_event_add_signal()</function> adds a new UNIX + process signal event source to an event loop. The event loop + object is specified in the <parameter>event</parameter> parameter, + and the event source object is returned in the + <parameter>source</parameter> parameter. The + <parameter>signal</parameter> parameter specifies the numeric + signal to be handled (see <citerefentry + project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>). + The <parameter>handler</parameter> parameter must reference a + function to call when the signal is received or be + <constant>NULL</constant>. The handler function will be passed + the <parameter>userdata</parameter> pointer, which may be chosen freely by the caller. The handler also receives a pointer to a - <structname>const struct signalfd_siginfo</structname> containing - the information about the received signal. See - <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> + <structname>signalfd_siginfo</structname> structure containing + information about the received signal. See <citerefentry + project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> for further information.</para> <para>Only a single handler may be installed for a specific - signal. The signal will be unblocked, and must be - blocked when the function is called. If the handler is not - specified (<parameter>handler</parameter> is + signal. The signal will be unblocked by this call, and must be + blocked before this function is called in all threads (using + <citerefentry + project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If + the handler is not specified (<parameter>handler</parameter> is <constant>NULL</constant>), a default handler which causes the - program to exit will be used. By default, the handler is enabled - permanently (<constant>SD_EVENT_ON</constant>), but this may be - changed with + program to exit cleanly will be used.</para> + + <para>By default, the event source is enabled permanently + (<constant>SD_EVENT_ON</constant>), but this may be changed with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If the handler function returns a negative error code, it will be - disabled after the invocation, even if - <constant>SD_EVENT_ON</constant> mode is set. + disabled after the invocation, even if the + <constant>SD_EVENT_ON</constant> mode was requested before. </para> + <para>To destroy an event source object use + <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + but note that the event source is only removed from the event loop + when all references to the event source are dropped. To make sure + an event source does not fire anymore, even when there's still a + reference to it kept, consider setting the event source to + <constant>SD_EVENT_OFF</constant> with + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> + + <para>If the the second parameter of + <function>sd_event_add_signal()</function> is passed as NULL no + reference to the event source object is returned. In this case the + event source is considered "floating", and will be destroyed + implicitly when the event loop itself is destroyed.</para> + <para><function>sd_event_source_get_signal()</function> retrieves - the configured signal number of a signal event source created - previously with <function>sd_event_add_signal()</function>. It - takes the event source object as the <parameter>source</parameter> + the configured UNIX process signal number of a signal event source + created previously with + <function>sd_event_add_signal()</function>. It takes the event + source object as the <parameter>source</parameter> parameter.</para> </refsect1> @@ -168,19 +192,17 @@ </varlistentry> - </variablelist> - </refsect1> + <varlistentry> + <term><constant>-EDOM</constant></term> - <refsect1> - <title>Notes</title> + <listitem><para>The passed event source is not a signal event source.</para></listitem> + </varlistentry> - <para><function>sd_event_add_signal()</function> and the other functions - described here are available as a shared library, which can be - compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + </variablelist> </refsect1> + <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> <title>See Also</title> @@ -188,10 +210,16 @@ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry> </para> </refsect1> |