Commit | Line | Data |
---|---|---|
1e7e4330 | 1 | .\" -*-nroff-*- |
c4ccbbf9 MW |
2 | .\" |
3 | .\" Manual for event-driven packet splitting | |
4 | .\" | |
5 | .\" (c) 2000--2003, 2005, 2009, 2023, 2024 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of the mLib utilities library. | |
11 | .\" | |
12 | .\" mLib is free software: you can redistribute it and/or modify it under | |
13 | .\" the terms of the GNU Library General Public License as published by | |
14 | .\" the Free Software Foundation; either version 2 of the License, or (at | |
15 | .\" your option) any later version. | |
16 | .\" | |
17 | .\" mLib is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public | |
20 | .\" License for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU Library General Public | |
23 | .\" License along with mLib. If not, write to the Free Software | |
24 | .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, | |
25 | .\" USA. | |
26 | . | |
27 | .\"-------------------------------------------------------------------------- | |
28 | .so ../defs.man \" @@@PRE@@@ | |
29 | . | |
30 | .\"-------------------------------------------------------------------------- | |
31 | .TH selpk 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library" | |
1e7e4330 | 32 | .\" @selpk_enable |
33 | .\" @selpk_disable | |
34 | .\" @selpk_want | |
35 | .\" @selpk_init | |
36 | .\" @selpk_destroy | |
c4ccbbf9 MW |
37 | . |
38 | .\"-------------------------------------------------------------------------- | |
39 | .SH NAME | |
40 | selpk \- packet-buffering input selector | |
41 | . | |
1e7e4330 | 42 | .SH SYNOPSIS |
43 | .nf | |
44 | .B "#include <mLib/selpk.h>" | |
d056fbdf | 45 | .PP |
4729aa69 | 46 | .B "typedef struct { ...\& } selpk;" |
d056fbdf | 47 | .PP |
1e7e4330 | 48 | .BI "void selpk_enable(selpk *" pk ); |
49 | .BI "void selpk_disable(selpk *" pk ); | |
50 | .BI "void selpk_want(selpk *" pk ", size_t " sz ); | |
adec5584 MW |
51 | .ta \w'\fBvoid selpk_init('u |
52 | .BI "void selpk_init(selpk *" pk ", sel_state *" s ", int " fd , | |
53 | .BI " pkbuf_func *" func ", void *" p ); | |
1e7e4330 | 54 | .BI "void selpk_destroy(selpk *" b ); |
55 | .fi | |
c4ccbbf9 MW |
56 | . |
57 | .\"-------------------------------------------------------------------------- | |
1e7e4330 | 58 | .SH DESCRIPTION |
c4ccbbf9 | 59 | . |
1e7e4330 | 60 | The |
61 | .B selpk | |
62 | subsystem is a selector which integrates with the | |
63 | .BR sel (3) | |
64 | system for I/O multiplexing. It reads packets from a file descriptor | |
65 | and passes them to a caller-defined function. It uses the packet buffer | |
66 | described in | |
67 | .BR pkbuf (3) | |
68 | to do its work: you should read about it in order to understand exactly | |
69 | how the packet buffer decides how much data is in each packet and the | |
70 | exact rules about what your packet handling function should and | |
71 | shouldn't do. | |
72 | .PP | |
73 | The data for a packet selector is stored in an object of type | |
74 | .BR selpk . | |
75 | This object must be allocated by the caller, and initialized using the | |
76 | .B selpk_init | |
77 | function. This requires a fair few arguments: | |
78 | .TP | |
79 | .BI "selpk *" pk | |
80 | Pointer to the | |
81 | .B selpk | |
82 | object to initialize. | |
83 | .TP | |
84 | .BI "sel_state *" s | |
85 | Pointer to a multiplexor object (type | |
86 | .BR sel_state ) | |
87 | to which this selector should be attached. See | |
88 | .BR sel (3) | |
89 | for more details about multiplexors, and how this whole system works. | |
90 | .TP | |
91 | .BI "int " fd | |
92 | The file descriptor of the stream the selector should read from. | |
93 | .TP | |
0daaeb18 | 94 | .BI "pkbuf_func *" func |
1e7e4330 | 95 | The |
96 | .I "packet handler" | |
0daaeb18 | 97 | function. It is given a pointer to each packet read from the file (or |
1e7e4330 | 98 | null to indicate end-of-file) and an arbitrary pointer (the |
99 | .I p | |
100 | argument to | |
101 | .B selpk_init | |
0daaeb18 | 102 | described below). See |
103 | .BR pkbuf (3) | |
104 | for full details. | |
1e7e4330 | 105 | .TP |
106 | .BI "void *" p | |
107 | A pointer argument passed to | |
108 | .I func | |
109 | for each packet read from the file. Apart from this, the pointer is not | |
110 | used at all. | |
111 | .PP | |
112 | The | |
113 | .B selpk | |
114 | selector is immediately active. Subsequent calls to | |
115 | .B sel_select | |
116 | on the same multiplexor will cause any packets read from the file to be | |
117 | passed to your handling function. This function can at any time call | |
118 | .B selpk_disable | |
119 | to stop itself from being called any more. The selector is then | |
120 | disengaged from the I/O multiplexor and won't do anything until | |
121 | .B selpk_enable | |
122 | is called. Note that | |
123 | .B selpk_enable | |
124 | may well immediately start emitting complete packets of text which were | |
125 | queued up from the last I/O operation: it doesn't necessarily wait for | |
126 | the next | |
127 | .B sel_select | |
128 | call. | |
129 | .PP | |
130 | The size of packets read by the buffer is set by calling | |
131 | .BR selpk_want . | |
132 | See | |
133 | .BR pkbuf (3) | |
134 | for more details about how packet buffering works. | |
135 | .PP | |
136 | When it's finished with, a packet selector must be destroyed by calling | |
137 | .BR selpk_destroy . | |
c4ccbbf9 MW |
138 | . |
139 | .\"-------------------------------------------------------------------------- | |
1e7e4330 | 140 | .SH "SEE ALSO" |
c4ccbbf9 | 141 | . |
1e7e4330 | 142 | .BR pkbuf (3), |
143 | .BR sel (3), | |
144 | .BR selbuf (3), | |
145 | .BR mLib (3). | |
c4ccbbf9 MW |
146 | . |
147 | .\"-------------------------------------------------------------------------- | |
1e7e4330 | 148 | .SH AUTHOR |
c4ccbbf9 | 149 | . |
9b5ac6ff | 150 | Mark Wooding, <mdw@distorted.org.uk> |
c4ccbbf9 MW |
151 | . |
152 | .\"----- That's all, folks -------------------------------------------------- |