Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsignal.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents 6a3ffc1dbb95
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{signal}}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{signal}
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
4 This module provides mechanisms to use signal handlers in Python.
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
5 Some general rules for working with signals handlers:
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
6
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
7 \begin{itemize}
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
8
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
9 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
10 A handler for a particular signal, once set, remains installed until
3378
6a3ffc1dbb95 document non-BSD SIGCHLD behaviour
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
11 it is explicitly reset (i.e. Python emulates the BSD style interface
6a3ffc1dbb95 document non-BSD SIGCHLD behaviour
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
12 regardless of the underlying implementation), with the exception of
6a3ffc1dbb95 document non-BSD SIGCHLD behaviour
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
13 the handler for \code{SIGCHLD}, which follows the underlying
6a3ffc1dbb95 document non-BSD SIGCHLD behaviour
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
14 implementation.
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
15
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
16 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
17 There is no way to ``block'' signals temporarily from critical
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
18 sections (since this is not supported by all \UNIX{} flavors).
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
19
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
20 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
21 Although Python signal handlers are called asynchronously as far as
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
22 the Python user is concerned, they can only occur between the
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
23 ``atomic'' instructions of the Python interpreter. This means that
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
24 signals arriving during long calculations implemented purely in C
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
25 (e.g.\ regular expression matches on large bodies of text) may be
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
26 delayed for an arbitrary amount of time.
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
27
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
28 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
29 When a signal arrives during an I/O operation, it is possible that the
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
30 I/O operation raises an exception after the signal handler returns.
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
31 This is dependent on the underlying \UNIX{} system's semantics regarding
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
32 interrupted system calls.
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
33
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
34 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
35 Because the C signal handler always returns, it makes little sense to
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
36 catch synchronous errors like \code{SIGFPE} or \code{SIGSEGV}.
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
37
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
38 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
39 Python installs a small number of signal handlers by default:
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
40 \code{SIGPIPE} is ignored (so write errors on pipes and sockets can be
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
41 reported as ordinary Python exceptions), \code{SIGINT} is translated
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
42 into a \code{KeyboardInterrupt} exception, and \code{SIGTERM} is
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
43 caught so that necessary cleanup (especially \code{sys.exitfunc}) can
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
44 be performed before actually terminating. All of these can be
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
45 overridden.
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
46
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
47 \item
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
48 Some care must be taken if both signals and threads are used in the
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
49 same program. The fundamental thing to remember in using signals and
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
50 threads simultaneously is:\ always perform \code{signal()} operations
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
51 in the main thread of execution. Any thread can perform an
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
52 \code{alarm()}, \code{getsignal()}, or \code{pause()}; only the main
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
53 thread can set a new signal handler, and the main thread will be the
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
54 only one to receive signals (this is enforced by the Python signal
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
55 module, even if the underlying thread implementation supports sending
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
56 signals to individual threads). This means that signals can't be used
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
57 as a means of interthread communication. Use locks instead.
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
58
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
59 \end{itemize}
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
60
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 The variables defined in the signal module are:
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
62
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 \renewcommand{\indexsubitem}{(in module signal)}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \begin{datadesc}{SIG_DFL}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 This is one of two standard signal handling options; it will simply
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 perform the default function for the signal. For example, on most
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 systems the default action for SIGQUIT is to dump core and exit,
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 while the default action for SIGCLD is to simply ignore it.
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 \end{datadesc}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
70
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 \begin{datadesc}{SIG_IGN}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 This is another standard signal handler, which will simply ignore
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 the given signal.
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 \end{datadesc}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
75
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 \begin{datadesc}{SIG*}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 All the signal numbers are defined symbolically. For example, the
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 hangup signal is defined as \code{signal.SIGHUP}; the variable names
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 are identical to the names used in C programs, as found in
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \file{signal.h}.
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
81 The \UNIX{} man page for \file{signal} lists the existing signals (on
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 some systems this is \file{signal(2)}, on others the list is in
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \file{signal(7)}).
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 Note that not all systems define the same set of signal names; only
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 those names defined by the system are defined by this module.
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 \end{datadesc}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
87
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
88 \begin{datadesc}{NSIG}
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
89 One more than the number of the highest signal number.
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
90 \end{datadesc}
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
91
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 The signal module defines the following functions:
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
93
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 \begin{funcdesc}{alarm}{time}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 If \var{time} is non-zero, this function requests that a
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 \code{SIGALRM} signal be sent to the process in \var{time} seconds.
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
97 Any previously scheduled alarm is canceled (i.e.\ only one alarm can
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 be scheduled at any time). The returned value is then the number of
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 seconds before any previously set alarm was to have been delivered.
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 If \var{time} is zero, no alarm id scheduled, and any scheduled
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 alarm is canceled. The return value is the number of seconds
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 remaining before a previously scheduled alarm. If the return value
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
103 is zero, no alarm is currently scheduled. (See the \UNIX{} man page
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 \code{alarm(2)}.)
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
105 \end{funcdesc}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
106
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 \begin{funcdesc}{getsignal}{signalnum}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
108 Return the current signal handler for the signal \var{signalnum}.
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 The returned value may be a callable Python object, or one of the
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
110 special values \code{signal.SIG_IGN}, \code{signal.SIG_DFL} or
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
111 \code{None}. Here, \code{signal.SIG_IGN} means that the signal was
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
112 previously ignored, \code{signal.SIG_DFL} means that the default way
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
113 of handling the signal was previously in use, and \code{None} means
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
114 that the previous signal handler was not installed from Python.
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \end{funcdesc}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
116
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 \begin{funcdesc}{pause}{}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
118 Cause the process to sleep until a signal is received; the
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 appropriate handler will then be called. Returns nothing. (See the
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
120 \UNIX{} man page \code{signal(2)}.)
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 \end{funcdesc}
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
122
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 \begin{funcdesc}{signal}{signalnum\, handler}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
124 Set the handler for signal \var{signalnum} to the function
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \var{handler}. \var{handler} can be any callable Python object, or
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
126 one of the special values \code{signal.SIG_IGN} or
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
127 \code{signal.SIG_DFL}. The previous signal handler will be returned
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
128 (see the description of \code{getsignal()} above). (See the \UNIX{}
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
129 man page \code{signal(2)}.)
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
130
2346
f09d3252a38b added lots of useful info
Guido van Rossum <guido@python.org>
parents: 2290
diff changeset
131 When threads are enabled, this function can only be called from the
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 main thread; attempting to call it from other threads will cause a
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2346
diff changeset
133 \code{ValueError} exception to be raised.
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
134
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
135 The \var{handler} is called with two arguments: the signal number
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
136 and the current stack frame (\code{None} or a frame object; see the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
137 reference manual for a description of frame objects).
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
138 \obindex{frame}
2290
f5a6e6ee529c added libsignal.tex
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \end{funcdesc}