Commit | Line | Data |
---|---|---|
1e7e4330 | 1 | .\" -*-nroff-*- |
fbf20b5b | 2 | .TH selpk 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library" |
1e7e4330 | 3 | .SH NAME |
4 | selpk \- packet-buffering input selector | |
5 | .\" @selpk_enable | |
6 | .\" @selpk_disable | |
7 | .\" @selpk_want | |
8 | .\" @selpk_init | |
9 | .\" @selpk_destroy | |
10 | .SH SYNOPSIS | |
11 | .nf | |
12 | .B "#include <mLib/selpk.h>" | |
d056fbdf | 13 | .PP |
4729aa69 | 14 | .B "typedef struct { ...\& } selpk;" |
d056fbdf | 15 | .PP |
1e7e4330 | 16 | .BI "void selpk_enable(selpk *" pk ); |
17 | .BI "void selpk_disable(selpk *" pk ); | |
18 | .BI "void selpk_want(selpk *" pk ", size_t " sz ); | |
adec5584 MW |
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 ); | |
1e7e4330 | 22 | .BI "void selpk_destroy(selpk *" b ); |
23 | .fi | |
24 | .SH DESCRIPTION | |
25 | The | |
26 | .B selpk | |
27 | subsystem is a selector which integrates with the | |
28 | .BR sel (3) | |
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 | |
31 | described in | |
32 | .BR pkbuf (3) | |
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 | |
36 | shouldn't do. | |
37 | .PP | |
38 | The data for a packet selector is stored in an object of type | |
39 | .BR selpk . | |
40 | This object must be allocated by the caller, and initialized using the | |
41 | .B selpk_init | |
42 | function. This requires a fair few arguments: | |
43 | .TP | |
44 | .BI "selpk *" pk | |
45 | Pointer to the | |
46 | .B selpk | |
47 | object to initialize. | |
48 | .TP | |
49 | .BI "sel_state *" s | |
50 | Pointer to a multiplexor object (type | |
51 | .BR sel_state ) | |
52 | to which this selector should be attached. See | |
53 | .BR sel (3) | |
54 | for more details about multiplexors, and how this whole system works. | |
55 | .TP | |
56 | .BI "int " fd | |
57 | The file descriptor of the stream the selector should read from. | |
58 | .TP | |
0daaeb18 | 59 | .BI "pkbuf_func *" func |
1e7e4330 | 60 | The |
61 | .I "packet handler" | |
0daaeb18 | 62 | function. It is given a pointer to each packet read from the file (or |
1e7e4330 | 63 | null to indicate end-of-file) and an arbitrary pointer (the |
64 | .I p | |
65 | argument to | |
66 | .B selpk_init | |
0daaeb18 | 67 | described below). See |
68 | .BR pkbuf (3) | |
69 | for full details. | |
1e7e4330 | 70 | .TP |
71 | .BI "void *" p | |
72 | A pointer argument passed to | |
73 | .I func | |
74 | for each packet read from the file. Apart from this, the pointer is not | |
75 | used at all. | |
76 | .PP | |
77 | The | |
78 | .B selpk | |
79 | selector is immediately active. Subsequent calls to | |
80 | .B sel_select | |
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 | |
83 | .B selpk_disable | |
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 | |
86 | .B selpk_enable | |
87 | is called. Note that | |
88 | .B selpk_enable | |
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 | |
91 | the next | |
92 | .B sel_select | |
93 | call. | |
94 | .PP | |
95 | The size of packets read by the buffer is set by calling | |
96 | .BR selpk_want . | |
97 | See | |
98 | .BR pkbuf (3) | |
99 | for more details about how packet buffering works. | |
100 | .PP | |
101 | When it's finished with, a packet selector must be destroyed by calling | |
102 | .BR selpk_destroy . | |
103 | .SH "SEE ALSO" | |
104 | .BR pkbuf (3), | |
105 | .BR sel (3), | |
106 | .BR selbuf (3), | |
107 | .BR mLib (3). | |
108 | .SH AUTHOR | |
9b5ac6ff | 109 | Mark Wooding, <mdw@distorted.org.uk> |