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

   1 .\" -*-nroff-*-
   2 .TH sel 3 "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
   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 .B "typedef struct { ...\& } sig;"
  13
  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 );
  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
  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,
  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
  45 .BI "sig *" s
  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
  52 .BI "int " n
  53 The number of the signal you want to handle.
  54 .PP
  55 .TP
  56 .BI "void (*" proc ")(int " n ", void *" p )
  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
  63 .BI "void *" p
  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.
  95 .SH "AUTHOR"
  96 Mark Wooding, <mdw@distorted.org.uk>