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