[mLib] / man / sig.3

.\" -*-nroff-*-
.TH sel 3 "23 July 1999" mLib
.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
.I 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
.I n
The number of the signal you want to handle.
.PP
.TP
.I proc
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
.I 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.
.PP
The system uses writes to a nonblocking pipe to integrate with the I/O
multiplexing system.  It's possible (though very unlikely) that signals
get lost because the pipe is full.
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>
Commit	Line	Data
9f8886c7	1	.\" --nroff--
	2	.TH sel 3 "23 July 1999" mLib
	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	.BI "void sig_add(sig *" s ", int " n ,
	13	.BI " void (" proc ")(int " n ", void " p "), void *" p );
	14	.BI "void sig_remove(sig *" s );
	15	.BI "void sig_init(sel_state *" s );
	16	.fi
	17	.SH "DESCRIPTION"
	18	The
	19	.B sig
	20	subsystem uses the I/O multiplexing capabilities of
	21	.B mLib
	22	(see
	23	.BR sel (3) for details)
	24	to provide a more convenient interface for handling signals which don't
	25	need to be dealt with `right away'. Like the I/O system,
	26	.B sig
	27	doesn't allocate any memory for itself: you have to give it space to
	28	work in.
	29	.PP
	30	The system needs to be initialized before use. To do this, you must
	31	call
	32	.BR sig_init ,
	33	passing it the address of an initialized multiplexor object. Signals
	34	handled through this interface will only be delivered when
	35	.BR sel_select (3)
	36	is called on that multiplexor.
	37	.PP
	38	To register interest in a signal, call
	39	.BR sig_add ,
	40	passing it the following arguments:
	41	.TP
	42	.I s
	43	A pointer to an (uninitialized) object of type
	44	.BR sig .
	45	This will be used by the system to retain information about this signal
	46	claim. You use the address of this object to remove the handler again
	47	when you've finished.
	48	.TP
	49	.I n
	50	The number of the signal you want to handle.
	51	.PP
	52	.TP
	53	.I proc
	54	A function to call when the signal is detected. The function is passed
	55	the signal number and the pointer
	56	.I p
	57	passed to
	58	.BR sig_add .
	59	.TP
	60	.I p
	61	A pointer argument to be passed to
	62	.I func
	63	when the signal is detected.
	64	.PP
65	Removing a handler is easy. Call
66	.B sig_remove
67	with the address of the
68	.B sig
69	structure you passed to
70	.BR sig_add .
71	.SS "Multiple signal handlers"
72	You may have multiple signal handlers for a signal. All of them are
73	called in some unspecified order when the signal occurs.
74	.PP
75	A signal's disposition is remembered when a handler for it is added and
76	there are no handlers already registered. When the last handler for a
77	signal is removed, its disposition is restored to its initial remembered
78	state.
79	.SH "BUGS AND CAVEATS"
80	The
81	.B sig
82	system attempts to set the
83	.B SA_RESTART
84	flag on signal handlers it creates that signal occurrences don't
85	interrupt system calls. This won't be done on systems which don't
86	define this flag, for obvious reasons.
87	.PP
88	The
89	.B SA_NOCLDSTOP
90	flag is also set, so that stopped child processes aren't reported by a
91	signal. This is normally right, but ought to be configurable.
92	.PP
93	The system uses writes to a nonblocking pipe to integrate with the I/O
94	multiplexing system. It's possible (though very unlikely) that signals
95	get lost because the pipe is full.
96	.SH "AUTHOR"
97	Mark Wooding, <mdw@nsict.org>