← Back to branch summary

~ubuntu-branches/ubuntu/lucid/libxfce4util/lucid

« back to all changes in this revision

Viewing changes to docs/xml/xfce-posix-signal-handler.xml

  • Committer: Bazaar Package Importer
  • Author(s): Michael Casadevall
  • Date: 2009-01-17 15:36:28 UTC
  • mfrom: (1.2.13 upstream)
  • Revision ID: james.westby@ubuntu.com-20090117153628-ulyk11ozaa2b19tk
Tags: 4.5.93-0ubuntu1
* Merge with Debian Xfce UNRELEASED, remaining Ubuntu changes:
  - debian/control:
    - added gtk-doc-tools to build-deps
  - debian/rules: 
    - pass --enable-gtk-doc to ./configure
  - debian/patches/series: 
    - don't apply 01_add-desktop-base-in-config-dirs.patch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/xml/xfce-posix-signal-handler.xml
 
1
<refentry id="libxfce4util-POSIX-Signal-Handling">
 
2
<refmeta>
 
3
<refentrytitle role="top_of_page" id="libxfce4util-POSIX-Signal-Handling.top_of_page">POSIX Signal Handling</refentrytitle>
 
4
<manvolnum>3</manvolnum>
 
5
<refmiscinfo>LIBXFCE4UTIL Library</refmiscinfo>
 
6
</refmeta>
 
7
 
 
8
<refnamediv>
 
9
<refname>POSIX Signal Handling</refname>
 
10
<refpurpose>a callback system for handling POSIX signals safely</refpurpose>
 
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
 
12
</refnamediv>
 
13
 
 
14
<refsynopsisdiv id="libxfce4util-POSIX-Signal-Handling.synopsis" role="synopsis">
 
15
<title role="synopsis.title">Synopsis</title>
 
16
 
 
17
<synopsis>
 
18
 
 
19
#include &lt;libxfce4util/libxfce4util.h&gt;
 
20
 
 
21
<link linkend="void">void</link>                (<link linkend="XfcePosixSignalHandler">*XfcePosixSignalHandler</link>)           (<link linkend="gint">gint</link> signal,
 
22
                                                         <link linkend="gpointer">gpointer</link> user_data);
 
23
<link linkend="gboolean">gboolean</link>            <link linkend="xfce-posix-signal-handler-init">xfce_posix_signal_handler_init</link>      (<link linkend="GError">GError</link> **error);
 
24
<link linkend="void">void</link>                <link linkend="xfce-posix-signal-handler-restore-handler">xfce_posix_signal_handler_restore_handler</link>
 
25
                                                        (<link linkend="gint">gint</link> signal);
 
26
<link linkend="gboolean">gboolean</link>            <link linkend="xfce-posix-signal-handler-set-handler">xfce_posix_signal_handler_set_handler</link>
 
27
                                                        (<link linkend="gint">gint</link> signal,
 
28
                                                         <link linkend="XfcePosixSignalHandler">XfcePosixSignalHandler</link> handler,
 
29
                                                         <link linkend="gpointer">gpointer</link> user_data,
 
30
                                                         <link linkend="GError">GError</link> **error);
 
31
<link linkend="void">void</link>                <link linkend="xfce-posix-signal-handler-shutdown">xfce_posix_signal_handler_shutdown</link>  ();
 
32
</synopsis>
 
33
</refsynopsisdiv>
 
34
 
 
35
 
 
36
 
 
37
 
 
38
 
 
39
 
 
40
 
 
41
 
 
42
 
 
43
<refsect1 id="libxfce4util-POSIX-Signal-Handling.description" role="desc">
 
44
<title role="desc.title">Description</title>
 
45
<para>
 
46
Due to reentrancy issues, there is a restricted set of functions/syscalls
 
47
that are allowed to be performed inside a POSIX signal handler.  In
 
48
general, it's safer to defer any signal-related processing until after the
 
49
signal handler has run.  The functionality in this module automatically
 
50
handles this, and allows you to set a handler function (with optional user
 
51
data) for any signal.
 
52
</para>
 
53
</refsect1>
 
54
 
 
55
<refsect1 id="libxfce4util-POSIX-Signal-Handling.details" role="details">
 
56
<title role="details.title">Details</title>
 
57
<refsect2 id="XfcePosixSignalHandler" role="function">
 
58
<title>XfcePosixSignalHandler ()</title>
 
