2 .TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
4 selbuf \- line-buffering input selector
12 .B "#include <mLib/selbuf.h>"
14 .B "typedef struct { ...\& } selbuf;"
16 .BI "void selbuf_enable(selbuf *" b );
17 .BI "void selbuf_disable(selbuf *" b );
18 .BI "void selbuf_setsize(selbuf *" b ", size_t " sz );
19 .ta \w'\fBvoid selbuf_init('u
20 .BI "void selbuf_init(selbuf *" b ", sel_state *" s ", int " fd ,
21 .BI " lbuf_func *" func ", void *" p );
22 .BI "void selbuf_destroy(selbuf *" b );
27 subsystem is a selector which integrates with the
29 system for I/O multiplexing. It reads entire text lines from a file
30 descriptor and passes them to a caller-defined function. It uses the
31 line buffer described in
33 to do its work: you should read about it in order to understand exactly
34 what gets considered to be a line of text and what doesn't, and the
35 exact rules about what your line handling function should and shouldn't
38 The data for a line selector is stored in an object of type
40 This object must be allocated by the caller, and initialized using the
42 function. This requires a fair few arguments:
50 Pointer to a multiplexor object (type
52 to which this selector should be attached. See
54 for more details about multiplexors, and how this whole system works.
57 The file descriptor of the stream the selector should read from.
59 .BI "lbuf_func *" func
62 function. It is passed a pointer to each line read from the file (or
63 null to indicate end-of-file), the length of the line, and an arbitrary
68 described below). For full details, see
72 A pointer argument passed to
74 for each line read from the file. Apart from this, the pointer is not
79 selector is immediately active. Subsequent calls to
81 on the same multiplexor will cause any complete lines read from the file
82 to be passed to your handling function. This function can at any time
85 to stop itself from being called any more. The selector is then
86 disengaged from the I/O multiplexor and won't do anything until
90 may well immediately start emitting complete lines of text which were
91 queued up from the last I/O operation: it doesn't necessarily wait for
96 The line buffer has a finite amount of memory for reading strings. The
97 size of this buffer is set by calling
99 with the requested size. The default buffer size is 256 bytes.
101 When it's finished with, a line buffer selector must be destroyed by
109 Mark Wooding, <mdw@distorted.org.uk>