source: project/wiki/eggref/4/tcp6 @ 28027

Last change on this file since 28027 was 28027, checked in by zbigniew, 6 years ago

wiki/tcp6: update to 0.1.1

File size: 12.6 KB
Line 
1[[tags: manual]]
2
3== tcp6
4
5'''tcp6''' provides facilities for communicating over TCP/IP and
6supports both IPv4 and IPv6.
7
8[[toc:]]
9
10== Overview
11
12This extension provides facilities for communicating over TCP sockets
13with an interface that is backwards-compatible with [[/man/4/Unit
14tcp|Unit tcp]].  It is implemented on top of the
15[[/egg/socket|socket]] egg and consequently supports IPv4 and IPv6,
16non-blocking operations on Windows, and correct error detection
17on Windows.
18
19All errors related to failing network operations will raise a
20condition of kind {{(exn i/o net)}}.  Timeouts raise the error {{(exn
21i/o net timeout)}}.
22
23== Usage
24
25Simply replace {{(use tcp)}} with {{(use tcp6)}}.  The API is the same,
26although it includes a few extensions: {{tcp-bind-v6-only}},
27{{tcp-connect/ai}} and {{tcp-listener-socket}}.
28
29== Servers
30
31<procedure>(tcp-listen TCPPORT [BACKLOG [HOST]])</procedure>
32
33Creates and returns a TCP listener object that listens for connections on {{TCPPORT}}, which
34should be an exact integer. {{BACKLOG}} specifies the number of maximally pending
35connections (and defaults to 10).
36
37If the optional argument {{HOST}} is given and not {{#f}}, then only
38incoming connections for the given host (or IP) are accepted.
39
40When {{HOST}} is {{#f}} (the default), the behavior is
41system-dependent.  It ''should'' listen on all IPv4 and IPv6 addresses
42if possible, or just on IPv4 if IPv6 is disabled.  This is true on OS
43X and Windows.  Unfortunately, certain systems may always prefer to
44listen on IPv4 only (particularly those using recent glibc, like
45Ubuntu).
46
47Special note when {{HOST}} is {{#f}}.  If you have set
48{{(tcp-bind-ipv6-only #t)}}, or if {{tcp-bind-ipv6-only}} is not
49supported by your OS, we ''always'' listen on {{"0.0.0.0"}} to IPv4 only.  This
50is done because users will expect {{(tcp-listen port)}} to listen at
51least on IPv4.  To listen to IPv6 only in this case, explicitly
52specify a {{HOST}} of {{"::"}}.
53
54Long story short, setting {{HOST}} to {{#f}} will more likely than not
55give you an IPv4-only listener.
56
57<procedure>(tcp-listener? X)</procedure>
58
59Returns {{#t}} if {{X}} is a TCP listener object, or {{#f}} otherwise.
60
61<procedure>(tcp-close LISTENER)</procedure>
62
63Reclaims any resources associated with {{LISTENER}}.
64
65<procedure>(tcp-accept LISTENER)</procedure>
66
67Waits until a connection is established on the port on which
68{{LISTENER}} is listening and returns two values: an input- and
69output-port that can be used to communicate with the remote
70process. The current value of {{tcp-accept-timeout}} is used to
71determine the maximal number of milliseconds (if any) to wait
72until a connection is established. When a client connects any
73read- and write-operations on the returned ports will use the
74current values (at the time of the connection) of {{tcp-read-timeout}}
75and {{tcp-write-timeout}}, respectively, to determine the maximal
76number of milliseconds to wait for input/output before a timeout
77error is signalled.
78
79Note: this operation and any I/O on the ports returned will not block
80other running threads.
81
82<procedure>(tcp-accept-ready? LISTENER)</procedure>
83
84Returns {{#t}} if there are any connections pending on {{LISTENER}}, or {{#f}}
85otherwise.
86
87<procedure>(tcp-listener-port LISTENER)</procedure>
88
89Returns the port number assigned to {{LISTENER}}. (If you pass {{0}} to {{tcp-listen}},
90then the system will choose a port-number for you.)
91
92<procedure>(tcp-listener-socket LISTENER)</procedure>
93
94Returns the socket object associated with {{LISTENER}}.  This
95procedure is an addition over [[/man/4/Unit tcp|Unit tcp]].
96
97<procedure>(tcp-listener-fileno LISTENER)</procedure>
98
99Returns the file-descriptor associated with {{LISTENER}}.
100
101=== Clients
102
103<procedure>(tcp-connect HOSTNAME [TCPPORT])</procedure>
104
105Establishes a client-side TCP connection to the machine with the node
106name or IP address {{HOSTNAME}} (a string) at {{TCPPORT}} (an exact
107integer or a service name) and returns two values: an input- and
108output-port for communicating with the remote process.
109
110If the {{TCPPORT}} is omitted, the port is parsed from the
111{{HOSTNAME}} string.  The format expected is {{"HOST:PORT"}}, or
112{{"[HOST]:PORT"}} if {{HOST}} is an IPv6 string.  The {{PORT}} can
113either be a string representation of an integer or a service name
114which is translated to an integer using {{address-information}} from
115[[/egg/socket|socket]].
116
117Address resolution is performed using {{address-information}}, which
118may return multiple addresses for a given hostname, including both
119IPv6 and IPv4 addresses.  {{tcp-connect}} will try each of these in
120turn until one succeeds.  See {{tcp-connect/ai}} for more information.
121For example, connecting to {{"localhost:ssh"}} may connect to
122{{"[::1]:22"}}, {{"[fe80::1%lo0]:22"}}, and {{"127.0.0.1:22"}} in turn,
123until an ssh listener is contacted.
124
125The current value of {{tcp-connect-timeout}} is used to determine the
126maximum number of milliseconds (if any) to wait until the connection
127is established. When the connection takes place any read- and
128write-operations on the returned ports will use the current values (at
129the time of the call to {{tcp-connect}}) of {{tcp-read-timeout}} and
130{{tcp-write-timeout}}, respectively, to determine the maximum number
131of milliseconds to wait for input/output before a timeout error is
132signalled.
133
134Note: any I/O on the ports returned will not block other running threads.
135
136<procedure>(tcp-connect/ai ais)</procedure>
137
138Takes a list of {{addrinfo}} objects, obtained from
139{{address-information}} in the [[/egg/socket|socket egg]], and
140connects to each in turn until one succeeds.  If a timeout occurs
141during connection, or a transient error (connection refused, host
142unreachable) occurs, the next address in the list will be tried.  If
143all addresses fail, the last error encountered is propagated to the
144caller.  If a fatal socket error occurs then we terminate immediately.
145
146{{(tcp-connect host port)}} is equivalent to
147
148 (tcp-connect/ai (address-information host port))
149
150which may include IPv6 and IPv4 addresses.  To connect instead to
151{{localhost:22}} over IPv4 only:
152
153 (tcp-connect/ai (address-information "localhost" 22 family: af/inet))
154
155and to try to connect to the first HTTP mirror that accepts your
156connection:
157
158 (tcp-connect/ai
159  (append (address-information "athena.example.com" 80)
160          (address-information "achilles.example.com" 80)
161          (address-information "aphrodite.example.com" 80)))
162
163Keeping the connect timeout low is probably a good idea in the last
164case.
165
166== Port operations
167
168<procedure>(tcp-addresses PORT)</procedure>
169
170Returns two values for the input- or output-port {{PORT}} (which should be a port returned
171by either {{tcp-accept}} or {{tcp-connect}}): the IP address of the local and the remote
172machine that are connected over the socket associated with {{PORT}}. The returned addresses
173are IPv4 or IPv6 strings.
174
175<procedure>(tcp-port-numbers PORT)</procedure>
176
177Returns two values for the input- or output-port {{PORT}} (which should be a port returned
178by either {{tcp-accept}} or {{tcp-connect}}): the TCP port numbers of the local and the remote
179machine that are connected over the socket associated with {{PORT}}.
180
181<procedure>(tcp-abandon-port PORT)</procedure>
182
183Marks the socket port {{PORT}} as abandoned.  This is mainly useful to
184close down an input or output port without shutting down that side of
185the connection.  See {{socket-abandon-port}} in [[/egg/socket|socket]]
186for more information.
187
188<procedure>(tcp-port->socket PORT)</procedure>
189
190Return the socket object associated with TCP input or output port
191{{PORT}}. 
192
193It is also possible to use {{port->fileno}} from
194[[/man/4/posix|Unit posix]] with TCP ports created by this egg.
195
196=== Parameters
197
198<parameter>tcp-buffer-size</parameter>
199
200Sets the size of the output buffer. By default no output-buffering for
201TCP output is done, but to improve performance by minimizing the
202number of TCP packets, buffering may be turned on by setting this
203parameter to an exact integer greater than zero.  For best
204performance, it should be a power of 2 such as 128, 1024 or 4096.  A
205buffer size of {{#f}} turns buffering off.  The setting of this
206parameter takes effect at the time when the I/O ports for a particular
207socket are created, i.e. when {{tcp-connect}} or {{tcp-accept}} is
208called.
209
210See {{socket-receive-buffer-size}} and {{socket-send-size}} in the
211[[/egg/socket|socket egg]] for additional send and receive tuning that
212can be done with TCP ports.  This parameter is itself equivalent to
213{{socket-send-buffer-size}}.
214
215Note that since output is not immediately written to the associated socket, you
216may need to call {{flush-output}} once you want the output to be transmitted.
217Closing the output port will flush automatically.
218
219<parameter>tcp-read-timeout</parameter>
220
221Determines the timeout for TCP read operations in milliseconds. A timeout of
222{{#f}} disables timeout checking. The default read timeout is 60000, i.e.
2231 minute.
224If timeout occurs while reading, a condition object of kind {{(exn i/o net timeout)}}
225is thrown.
226
227<parameter>tcp-write-timeout</parameter>
228
229Determines the timeout for TCP write operations in milliseconds. A timeout of
230{{#f}} disables timeout checking. The default write timeout is 60000, i.e.
2311 minute.
232If timeout occurs while writing, a condition object of kind {{(exn i/o net timeout)}}
233is thrown.
234
235<parameter>tcp-connect-timeout</parameter>
236
237Determines the timeout for {{tcp-connect}} operations in milliseconds. A timeout of
238{{#f}} disables timeout checking and is the default.
239If timeout occurs while trying to connect, a condition object of kind {{(exn i/o net timeout)}}
240is thrown.
241
242<parameter>tcp-accept-timeout</parameter>
243
244Determines the timeout for {{tcp-accept}} operations in milliseconds. A timeout of
245{{#f}} disables timeout checking and is the default.
246If timeout occurs while waiting for connections, a condition object of kind {{(exn i/o net timeout)}}
247is thrown.
248
249<parameter>tcp-bind-ipv6-only</parameter>
250
251When {{#f}}, the default, IPv6 listening sockets will accept IPv6 or
252IPv4 connections when possible.  This is only relevant when listening on the
253unspecified address "::".  When {{#t}}, IPv6 listeners will not accept
254IPv4 connections.
255
256This option is ignored when unsupported, such as on Windows 2000 and
257XP, whose IPv4 and IPv6 stacks are separate.
258
259== Example
260
261A very simple example follows. Say we have the two files {{client.scm}}
262and {{server.scm}}:
263
264<enscript highlight=scheme>
265 ; client.scm
266 (use tcp6)
267 (define-values (i o) (tcp-connect "localhost" 4242))
268 (write-line "Good Bye!" o)
269 (print (read-line i))
270</enscript>
271
272<enscript highlight=scheme>
273 ; server.scm
274 (use tcp6)
275 (define l (tcp-listen 4242))
276 (define-values (i o) (tcp-accept l))
277 (write-line "Hello!" o)
278 (print (read-line i))
279 (close-input-port i)
280 (close-output-port o)
281</enscript>
282
283 % csc server.scm
284 % csc client.scm
285 % ./server &
286 % ./client
287 Good Bye!
288 Hello!
289
290== About this egg
291
292=== Author
293
294[[http://3e8.org|Jim Ursetto]]
295
296This code has been completely rewritten from the core TCP unit, but
297some of the original code was moved into the socket egg, and the API
298is largely unchanged.
299
300=== Version history
301
302; 0.1.1 : Bugfix for #963: tcp-accept now propagates read/write timeout to socket egg.
303; 0.1 : Initial release.
304
305=== License
306
307 Copyright (c) 2011, Jim Ursetto
308 Copyright (c) 2008-2011, The Chicken Team
309 Copyright (c) 2000-2007, Felix L. Winkelmann
310 All rights reserved.
311 
312 Redistribution and use in source and binary forms, with or without
313 modification, are permitted provided that the following conditions
314 are met:
315 
316 - Redistributions of source code must retain the above copyright
317 notice, this list of conditions and the following disclaimer.
318 - Redistributions in binary form must reproduce the above copyright
319 notice, this list of conditions and the following disclaimer in
320 the documentation and/or other materials provided with the
321 distribution.
322 - Neither the name of the author nor the names of its contributors
323 may be used to endorse or promote products derived from this
324 software without specific prior written permission.
325 
326 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
327 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
328 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
329 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
330 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
331 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
332 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
333 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
334 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
335 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
336 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
337 OF THE POSSIBILITY OF SUCH DAMAGE.
338
Note: See TracBrowser for help on using the repository browser.