chiark - git - mdw - mLib/blame_incremental

... / ...

Commit	Line	Data
	1	.\" --nroff--
	2	.TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
	3	.SH NAME
	4	selbuf \- line-buffering input selector
	5	.\" @selbuf_enable
	6	.\" @selbuf_disable
	7	.\" @selbuf_setsize
	8	.\" @selbuf_init
	9	.\" @selbuf_destroy
	10	.SH SYNOPSIS
	11	.nf
	12	.B "#include <mLib/selbuf.h>"
	13
	14	.BI "void selbuf_enable(selbuf *" b );
	15	.BI "void selbuf_disable(selbuf *" b );
	16	.BI "void selbuf_setsize(selbuf *" b ", size_t " sz );
	17	.BI "void selbuf_init(selbuf " b ", sel_state " s ", int " fd ,
	18	.BI " lbuf_func " func ", void " p );
	19	.BI "void selbuf_destroy(selbuf *" b );
	20	.fi
	21	.SH DESCRIPTION
	22	The
	23	.B selbuf
	24	subsystem is a selector which integrates with the
	25	.BR sel (3)
	26	system for I/O multiplexing. It reads entire text lines from a file
	27	descriptor and passes them to a caller-defined function. It uses the
	28	line buffer described in
	29	.BR lbuf (3)
	30	to do its work: you should read about it in order to understand exactly
	31	what gets considered to be a line of text and what doesn't, and the
	32	exact rules about what your line handling function should and shouldn't
	33	do.
	34	.PP
	35	The data for a line selector is stored in an object of type
	36	.BR selbuf .
	37	This object must be allocated by the caller, and initialized using the
	38	.B selbuf_init
	39	function. This requires a fair few arguments:
	40	.TP
	41	.BI "selbuf *" b
	42	Pointer to the
	43	.B selbuf
	44	object to initialize.
	45	.TP
	46	.BI "sel_state *" s
	47	Pointer to a multiplexor object (type
	48	.BR sel_state )
	49	to which this selector should be attached. See
	50	.BR sel (3)
	51	for more details about multiplexors, and how this whole system works.
	52	.TP
	53	.BI "int " fd
	54	The file descriptor of the stream the selector should read from.
	55	.TP
	56	.BI "lbuf_func *" func
	57	The
	58	.I "line handler"
	59	function. It is passed a pointer to each line read from the file (or
	60	null to indicate end-of-file), the length of the line, and an arbitrary
	61	pointer (the
	62	.I p
	63	argument to
	64	.B selbuf_init
	65	described below). For full details, see
	66	.BR lbuf (3).
	67	.TP
	68	.BI "void *" p
	69	A pointer argument passed to
	70	.I func
	71	for each line read from the file. Apart from this, the pointer is not
	72	used at all.
	73	.PP
	74	The
	75	.B selbuf
	76	selector is immediately active. Subsequent calls to
	77	.B sel_select
	78	on the same multiplexor will cause any complete lines read from the file
	79	to be passed to your handling function. This function can at any time
	80	call
	81	.B selbuf_disable
	82	to stop itself from being called any more. The selector is then
	83	disengaged from the I/O multiplexor and won't do anything until
	84	.B selbuf_enable
	85	is called. Note that
	86	.B selbuf_enable
	87	may well immediately start emitting complete lines of text which were
	88	queued up from the last I/O operation: it doesn't necessarily wait for
	89	the next
	90	.B sel_select
	91	call.
	92	.PP
	93	The line buffer has a finite amount of memory for reading strings. The
	94	size of this buffer is set by calling
	95	.B selbuf_setsize
	96	with the requested size. The default buffer size is 256 bytes.
	97	.PP
	98	When it's finished with, a line buffer selector must be destroyed by
	99	calling
	100	.BR selbuf_destroy .
	101	.SH "SEE ALSO"
	102	.BR lbuf (3),
	103	.BR sel (3),
	104	.BR mLib (3).
	105	.SH AUTHOR
	106	Mark Wooding, <mdw@distorted.org.uk>