source: project/chicken/trunk/manual/Unit tcp @ 12227

Last change on this file since 12227 was 12227, checked in by felix winkelmann, 11 years ago
  • added helpful script for testing in build dir
  • chicken-install checks for TCP timeouts and handles multiple default sources to download from
  • alias-global-hook is saved and restored when loading compiler extensions
  • making bootstrap automaticaly makes confclean
File size: 6.5 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit tcp
5
6This unit provides basic facilities for communicating over TCP sockets.
7The socket interface should be mostly compatible to the one found in
8PLT Scheme.
9
10This unit uses the {{extras}} unit.
11
12All errors related to failing network operations will raise a condition
13of kind {{(exn i/o network)}}.
14
15
16=== tcp-listen
17
18 [procedure] (tcp-listen TCPPORT [BACKLOG [HOST]])
19
20Creates and returns a TCP listener object that listens for connections on {{TCPPORT}}, which
21should be an exact integer. {{BACKLOG}} specifies the number of maximally pending
22connections (and defaults to 4). If the optional argument {{HOST}} is given and not
23{{#f}}, then only incoming connections for the given host (or IP) are accepted.
24
25
26=== tcp-listener?
27
28 [procedure] (tcp-listener? X)
29
30Returns {{#t}} if {{X}} is a TCP listener object, or {{#f}} otherwise.
31
32
33=== tcp-close
34
35 [procedure] (tcp-close LISTENER)
36
37Reclaims any resources associated with {{LISTENER}}.
38
39
40=== tcp-accept
41
42 [procedure] (tcp-accept LISTENER)
43
44Waits until a connection is established on the port on which
45{{LISTENER}} is listening and returns two values: an input- and
46output-port that can be used to communicate with the remote
47process. The current value of {{tcp-accept-timeout}} is used to
48determine the maximal number of milliseconds (if any) to wait
49until a connection is established. When a client connects any
50read- and write-operations on the returned ports will use the
51current values (at the time of the connection) of {{tcp-read-timeout}}
52and {{tcp-write-timeout}}, respectively, to determine the maximal
53number of milliseconds to wait for input/output before a timeout
54error is signalled by raising an exception of the kinds {{(exn i/o net)}}.
55
56Note: this operation and any I/O on the ports returned will not block
57other running threads.
58
59
60=== tcp-accept-ready?
61
62 [procedure] (tcp-accept-ready? LISTENER)
63
64Returns {{#t}} if there are any connections pending on {{LISTENER}}, or {{#f}}
65otherwise.
66
67
68=== tcp-listener-port
69
70 [procedure] (tcp-listener-port LISTENER)
71
72Returns the port number assigned to {{LISTENER}} (If you pass {{0}} to {{tcp-listen}},
73then the system will choose a port-number for you).
74
75=== tcp-listener-fileno
76
77 [procedure] (tcp-listener-fileno LISTENER)
78
79Returns the file-descriptor associated with {{LISTENER}}.
80
81
82=== tcp-connect
83
84 [procedure] (tcp-connect HOSTNAME [TCPPORT])
85
86Establishes a client-side TCP connection to the machine with the name
87{{HOSTNAME}} (a string) at {{TCPPORT}} (an exact integer) and returns
88two values: an input- and output-port for communicating with the
89remote process. The current value of {{tcp-connect-timeout}} is used
90to determine the maximal number of milliseconds (if any) to wait until
91the connection is established. When the connection takes place any
92read- and write-operations on the returned ports will use the current
93values (at the time of the call to {{tcp-connect}}) of {{tcp-read-timeout}} and
94{{tcp-write-timeout}}, respectively, to determine the maximal number
95of milliseconds to wait for input/output before a timeout error is
96signalled by raising an exception of the kinds {{(exn i/o net)}}.
97
98If the {{TCPPORT}} is omitted, the port is parsed from the {{HOSTNAME}} string.  The format expected is {{HOSTNAME:PORT}}.  The {{PORT}} can either be a string representation of an integer or a service name which is translated to an integer using the POSIX function [[http://www.opengroup.org/onlinepubs/009695399/functions/getservbyname.html|{{getservbyname}}]].
99
100Note: any I/O on the ports returned will not block other running threads.
101
102
103=== tcp-addresses
104
105 [procedure] (tcp-addresses PORT)
106
107Returns two values for the input- or output-port {{PORT}} (which should be a port returned
108by either {{tcp-accept}} or {{tcp-connect}}): the IP address of the local and the remote
109machine that are connected over the socket associated with {{PORT}}. The returned addresses
110are strings in {{XXX.XXX.XXX.XXX}} notation.
111
112
113=== tcp-port-numbers
114
115 [procedure] (tcp-port-numbers PORT)
116
117Returns two values for the input- or output-port {{PORT}} (which should be a port returned
118by either {{tcp-accept}} or {{tcp-connect}}): the TCP port numbers of the local and the remote
119machine that are connected over the socket associated with {{PORT}}.
120
121
122=== tcp-abandon-port
123
124 [procedure] (tcp-abandon-port PORT)
125
126Marks the socket port {{PORT}} as abandoned. This is mainly useful to close down a port
127without breaking the connection.
128
129
130=== tcp-buffer-size
131
132 [parameter] tcp-buffer-size
133
134Sets the size of the output buffer. By default no output-buffering for
135TCP output is done, but to improve performance by minimizing the
136number of TCP packets, buffering may be turned on by setting this
137parameter to an exact integer greater zero. A buffer size of zero or {{#f}}
138turns buffering off. The setting of this parameter takes effect at the time
139when the I/O ports for a particular socket are created, i.e. when {{tcp-connect}}
140or {{tcp-accept}} is called.
141
142Note that since output is not immediately written to the associated socket, you
143may need to call {{flush-output}}, once you want the output to be transmitted.
144Closing the output port will flush automatically.
145
146=== tcp-read-timeout
147
148 [parameter] tcp-read-timeout
149
150Determines the timeout for TCP read operations in milliseconds. A timeout of
151{{#f}} disables timeout checking. The default read timeout is 60000, i.e.
1521 minute.
153
154=== tcp-write-timeout
155
156 [parameter] tcp-write-timeout
157
158Determines the timeout for TCP write operations in milliseconds. A timeout of
159{{#f}} disables timeout checking. The default write timeout is 60000, i.e.
1601 minute.
161
162=== tcp-connect-timeout
163
164 [parameter] tcp-connect-timeout
165
166Determines the timeout for {{tcp-connect}} operations in milliseconds. A timeout of
167{{#f}} disables timeout checking and is the default.
168
169
170=== tcp-accept-timeout
171
172 [parameter] tcp-accept-timeout
173
174Determines the timeout for {{tcp-accept}} operations in milliseconds. A timeout of
175{{#f}} disables timeout checking and is the default.
176
177
178=== Example
179
180A very simple example follows. Say we have the two files {{client.scm}}
181and {{server.scm}}:
182
183<enscript highlight=scheme>
184; client.scm
185(declare (uses tcp))
186(define-values (i o) (tcp-connect "localhost" 4242))
187(write-line "Good Bye!" o)
188(print (read-line i))
189</enscript>
190
191<enscript highlight=scheme>
192; server.scm
193(declare (uses tcp))
194(define l (tcp-listen 4242))
195(define-values (i o) (tcp-accept l))
196(write-line "Hello!" o)
197(print (read-line i))
198(close-input-port i)
199(close-output-port o)
200</enscript>
201
202 % csc server.scm
203 % csc client.scm
204 % ./server &
205 % ./client
206 Good Bye!
207 Hello!
208
209Previous: [[Unit utils]]
210
211Next: [[Unit lolevel]]
Note: See TracBrowser for help on using the repository browser.