| blob | fd22f483deb7dddf6bc0707ffe9c1517df62efa1 |
3 <html>
5 <head>
11 </head>
13 <body>
15 <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
18 <hr>
19 <center>
23 </a></td></tr>
25 </td></tr>
26 </table>
33 </p>
34 </center>
35 <hr>
36 </div>
38 <!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
42 <p>
44 that is composed by two parts: a C core that provides support for the TCP
45 and UDP transport layers, and a set of Lua modules that add support for
46 the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
47 downloading files) protocols and other functionality commonly needed by
48 applications that deal with the Internet. This introduction is about the C
49 core.
50 </p>
52 <p>
53 Communication in LuaSocket is performed via I/O objects. These can
54 represent different network domains. Currently, support is provided for TCP
55 and UDP, but nothing prevents other developers from implementing SSL, Local
56 Domain, Pipes, File Descriptors etc. I/O objects provide a standard
57 interface to I/O across different domains and operating systems.
58 </p>
60 <p>
61 The API design had two goals in mind. First, users
62 experienced with the C API to sockets should feel comfortable using LuaSocket.
63 Second, the simplicity and the feel of the Lua language should be
64 preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified.
65 </p>
68 <p>
69 One of the simplifications is the receive pattern capability.
70 Applications can read data from stream domains (such as TCP)
71 line by line, block by block, or until the connection is closed.
72 All I/O reads are buffered and the performance differences between
73 different receive patterns are negligible.
74 </p>
76 <p>
77 Another advantage is the flexible timeout control
78 mechanism. As in C, all I/O operations are blocking by default. For
82 of the TCP domain will block the caller application until
83 the operation is completed (if ever!). However, with a call to the
85 method, an application can specify upper limits on
86 the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
87 the time LuaSocket can internally be blocked by any OS call (the
88 "<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
89 call might perform several OS calls, so that the two timeout values are
91 </p>
93 <p>
94 Finally, the host name resolution is transparent, meaning that most
95 functions and methods accept both IP addresses and host names. In case a
96 host name is given, the library queries the system's resolver and
97 tries the main IP address returned. Note that direct use of IP addresses
98 is more efficient, of course. The
101 functions from the DNS module are provided to convert between host names and IP addresses.
102 </p>
104 <p>
105 Together, these changes make network programming in LuaSocket much simpler
106 than it is in C, as the following sections will show.
107 </p>
109 <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
113 <p>
114 TCP (Transfer Control Protocol) is reliable stream protocol. In other
115 words, applications communicating through TCP can send and receive data as
116 an error free stream of bytes. Data is split in one end and
117 reassembled transparently on the other end. There are no boundaries in
118 the data transfers. The library allows users to read data from the
119 sockets in several different granularities: patterns are available for
120 lines, arbitrary sized blocks or "read up to connection closed", all with
121 good performance.
122 </p>
124 <p>
127 </p>
129 <p>
130 Master sockets are newly created TCP sockets returned by the function
132 transformed into a server socket
136 can be changed into a client socket with the method
139 </p>
141 <p>
142 On server sockets, applications can use the
144 to wait for a client connection. Once a connection is established, a
145 client socket object is returned representing this connection. The
146 other methods available for server socket objects are
151 </p>
153 <p>
154 Client sockets are used to exchange data between two applications over
155 the Internet. Applications can call the methods
158 to send and receive data. The other methods
159 available for client socket objects are
166 </p>
168 <p>
169 Example:
170 </p>
171 <blockquote>
172 <p>
173 A simple echo server, using LuaSocket. The program binds to an ephemeral
174 port (one that is chosen by the operating system) on the local host and
175 awaits client connections on that port. When a connection is established,
176 the program reads a line from the remote end and sends it back, closing
177 the connection immediately. You can test it using the telnet
178 program.
179 </p>
182 -- load namespace
183 local socket = require("socket")
184 -- create a TCP socket and bind it to the local host, at any port
186 -- find out which port the OS chose for us
187 local ip, port = server:getsockname()
188 -- print a message informing what's up
189 print("Please telnet to localhost on port " .. port)
190 print("After connecting, you have 10s to enter a line to be echoed")
191 -- loop forever waiting for clients
192 while 1 do
193 -- wait for a connection from any client
194 local client = server:accept()
195 -- make sure we don't block waiting for this client's line
196 client:settimeout(10)
197 -- receive the line
198 local line, err = client:receive()
199 -- if there was no error, send it back to the client
200 if not err then client:send(line .. "\n") end
201 -- done with client, close the object
202 client:close()
203 end
204 </pre>
205 </blockquote>
207 <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
211 <p>
212 UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
213 other words, applications communicating through UDP send and receive
214 data as independent blocks, which are not guaranteed to reach the other
215 end. Even when they do reach the other end, they are not guaranteed to be
216 error free. Data transfers are atomic, one datagram at a time. Reading
217 only part of a datagram discards the rest, so that the following read
218 operation will act on the next datagram. The advantages are in
219 simplicity (no connection setup) and performance (no error checking or
220 error correction).
221 </p>
223 <p>
224 Note that although no guarantees are made, these days
225 networks are so good that, under normal circumstances, few errors
226 happen in practice.
227 </p>
229 <p>
230 An UDP socket object is created by the
232 sockets do not need to be connected before use. The method
234 can be used immediately after creation to
235 send a datagram to IP address and port. Host names are not allowed
236 because performing name resolution for each packet would be forbiddingly
237 slow. Methods
240 can be used to retrieve datagrams, the latter returning the IP and port of
241 the sender as extra return values (thus being slightly less
242 efficient).
243 </p>
245 <p>
246 When communication is performed repeatedly with a single peer, an
247 application should call the
249 permanent partner. Methods
252 can no longer be used, but the method
254 directly to the peer, and the method
256 will only return datagrams originating
257 from that peer. There is about 30% performance gain due to this practice.
258 </p>
260 <p>
261 To associate an UDP socket with a local address, an application calls the
264 automatically bound to an ephemeral address before the first data
265 transmission and once bound the local address cannot be changed.
266 The other methods available for UDP sockets are
272 </p>
274 <p>
275 Example:
276 </p>
277 <blockquote>
278 <p>
279 A simple daytime client, using LuaSocket. The program connects to a remote
280 server and tries to retrieve the daytime, printing the answer it got or an
281 error message.
282 </p>
285 -- change here to the host an port you want to contact
287 -- load namespace
288 local socket = require("socket")
289 -- convert host name to ip address
290 local ip = assert(socket.dns.toip(host))
291 -- create a new UDP object
292 local udp = assert(socket.udp())
293 -- contact daytime host
294 assert(udp:sendto("anything", ip, port))
295 -- retrieve the answer and print results
296 io.write(assert(udp:receive()))
297 </pre>
298 </blockquote>
300 <!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
304 <p> Although not covered in the introduction, LuaSocket offers
305 much more than TCP and UDP functionality. As the library
309 </p>
311 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
314 <hr>
315 <center>
322 </p>
323 <p>
324 <small>
325 Last modified by Diego Nehab on <br>
327 </small>
328 </p>
329 </center>
330 </div>
332 </body>
333 </html>