2 .TH selpk 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
4 selpk \- packet-buffering input selector
12 .B "#include <mLib/selpk.h>"
14 .B "typedef struct { ...\& } selpk;"
16 .BI "void selpk_enable(selpk *" pk );
17 .BI "void selpk_disable(selpk *" pk );
18 .BI "void selpk_want(selpk *" pk ", size_t " sz );
19 .ta \w'\fBvoid selpk_init('u
20 .BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
21 .BI " pkbuf_func *" func ", void *" p );
22 .BI "void selpk_destroy(selpk *" b );
27 subsystem is a selector which integrates with the
29 system for I/O multiplexing. It reads packets from a file descriptor
30 and passes them to a caller-defined function. It uses the packet buffer
33 to do its work: you should read about it in order to understand exactly
34 how the packet buffer decides how much data is in each packet and the
35 exact rules about what your packet handling function should and
38 The data for a packet 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 "pkbuf_func *" func
62 function. It is given a pointer to each packet read from the file (or
63 null to indicate end-of-file) and an arbitrary pointer (the
72 A pointer argument passed to
74 for each packet 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 packets read from the file to be
82 passed to your handling function. This function can at any time call
84 to stop itself from being called any more. The selector is then
85 disengaged from the I/O multiplexor and won't do anything until
89 may well immediately start emitting complete packets of text which were
90 queued up from the last I/O operation: it doesn't necessarily wait for
95 The size of packets read by the buffer is set by calling
99 for more details about how packet buffering works.
101 When it's finished with, a packet selector must be destroyed by calling
109 Mark Wooding, <mdw@distorted.org.uk>