chiark - git - mdw - mLib/blob - sel/sig.3.in

   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 --------------------------------------------------