59
<indexterm zone="XfcePosixSignalHandler"><primary>XfcePosixSignalHandler</primary></indexterm><programlisting><link linkend="void">void</link>                (*XfcePosixSignalHandler)           (<link linkend="gint">gint</link> signal,
 
60
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 
61
<para>
 
62
A function signature to use for POSIX signal handler functions.
 
63
</para><variablelist role="params">
 
64
<varlistentry><term><parameter>signal</parameter>&nbsp;:</term>
 
65
<listitem><simpara>The signal that was caught.
 
66
</simpara></listitem></varlistentry>
 
67
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
68
<listitem><simpara>The <parameter>user_data</parameter> parameter passed when the handler was registered.
 
69
 
 
70
 
 
71
</simpara></listitem></varlistentry>
 
72
</variablelist></refsect2>
 
73
<refsect2 id="xfce-posix-signal-handler-init" role="function">
 
74
<title>xfce_posix_signal_handler_init ()</title>
 
75
<indexterm zone="xfce-posix-signal-handler-init"><primary>xfce_posix_signal_handler_init</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            xfce_posix_signal_handler_init      (<link linkend="GError">GError</link> **error);</programlisting>
 
76
<para>
 
77
Initializes the POSIX signal handler system.  Must be called
 
78
before setting any POSIX signal handlers.</para>
 
79
<para>
 
80
 
 
81
</para><variablelist role="params">
 
82
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
83
<listitem><simpara> Location of a <link linkend="GError"><type>GError</type></link> to store any possible errors.
 
84
</simpara></listitem></varlistentry>
 
85
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> on failure, in which case
 
86
         <parameter>error</parameter> will be set.
 
87
</simpara></listitem></varlistentry>
 
88
</variablelist></refsect2>
 
89
<refsect2 id="xfce-posix-signal-handler-restore-handler" role="function">
 
90
<title>xfce_posix_signal_handler_restore_handler ()</title>
 
91
<indexterm zone="xfce-posix-signal-handler-restore-handler"><primary>xfce_posix_signal_handler_restore_handler</primary></indexterm><programlisting><link linkend="void">void</link>                xfce_posix_signal_handler_restore_handler
 
92
                                                        (<link linkend="gint">gint</link> signal);</programlisting>
 
93
<para>
 
94
Restores the default handler for <parameter>signal</parameter>.</para>
 
95
<para>
 
96
 
 
97
</para><variablelist role="params">
 
98
<varlistentry><term><parameter>signal</parameter>&nbsp;:</term>
 
99
<listitem><simpara> A POSIX signal id number.
 
100
</simpara></listitem></varlistentry>
 
101
</variablelist></refsect2>
 
102
<refsect2 id="xfce-posix-signal-handler-set-handler" role="function">
 
103
<title>xfce_posix_signal_handler_set_handler ()</title>
 
104
<indexterm zone="xfce-posix-signal-handler-set-handler"><primary>xfce_posix_signal_handler_set_handler</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            xfce_posix_signal_handler_set_handler
 
105
                                                        (<link linkend="gint">gint</link> signal,
 
106
                                                         <link linkend="XfcePosixSignalHandler">XfcePosixSignalHandler</link> handler,
 
107
                                                         <link linkend="gpointer">gpointer</link> user_data,
 
108
                                                         <link linkend="GError">GError</link> **error);</programlisting>
 
109
<para>
 
110
Sets <parameter>handler</parameter> to be called whenever <parameter>signal</parameter> is caught by the
 
111
application.  The <parameter>user_data</parameter> parameter will be passed as an argument
 
112
to <parameter>handler</parameter>.</para>
 
113
<para>
 
114
 
 
115
</para><variablelist role="params">
 
116
<varlistentry><term><parameter>signal</parameter>&nbsp;:</term>
 
117
<listitem><simpara> A POSIX signal id number.
 
118
</simpara></listitem></varlistentry>
 
119
<varlistentry><term><parameter>handler</parameter>&nbsp;:</term>
 
120
<listitem><simpara> A callback function.
 
121
</simpara></listitem></varlistentry>
 
122
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
123
<listitem><simpara> Arbitrary data that will be passed to <parameter>handler</parameter>.
 
124
</simpara></listitem></varlistentry>
 
125
<varlistentry><term><parameter>error</parameter>&nbsp;:</term>
 
126
<listitem><simpara> Location of a <link linkend="GError"><type>GError</type></link> to store any possible errors.
 
127
</simpara></listitem></varlistentry>
 
128
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise, in which case
 
129
         <parameter>error</parameter> will be set.
 
130
</simpara></listitem></varlistentry>
 
131
</variablelist></refsect2>
 
132
<refsect2 id="xfce-posix-signal-handler-shutdown" role="function">
 
133
<title>xfce_posix_signal_handler_shutdown ()</title>
 
134
<indexterm zone="xfce-posix-signal-handler-shutdown"><primary>xfce_posix_signal_handler_shutdown</primary></indexterm><programlisting><link linkend="void">void</link>                xfce_posix_signal_handler_shutdown  ();</programlisting>
 
135
<para>
 
136
Frees all memory associated with the POSIX signal handling system
 
137
and restores all default signal handlers.</para>
 
138
<para>
 
139
 
 
140
</para></refsect2>
 
141
 
 
142
</refsect1>
 
143
 
 
144
 
 
145
 
 
146
 
 
147
</refentry>