chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / sel / selpk.3
1e7e4330 1.\" -*-nroff-*-
fbf20b5b 2.TH selpk 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
1e7e4330 3.SH NAME
4selpk \- packet-buffering input selector
5.\" @selpk_enable
6.\" @selpk_disable
7.\" @selpk_want
8.\" @selpk_init
9.\" @selpk_destroy
12.B "#include <mLib/selpk.h>"
14.BI "void selpk_enable(selpk *" pk );
15.BI "void selpk_disable(selpk *" pk );
16.BI "void selpk_want(selpk *" pk ", size_t " sz );
0daaeb18 17.BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd ,
528c8b4d 18.BI " pkbuf_func *" func ", void *" p );
1e7e4330 19.BI "void selpk_destroy(selpk *" b );
23.B selpk
24subsystem is a selector which integrates with the
25.BR sel (3)
26system for I/O multiplexing. It reads packets from a file descriptor
27and passes them to a caller-defined function. It uses the packet buffer
28described in
29.BR pkbuf (3)
30to do its work: you should read about it in order to understand exactly
31how the packet buffer decides how much data is in each packet and the
32exact rules about what your packet handling function should and
33shouldn't do.
35The data for a packet selector is stored in an object of type
36.BR selpk .
37This object must be allocated by the caller, and initialized using the
38.B selpk_init
39function. This requires a fair few arguments:
41.BI "selpk *" pk
42Pointer to the
43.B selpk
44object to initialize.
46.BI "sel_state *" s
47Pointer to a multiplexor object (type
48.BR sel_state )
49to which this selector should be attached. See
50.BR sel (3)
51for more details about multiplexors, and how this whole system works.
53.BI "int " fd
54The file descriptor of the stream the selector should read from.
0daaeb18 56.BI "pkbuf_func *" func
1e7e4330 57The
58.I "packet handler"
0daaeb18 59function. It is given a pointer to each packet read from the file (or
1e7e4330 60null to indicate end-of-file) and an arbitrary pointer (the
61.I p
62argument to
63.B selpk_init
0daaeb18 64described below). See
65.BR pkbuf (3)
66for full details.
1e7e4330 67.TP
68.BI "void *" p
69A pointer argument passed to
70.I func
71for each packet read from the file. Apart from this, the pointer is not
72used at all.
75.B selpk
76selector is immediately active. Subsequent calls to
77.B sel_select
78on the same multiplexor will cause any packets read from the file to be
79passed to your handling function. This function can at any time call
80.B selpk_disable
81to stop itself from being called any more. The selector is then
82disengaged from the I/O multiplexor and won't do anything until
83.B selpk_enable
84is called. Note that
85.B selpk_enable
86may well immediately start emitting complete packets of text which were
87queued up from the last I/O operation: it doesn't necessarily wait for
88the next
89.B sel_select
92The size of packets read by the buffer is set by calling
93.BR selpk_want .
95.BR pkbuf (3)
96for more details about how packet buffering works.
98When it's finished with, a packet selector must be destroyed by calling
99.BR selpk_destroy .
101.BR pkbuf (3),
102.BR sel (3),
103.BR selbuf (3),
104.BR mLib (3).
9b5ac6ff 106Mark Wooding, <>