aboutsummaryrefslogtreecommitdiff
path: root/doc/introduction.html
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade /doc/introduction.html
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip
LuaSocket 2.0 User's Manual.
Diffstat (limited to 'doc/introduction.html')
-rw-r--r--doc/introduction.html328
1 files changed, 328 insertions, 0 deletions
diff --git a/doc/introduction.html b/doc/introduction.html
new file mode 100644
index 0000000..7adf45b
--- /dev/null
+++ b/doc/introduction.html
@@ -0,0 +1,328 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4
5<head>
6<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2>Introduction</h2>
37
38<p>
39Communication in LuaSocket is performed via I/O objects. These can
40represent different network domains. Currently, support is
41provided for TCP and UDP, but there is work in progress to implement SSL,
42Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard
43interface to I/O across different domains and operating systems.
44LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future
45addition new domains.
46</p>
47
48<p>
49The LuaSocket API was designed with two goals in mind. First, users
50experienced with the C API to sockets should feel comfortable using LuaSocket.
51Second, the simplicity and the feel of the Lua language should be
52preserved. 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.
53</p>
54
55<p>
56One of the simplifications is the timeout control
57mechanism. As in C, all I/O operations are blocking by default. For
58example, the <a href=tcp.html#send><tt>send</tt></a>,
59<a href=tcp.html#receive><tt>receive</tt></a> and
60<a href=tcp.html#accept><tt>accept</tt></a> methods
61of the TCP domain will block the caller application until
62the operation is completed (if ever!). However, with a call to the
63<a href=tcp.html#settimeout><tt>settimeout</tt></a>
64method, an application can specify upper limits on
65the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
66the time LuaSocket can internally be blocked by any OS call (the
67"<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
68call might perform several OS calls, so that the two timeout values are
69<em>not</em> equivalent.
70</p>
71
72<p>
73Another important difference is the receive pattern capability.
74Applications can read data from stream domains (such as TCP)
75line by line, block by block, or until the connection is closed.
76All I/O reads are buffered and the performance differences between
77different receive patterns are negligible.
78</p>
79
80<p>
81Finally, the host name resolution is transparent, meaning that most
82functions and methods accept both IP addresses and host names. In case a
83host name is given, the library queries the system's resolver and
84tries the main returned IP address. Note that direct use of IP addresses
85is more efficient, of course. The
86<a href=dns.html#toip><tt>toip</tt></a>
87and <a href=dns.html#tohostname><tt>tohostname</tt></a>
88functions from the DNS module are provided to convert between host names and IP addresses.
89</p>
90
91<p>
92Previous versions of LuaSocket provided global functions for operating on
93I/O objects. To give the library a Lua 5.0 feel, these have been eliminated
94from LuaSocket 2.0. I/O operations are only available as methods of the
95corresponding I/O objects. Naturally, different I/O objects accept
96different operations. The core functionality for TCP and UDP objects is
97introduced in the following sections, following a few words about
98initialization.
99</p>
100
101<!-- initializing +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
102
103<h3>Initializing the library</h3>
104
105<p>
106Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket
107functionality is defined inside a table (or rather a namespace) stored with
108the global name <tt>socket</tt>. To have this table created and its
109contents made available to a Lua script, the interpreter running the script
110must be linked to the LuaSocket library, and to whatever libraries the
111host OS requires for network access (Windows requires ws2_32.lib, for
112instance). LuaSocket is initialized in the
113Lua state given as the argument to the function
114<tt>luaopen_socket</tt>, the only C function exported by the library.
115After initialization, the scripts are free to use all LuaSocket API.
116</p>
117
118<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
119
120<h3 id=tcp>TCP</h3>
121
122<p>
123TCP (Transfer Control Protocol) is reliable stream protocol. In other
124words, applications communicating through TCP can send and receive data as
125an error free stream of bytes. Data is split in one end and
126reassembled transparently on the other end. There are no boundaries in
127the data transfers. The library allows users to read data from the
128sockets in several different granularity: patterns are available for
129lines, arbitrary sized blocks or "read up to connection closed", all with
130good performance.
131</p>
132
133<p>
134The library distinguishes three types of TCP sockets: master, client and server sockets.
135</p>
136
137<p>
138Master sockets are newly created TCP sockets returned by the function
139<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
140transformed into a server socket
141after it is associated with a <em>local</em> address by a call to the
142<a href=tcp.html#bind><tt>bind</tt></a> method. Conversely, it
143can be changed into a client socket with the method
144<a href=tcp.html#connect><tt>connect</tt></a>,
145that associates it with a <em>remote</em> address.
146</p>
147
148<p>
149On server sockets, applications can use the
150<a href=tcp.html#accept><tt>accept</tt></a> method
151to wait for a client connection. Once a connection is established, a
152client socket object is returned representing this connection. The
153other methods available for server socket objects are
154<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
155<a href=tcp.html#setoption><tt>setoption</tt></a>,
156<a href=tcp.html#settimeout><tt>settimeout</tt></a> and
157<a href=tcp.html#close><tt>close</tt></a>.
158</p>
159
160<p>
161Client sockets are used to exchange data between two applications over
162the Internet. Applications can call the methods
163<a href=tcp.html#send><tt>send</tt></a> and
164<a href=tcp.html#receive><tt>receive</tt></a>
165to send and receive data. The other methods
166available for client socket objects are
167<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
168<a href=tcp.html#getpeername><tt>getpeername</tt></a>,
169<a href=tcp.html#setoption><tt>setoption</tt></a>,
170<a href=tcp.html#settimeout><tt>settimeout</tt></a> and
171<a href=tcp.html#close><tt>close</tt></a>.
172</p>
173
174<p>
175Example:
176</p>
177<blockquote>
178<p>
179A simple echo server, using LuaSocket. The program binds to an ephemeral
180port (one that is chosen by the operating system) on the local host and
181awaits client connections on that port. When a connection is established,
182the program reads a line from the remote end and sends it back, closing
183the connection immediately after. You can test it using the telnet
184program.
185</p>
186
187<pre class=example>
188-- create a new TCP object
189server, err = socket.tcp()
190assert(server, err)
191-- bind it to the local host, at any port
192ret, err = server:bind("*", 0)
193assert(ret, err)
194-- find out which port the OS chose for us
195ip, port = server:getsockname()
196-- print a message informing what's up
197print("Please telnet to localhost on port " .. port)
198print("After connecting, you have 10s to enter a line to be echoed")
199-- loop forever waiting for clients
200while 1 do
201 -- wait for a conection from any client
202 client, err = server:accept()
203 -- make sure we don't block waiting for this client's line
204 client:settimeout(10)
205 -- receive the line
206 line, err = client:receive()
207 -- if there was no error, send it back to the client
208 if not err then
209 client:send(line .. "\n")
210 end
211 -- done with client, close the object
212 client:close()
213end
214</pre>
215</blockquote>
216
217<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
218
219<h3 id=udp>UDP</h3>
220
221<p>
222UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
223other words, applications communicating through UDP send and receive
224data as independent blocks, which are not guaranteed to reach the other
225end. Even when they do reach the other end, they are not guaranteed to be
226error free. Data transfers are atomic, one datagram at a time. Reading
227only part of a datagram discards the rest, so that the following read
228operation will act on the next datagram. The advantages are in
229simplicity (no connection setup) and performance (no error checking or
230error correction).
231</p>
232
233<p>
234An UDP socket object is created by the
235<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
236sockets do not need to be connected before use. The method
237<a href=udp.html#sendto><tt>sendto</tt></a>
238can be used immediately after creation to
239send a datagram to IP address and port. Host names are not allowed
240because performing name resolution for each packet would be forbiddingly
241slow. Methods
242<a href=udp.html#receive><tt>receive</tt></a> and
243<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
244can be used to retrieve datagrams, the latter returning the IP and port of
245the sender as extra return values (thus being slightly less
246efficient).
247</p>
248
249<p>
250When communication is performed repeatedly with a single peer, an
251application should call the
252<a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
253permanent partner. Methods
254<a href=udp.html#sendto><tt>sendto</tt></a> and
255<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
256can no longer be used, but the method
257<a href=udp.html#send><tt>send</tt></a> can be used to send data
258directly to the peer, and the method
259<a href=udp.html#receive><tt>receive</tt></a>
260will only return datagrams originating
261from that peer. There is about 30% performance gain due to this practice.
262</p>
263
264<p>
265To associate an UDP socket with a local address, an application calls the
266<a href=udp.html#setsockname><tt>setsockname</tt></a>
267method <em>before</em> sending any datagrams. Otherwise, the socket is
268automatically bound to an ephemeral address before the first data
269transmission and once bound the local address cannot be changed.
270The other methods available for UDP sockets are
271<a href=udp.html#getpeername><tt>getpeername</tt></a>,
272<a href=udp.html#getsockname><tt>getsockname</tt></a>,
273<a href=udp.html#settimeout><tt>settimeout</tt></a>,
274<a href=udp.html#setoption><tt>setoption</tt></a> and
275<a href=udp.html#close><tt>close</tt></a>.
276</p>
277
278<p>
279Example:
280</p>
281<blockquote>
282<p>
283A simple daytime client, using LuaSocket. The program connects to a remote
284server and tries to retrieve the daytime, printing the answer it got or an
285error message.
286</p>
287
288<pre class=example>
289host = "localhost" -- change here to the host you want to contact
290port = port or 13
291-- convert host name to ip address
292ip, err = socket.toip(host)
293assert(ip, err)
294-- create a new UDP object
295udp = socket.udp()
296-- contact daytime host
297nsent, err = udp:sendto("anything", ip, port)
298assert(not err, err)
299-- retrieve the answer
300dgram, err = udp:receive()
301assert(dgram, err)
302-- display to user
303print(dgram)
304</pre>
305</blockquote>
306
307<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
308
309<div class=footer>
310<hr>
311<center>
312<p class=bar>
313<a href="home.html">home</a> &middot;
314<a href="home.html#down">download</a> &middot;
315<a href="introduction.html">introduction</a> &middot;
316<a href="reference.html">reference</a>
317</p>
318<p>
319<small>
320Last modified by Diego Nehab on <br>
321Sat Aug 9 01:00:41 PDT 2003
322</small>
323</p>
324</center>
325</div>
326
327</body>
328</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-15 07:32:52 +0000