Infrastructure: Split the files into subdirectories.

[mLib] / sel / sig.3

diff --git a/sel/sig.3 b/sel/sig.3
new file mode 100644 (file)
index 0000000..a176e12
--- /dev/null
+++ b/sel/sig.3
@@ -0,0 +1,93 @@
+.\" -*-nroff-*-
+.TH sel 3 "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.SH NAME
+sig \- more controlled signal handling
+.\" @sig_init
+.\" @sig_add
+.\" @sig_remove
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/sig.h>"
+
+.BI "void sig_add(sig *" s ", int " n ,
+.BI "             void (*" proc ")(int " n ", void *" p "), void *" p );
+.BI "void sig_remove(sig *" s );
+.BI "void sig_init(sel_state *" s );
+.fi
+.SH "DESCRIPTION"
+The
+.B sig
+subsystem uses the I/O multiplexing capabilities of
+.B mLib
+(see
+.BR sel (3)
+for details) to provide a more convenient interface for handling signals
+which don't need to be dealt with `right away'.  Like the I/O system,
+.B sig
+doesn't allocate any memory for itself: you have to give it space to
+work in.
+.PP
+The system needs to be initialized before use.  To do this, you must
+call
+.BR sig_init ,
+passing it the address of an initialized multiplexor object.  Signals
+handled through this interface will only be delivered when
+.BR sel_select (3)
+is called on that multiplexor.
+.PP
+To register interest in a signal, call
+.BR sig_add ,
+passing it the following arguments:
+.TP
+.BI "sig *" s
+A pointer to an (uninitialized) object of type
+.BR sig .
+This will be used by the system to retain information about this signal
+claim.  You use the address of this object to remove the handler again
+when you've finished.
+.TP
+.BI "int " n
+The number of the signal you want to handle.
+.PP
+.TP
+.BI "void (*" proc ")(int " n ", void *" p )
+A function to call when the signal is detected.  The function is passed
+the signal number and the pointer
+.I p
+passed to
+.BR sig_add .
+.TP
+.BI "void *" p
+A pointer argument to be passed to
+.I func
+when the signal is detected.
+.PP
+Removing a handler is easy.  Call
+.B sig_remove
+with the address of the
+.B sig
+structure you passed to
+.BR sig_add .
+.SS "Multiple signal handlers"
+You may have multiple signal handlers for a signal.  All of them are
+called in some unspecified order when the signal occurs.
+.PP
+A signal's disposition is remembered when a handler for it is added and
+there are no handlers already registered.  When the last handler for a
+signal is removed, its disposition is restored to its initial remembered
+state.
+.SH "BUGS AND CAVEATS"
+The
+.B sig
+system attempts to set the
+.B SA_RESTART
+flag on signal handlers it creates that signal occurrences don't
+interrupt system calls.  This won't be done on systems which don't
+define this flag, for obvious reasons.
+.PP
+The
+.B SA_NOCLDSTOP
+flag is also set, so that stopped child processes aren't reported by a
+signal.  This is normally right, but ought to be configurable.
+.SH "AUTHOR"
+Mark Wooding, <mdw@distorted.org.uk>