[mLib] / sel / sig.3

.\" -*-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>"
.PP
.B "typedef struct { ...\& } sig;"
.PP
.ta \w'\fBvoid sig_add('u
.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>
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>"
d056fbdf	11	.PP
4729aa69	12	.B "typedef struct { ...\& } sig;"
d056fbdf	13	.PP
adec5584 MW	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 );
9f8886c7	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
d4704dee	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,
9f8886c7	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
b78d1e6d	45	.BI "sig *" s
9f8886c7	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
b78d1e6d	52	.BI "int " n
9f8886c7	53	The number of the signal you want to handle.
	54	.PP
	55	.TP
b78d1e6d	56	.BI "void (" proc ")(int " n ", void " p )
9f8886c7	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
b78d1e6d	63	.BI "void *" p
9f8886c7	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.
9f8886c7	95	.SH "AUTHOR"
9b5ac6ff	96	Mark Wooding, <mdw@distorted.org.uk>