Commit | Line | Data |
---|---|---|
9f8886c7 | 1 | .\" -*-nroff-*- |
fbf20b5b | 2 | .TH sel 3 "23 July 1999" "Straylight/Edgeware" "mLib utilities library" |
9f8886c7 | 3 | .SH NAME |
4 | sig \- more controlled signal handling | |
5 | .\" @sig_init | |
6 | .\" @sig_add | |
7 | .\" @sig_remove | |
8 | .SH SYNOPSIS | |
9 | .nf | |
10 | .B "#include <mLib/sig.h>" | |
11 | ||
4729aa69 MW |
12 | .B "typedef struct { ...\& } sig;" |
13 | ||
adec5584 MW |
14 | .ta \w'\fBvoid sig_add('u |
15 | .BI "void sig_add(sig *" s ", int " n , | |
16 | .BI " void (*" proc ")(int " n ", void *" p "), void *" p ); | |
9f8886c7 | 17 | .BI "void sig_remove(sig *" s ); |
18 | .BI "void sig_init(sel_state *" s ); | |
19 | .fi | |
20 | .SH "DESCRIPTION" | |
21 | The | |
22 | .B sig | |
23 | subsystem uses the I/O multiplexing capabilities of | |
24 | .B mLib | |
25 | (see | |
d4704dee | 26 | .BR sel (3) |
27 | for details) to provide a more convenient interface for handling signals | |
28 | which don't need to be dealt with `right away'. Like the I/O system, | |
9f8886c7 | 29 | .B sig |
30 | doesn't allocate any memory for itself: you have to give it space to | |
31 | work in. | |
32 | .PP | |
33 | The system needs to be initialized before use. To do this, you must | |
34 | call | |
35 | .BR sig_init , | |
36 | passing it the address of an initialized multiplexor object. Signals | |
37 | handled through this interface will only be delivered when | |
38 | .BR sel_select (3) | |
39 | is called on that multiplexor. | |
40 | .PP | |
41 | To register interest in a signal, call | |
42 | .BR sig_add , | |
43 | passing it the following arguments: | |
44 | .TP | |
b78d1e6d | 45 | .BI "sig *" s |
9f8886c7 | 46 | A pointer to an (uninitialized) object of type |
47 | .BR sig . | |
48 | This will be used by the system to retain information about this signal | |
49 | claim. You use the address of this object to remove the handler again | |
50 | when you've finished. | |
51 | .TP | |
b78d1e6d | 52 | .BI "int " n |
9f8886c7 | 53 | The number of the signal you want to handle. |
54 | .PP | |
55 | .TP | |
b78d1e6d | 56 | .BI "void (*" proc ")(int " n ", void *" p ) |
9f8886c7 | 57 | A function to call when the signal is detected. The function is passed |
58 | the signal number and the pointer | |
59 | .I p | |
60 | passed to | |
61 | .BR sig_add . | |
62 | .TP | |
b78d1e6d | 63 | .BI "void *" p |
9f8886c7 | 64 | A pointer argument to be passed to |
65 | .I func | |
66 | when the signal is detected. | |
67 | .PP | |
68 | Removing a handler is easy. Call | |
69 | .B sig_remove | |
70 | with the address of the | |
71 | .B sig | |
72 | structure you passed to | |
73 | .BR sig_add . | |
74 | .SS "Multiple signal handlers" | |
75 | You may have multiple signal handlers for a signal. All of them are | |
76 | called in some unspecified order when the signal occurs. | |
77 | .PP | |
78 | A signal's disposition is remembered when a handler for it is added and | |
79 | there are no handlers already registered. When the last handler for a | |
80 | signal is removed, its disposition is restored to its initial remembered | |
81 | state. | |
82 | .SH "BUGS AND CAVEATS" | |
83 | The | |
84 | .B sig | |
85 | system attempts to set the | |
86 | .B SA_RESTART | |
87 | flag on signal handlers it creates that signal occurrences don't | |
88 | interrupt system calls. This won't be done on systems which don't | |
89 | define this flag, for obvious reasons. | |
90 | .PP | |
91 | The | |
92 | .B SA_NOCLDSTOP | |
93 | flag is also set, so that stopped child processes aren't reported by a | |
94 | signal. This is normally right, but ought to be configurable. | |
9f8886c7 | 95 | .SH "AUTHOR" |
9b5ac6ff | 96 | Mark Wooding, <mdw@distorted.org.uk> |