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