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