From: Kim F. Storm <storm@cua.dk>
Date: Tue, 19 Dec 2006 15:38:08 +0000 (+0000)
Subject: (Misc Events): User signals now result in sigusr1
X-Git-Tag: emacs-pretest-22.0.92~9
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=f68903b317e0bbddd03b8e2da1e9afedb2afeb47;p=emacs.git

(Misc Events): User signals now result in sigusr1
and sigusr2 events which are handled through special-event-map.
(Special Events): User signals and drag-n-drop are special.
---

diff --git a/lispref/commands.texi b/lispref/commands.texi
index 7188961e344..0f45ddbdd04 100644
--- a/lispref/commands.texi
+++ b/lispref/commands.texi
@@ -1586,14 +1586,33 @@ The precise meaning of the event parameters and the way these
 parameters are used to display the help-echo text are described in
 @ref{Text help-echo}.
 
-@cindex @code{signal usr1} event
-@cindex @code{signal usr2} event
+@cindex @code{sigusr1} event
+@cindex @code{sigusr2} event
 @cindex user signals
-@item signal usr1
-@itemx signal usr2
-These event sequences are generated when the Emacs process receives
+@item sigusr1
+@itemx sigusr2
+These events are generated when the Emacs process receives
 the signals @code{SIGUSR1} and @code{SIGUSR2}.  They contain no
 additional data because signals do not carry additional information.
+
+To catch a user signal, bind the corresponding event to an interactive
+command in the @code{special-event-map} (@pxref{Active Keymaps}).
+The command is called with no arguments, and the specific signal event is
+available in @code{last-input-event}.  For example:
+
+@example
+(defun sigusr-handler ()
+  (interactive)
+  (message "Caught signal %S" last-input-event))
+
+(define-key special-event-map [sigusr1] 'sigusr-handler)
+@end example
+
+To test the signal handler, you can make Emacs send a signal to itself:
+
+@example
+(signal-process (emacs-pid) 'sigusr1)
+@end example
 @end table
 
   If one of these events arrives in the middle of a key sequence---that
@@ -2634,8 +2653,9 @@ These events do, however, appear in @code{last-input-event} immediately
 after they are read, and this is the way for the event's definition to
 find the actual event.
 
-The events types @code{iconify-frame}, @code{make-frame-visible} and
-@code{delete-frame} are normally handled in this way.  The keymap which
+The events types @code{iconify-frame}, @code{make-frame-visible},
+@code{delete-frame}, @code{drag-n-drop}, and user signals like
+@code{sigusr1} are normally handled in this way.  The keymap which
 defines how to handle special events---and which events are special---is
 in the variable @code{special-event-map} (@pxref{Active Keymaps}).