| 1 | .\" -*-nroff-*- |
| 2 | .\" |
| 3 | .\" Manual for in-band signal handling |
| 4 | .\" |
| 5 | .\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware |
| 6 | .\" |
| 7 | . |
| 8 | .\"----- Licensing notice --------------------------------------------------- |
| 9 | .\" |
| 10 | .\" This file is part of the mLib utilities library. |
| 11 | .\" |
| 12 | .\" mLib is free software: you can redistribute it and/or modify it under |
| 13 | .\" the terms of the GNU Library General Public License as published by |
| 14 | .\" the Free Software Foundation; either version 2 of the License, or (at |
| 15 | .\" your option) any later version. |
| 16 | .\" |
| 17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT |
| 18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
| 20 | .\" License for more details. |
| 21 | .\" |
| 22 | .\" You should have received a copy of the GNU Library General Public |
| 23 | .\" License along with mLib. If not, write to the Free Software |
| 24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, |
| 25 | .\" USA. |
| 26 | . |
| 27 | .\"-------------------------------------------------------------------------- |
| 28 | .so ../defs.man \" @@@PRE@@@ |
| 29 | . |
| 30 | .\"-------------------------------------------------------------------------- |
| 31 | .TH sel 3mLib "23 July 1999" "Straylight/Edgeware" "mLib utilities library" |
| 32 | .\" @sig_init |
| 33 | .\" @sig_add |
| 34 | .\" @sig_remove |
| 35 | . |
| 36 | .\"-------------------------------------------------------------------------- |
| 37 | .SH NAME |
| 38 | sig \- more controlled signal handling |
| 39 | . |
| 40 | .\"-------------------------------------------------------------------------- |
| 41 | .SH SYNOPSIS |
| 42 | . |
| 43 | .nf |
| 44 | .B "#include <mLib/sig.h>" |
| 45 | .PP |
| 46 | .B "typedef struct { ...\& } sig;" |
| 47 | .PP |
| 48 | .ta \w'\fBvoid sig_add('u |
| 49 | .BI "void sig_add(sig *" s ", int " n , |
| 50 | .BI " void (*" proc ")(int " n ", void *" p "), void *" p ); |
| 51 | .BI "void sig_remove(sig *" s ); |
| 52 | .BI "void sig_init(sel_state *" s ); |
| 53 | .fi |
| 54 | . |
| 55 | .\"-------------------------------------------------------------------------- |
| 56 | .SH "DESCRIPTION" |
| 57 | . |
| 58 | The |
| 59 | .B sig |
| 60 | subsystem uses the I/O multiplexing capabilities of |
| 61 | .B mLib |
| 62 | (see |
| 63 | .BR sel (3) |
| 64 | for details) to provide a more convenient interface for handling signals |
| 65 | which don't need to be dealt with `right away'. Like the I/O system, |
| 66 | .B sig |
| 67 | doesn't allocate any memory for itself: you have to give it space to |
| 68 | work in. |
| 69 | .PP |
| 70 | The system needs to be initialized before use. To do this, you must |
| 71 | call |
| 72 | .BR sig_init , |
| 73 | passing it the address of an initialized multiplexor object. Signals |
| 74 | handled through this interface will only be delivered when |
| 75 | .BR sel_select (3) |
| 76 | is called on that multiplexor. |
| 77 | .PP |
| 78 | To register interest in a signal, call |
| 79 | .BR sig_add , |
| 80 | passing it the following arguments: |
| 81 | .TP |
| 82 | .BI "sig *" s |
| 83 | A pointer to an (uninitialized) object of type |
| 84 | .BR sig . |
| 85 | This will be used by the system to retain information about this signal |
| 86 | claim. You use the address of this object to remove the handler again |
| 87 | when you've finished. |
| 88 | .TP |
| 89 | .BI "int " n |
| 90 | The number of the signal you want to handle. |
| 91 | .PP |
| 92 | .TP |
| 93 | .BI "void (*" proc ")(int " n ", void *" p ) |
| 94 | A function to call when the signal is detected. The function is passed |
| 95 | the signal number and the pointer |
| 96 | .I p |
| 97 | passed to |
| 98 | .BR sig_add . |
| 99 | .TP |
| 100 | .BI "void *" p |
| 101 | A pointer argument to be passed to |
| 102 | .I func |
| 103 | when the signal is detected. |
| 104 | .PP |
| 105 | Removing a handler is easy. Call |
| 106 | .B sig_remove |
| 107 | with the address of the |
| 108 | .B sig |
| 109 | structure you passed to |
| 110 | .BR sig_add . |
| 111 | . |
| 112 | .SS "Multiple signal handlers" |
| 113 | You may have multiple signal handlers for a signal. All of them are |
| 114 | called in some unspecified order when the signal occurs. |
| 115 | .PP |
| 116 | A signal's disposition is remembered when a handler for it is added and |
| 117 | there are no handlers already registered. When the last handler for a |
| 118 | signal is removed, its disposition is restored to its initial remembered |
| 119 | state. |
| 120 | . |
| 121 | .\"-------------------------------------------------------------------------- |
| 122 | .SH "BUGS AND CAVEATS" |
| 123 | . |
| 124 | The |
| 125 | .B sig |
| 126 | system attempts to set the |
| 127 | .B SA_RESTART |
| 128 | flag on signal handlers it creates that signal occurrences don't |
| 129 | interrupt system calls. This won't be done on systems which don't |
| 130 | define this flag, for obvious reasons. |
| 131 | .PP |
| 132 | The |
| 133 | .B SA_NOCLDSTOP |
| 134 | flag is also set, so that stopped child processes aren't reported by a |
| 135 | signal. This is normally right, but ought to be configurable. |
| 136 | . |
| 137 | .\"-------------------------------------------------------------------------- |
| 138 | .SH "SEE ALSO" |
| 139 | . |
| 140 | .BR signal (2), |
| 141 | .BR sel (3), |
| 142 | .BR mLib (3). |
| 143 | . |
| 144 | .\"-------------------------------------------------------------------------- |
| 145 | .SH "AUTHOR" |
| 146 | . |
| 147 | Mark Wooding, <mdw@distorted.org.uk> |
| 148 | . |
| 149 | .\"----- That's all, folks -------------------------------------------------- |