source: project/wiki/eggref/4/udp6 @ 37084

Last change on this file since 37084 was 37084, checked in by Jim Ursetto, 7 months ago

Update Chicken 4 docs for zbigniew eggs

These eggs were ported to Chicken 5 and still support
Chicken 4; docs remain synchronized.

atom chickadee chicken-doc chicken-doc-admin doctype
feature-test socket sql-de-lite tcp6 udp6

File size: 8.7 KB
Line 
1[[tags: egg]]
2
3== udp6
4
5'''udp6''' is an interface to User Datagram Protocol sockets
6over IPv4 and IPv6.
7
8[[toc:]]
9
10== Overview
11
12This is a superset of the functionality of the [[/egg/udp|udp]]
13extension, primarily adding IPv6 support while maintaining a
14backwards-compatible API.  It is implemented on top of the
15[[/egg/socket|socket]] egg,
16
17== Interface
18
19<procedure>(udp-open-socket [family])</procedure>
20<procedure>(udp-open-socket* [family])</procedure>
21
22Returns a new UDP socket object, which is simply a datagram {{socket}}
23object created by the [[/egg/socket|socket]] egg.
24
25The optional argument ''family'' can be {{'inet}} for IPv4 or
26{{'inet6}} for IPv6; the default is {{'inet}}.
27
28(Note: The starred version is provided for API compatibility; it is exactly
29the same as the unstarred version, as all sockets in the socket egg
30are nonblocking at the OS level.)
31
32<procedure>(udp-bind! SOCKET HOST PORT)</procedure>
33
34Binds a UDP socket to an address and port as specified by {{HOST}} and
35{{PORT}}.  {{HOST}} may be a string consisting of an IP address or
36hostname, or {{#f}}, in which case the unspecified address is used.  If
37{{PORT}} is 0, a port will be allocated by the system automatically.
38
39To use IPv6, create a UDP socket with family {{'inet6}}.  If the socket
40is in the IPv4 address family, as is the default, binding to an IPv6 address
41will raise an exception.  Example:
42
43 (define s (udp-open-socket 'inet6))
44 (udp-bind! s "::" 1337)
45
46Binding to the unspecified IPv6 address "::" may, depending on your OS, also
47allow connections via IPv4.  See {{socket-bind}} in the [[/egg/socket|socket]] egg
48for an example of disabling this behavior.
49
50<procedure>(udp-connect! SOCKET HOST PORT)</procedure>
51
52Connect a socket.  In the case of UDP this does nothing more than
53associate a peer address with the socket in the kernel for use with
54later calls to {{send(2)}}.  UDP is a connectionless protocol.
55
56<procedure>(udp-send SOCKET STRING)</procedure>
57
58Send the bytes in {{STRING}} through {{SOCKET}} to its peer, as specified with a previous call to {{udp-connect!}}.  If the socket is not connected, the system will return an error.
59
60<procedure>(udp-sendto SOCKET HOST PORT STRING)</procedure>
61
62Send the bytes in {{STRING}} through {{SOCKET}} to {{PORT}} on {{HOST}}.
63
64<procedure>(udp-recv SOCKET LENGTH)</procedure>
65
66Receive a packet of ''up to'' {{LENGTH}} bytes, blocking the current thread until data is available.
67
68Returns two values: the number of bytes received and a string containing the message received.
69
70<procedure>(udp-recvfrom SOCKET LENGTH)</procedure>
71
72Same as {{udp-recv}} except that two additional values are returned: the host string and port number from which the packet was received.
73
74<procedure>(udp-close-socket SOCKET)</procedure>
75
76Close a socket.
77
78<procedure>(udp-socket? THING)</procedure>
79
80Test whether {{THING}} is a UDP socket.
81
82<procedure>(udp-bound? SOCKET)</procedure>
83
84Test whether a UDP socket is bound to a local address and port.
85
86<procedure>(udp-connected? SOCKET)</procedure>
87
88Test whether a peer address and port has been associated with a UDP socket with a call to {{udp-connect!}}.
89
90<procedure>(udp-bound-port SOCKET)</procedure>
91
92Returns the port to which the socket is bound.
93
94== UDP ports
95
96Input and output Scheme ports can be created from a connected UDP
97socket using {{socket-i/o-ports}} from the [[/egg/socket|socket]] egg.
98An example will be provided in the future.
99
100== Example
101
102=== Daytime client
103
104Connect to the daytime service on localhost:13, and echo back the
105current time.  You must specify whether to connect over IPv4 or IPv6.
106
107<enscript highlight="scheme">
108;; daytime-client.scm
109(use udp6)
110(define port 13)
111(define family 'inet)
112(define s (udp-open-socket family))
113(udp-connect! s "localhost" port)  ; daytime service
114(udp-send s "\n")
115(receive (n data host port) (udp-recvfrom s 64)
116  (print n " bytes from " host ":" port ": " data))
117(udp-close-socket s)
118 
119;; If family is 'inet, prints:
120;;  26 bytes from 127.0.0.1:13: Wed Dec 24 11:53:14 2003
121;; If family is 'inet6, prints:
122;;  26 bytes from ::1:13: Wed Dec 24 11:53:14 2003
123</enscript>
124
125If you don't have a daytime service running---and you probably don't---simulate it with netcat as in:
126
127 # this will work for one read
128 $ date | nc -u -l -6 1313
129
130and, setting {{port}} to 1313 in the script, we get:
131
132 29 bytes from ::1:1313: Tue Feb 17 23:05:10 CST 2015
133
134Alternatively, see [[#Daytime server]] for an implementation using udp6.
135
136==== Daytime client using socket
137
138This example can also be written directly with the [[/egg/socket|socket]] egg:
139
140<enscript highlight="scheme">
141(use socket)
142(define s (socket-connect/ai
143           (address-information "localhost" 13 type: sock/dgram)))
144(socket-send s "\n")
145(receive (data addr) (socket-receive-from s 64)
146  (print (string-length data) " bytes from "
147         (sockaddr->string addr) ": " data))
148(socket-close s)
149
150;; Prints one of the following:
151;; 26 bytes from 127.0.0.1:13: Sat Feb 12 03:53:46 CST 2011
152;; 26 bytes from [::1]:13: Sat Feb 12 03:53:46 CST 2011
153</enscript>
154
155In the latter case, we do not need to specify the address family; {{address-information}} returns
156all IPv4 and IPv6 addresses associated with "localhost", and {{socket-connect/ai}} tries each in turn.
157The udp6 egg does not currently expose this shortcut.
158
159=== Cat server
160
161Listen on both IPv6 and IPv4 (on most operating systems), port 1337, and
162echo messages to stdout.
163
164<enscript highlight="scheme">
165(use udp6)
166(define s (udp-open-socket 'inet6))
167(udp-bind! s "::" 1337)
168(let loop ()
169  (receive (len str host port) (udp-recvfrom s 1024)
170      (print "received " len " bytes from [" host "]:" port " : " str))
171      (loop))
172(udp-close-socket s)
173</enscript>
174
175After running this script in a window, we can see the UDP listener:
176
177 $ netstat -n -p udp|grep 1337
178 udp46      0      0  *.1337                 *.*
179
180Then we can send data to the server over both IPv4 and IPv6 using netcat:
181
182 $ nc -6 -u localhost 1337
183 hello
184 ^C
185
186 $ nc -4 -u localhost 1337
187 hi
188 ^C
189
190The script should now produce output similar to:
191
192 received 6 bytes from [::1]:62028 : hello
193 received 3 bytes from [::ffff:127.0.0.1]:61031 : hi
194
195=== Daytime server
196
197Using {{daytime-client.scm}} from above (modified to use port 1313), you can
198connect to this example daytime server:
199
200<enscript highlight="scheme">
201;; daytime-server.scm
202(use udp6 posix)
203(define s (udp-open-socket 'inet6))
204(udp-bind! s "::" 1313)
205(let loop ()
206  (receive (len str host port) (udp-recvfrom s 1024)
207      (udp-sendto s host port (seconds->string))
208      (loop))
209(udp-close-socket s)
210</enscript>
211
212 $ csi -script daytime-server.scm &
213 $ csi -script daytime-client.scm
214 24 bytes from ::1:1313: Tue Feb 17 23:23:19 2015
215 $ csi -script daytime-client.scm
216 24 bytes from ::1:1313: Tue Feb 17 23:23:21 2015
217
218== Bugs and limitations
219
220Multicast is not yet implemented.
221
222== About this egg
223
224=== Source
225
226[[https://github.com/ursetto/udp6-egg]]
227
228=== Author
229
230[[http://3e8.org|Jim Ursetto]].  Originally by Category 5, with
231several enhancements by Daishi Kato, but has been rewritten on
232top of the [[/egg/socket|socket]] egg.
233
234=== Version History
235
236; 0.2 : Add Chicken 5 support. Add simple daytime client/server, echo server to {{tests/}} dir; not used during {{-test}}.
237; 0.1 : Initial release
238
239See [[/egg/udp|udp]] for previous history (up to 1.14).
240
241=== License
242
243 Copyright (c) 2011-2019, Jim Ursetto
244 Copyright (c) 2003-2004, Category 5
245 All rights reserved.
246 
247 Redistribution and use in source and binary forms, with or without
248 modification, are permitted provided that the following conditions are
249 met:
250 
251   Redistributions of source code must retain the above copyright notice,
252   this list of conditions and the following disclaimer. Redistributions in
253   binary form must reproduce the above copyright notice, this list of
254   conditions and the following disclaimer in the documentation and/or
255   other materials provided with the distribution. Neither the name of the
256   author nor the names of its contributors may be used to endorse or
257   promote products derived from this software without specific prior
258   written permission.
259 
260 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
261 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
262 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
263 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
264 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
265 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
266 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
267 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
268 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
269 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
270 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
271
Note: See TracBrowser for help on using the repository browser.