aboutsummaryrefslogtreecommitdiff
path: root/docs/introduction.html
diff options
context:
space:
mode:
authorThijs Schreijer <thijs@thijsschreijer.nl>2022-03-23 07:55:45 +0100
committerGitHub <noreply@github.com>2022-03-23 07:55:45 +0100
commitaf0ddb6ea845b285a6aa6a5019a448726ee23095 (patch)
treec9bca0319e32501b708b66eeabc5039c09cee352 /docs/introduction.html
parentc1eacfa6d24dc15476f5f9befa8370e2244931d4 (diff)
parent2eac8950396247b412c4089c23a46015c8cc12bb (diff)
downloadluasocket-af0ddb6ea845b285a6aa6a5019a448726ee23095.tar.gz
luasocket-af0ddb6ea845b285a6aa6a5019a448726ee23095.tar.bz2
luasocket-af0ddb6ea845b285a6aa6a5019a448726ee23095.zip
Merge pull request #361 from lunarmodules/docs
Diffstat (limited to 'docs/introduction.html')
-rw-r--r--docs/introduction.html333
1 files changed, 333 insertions, 0 deletions
diff --git a/docs/introduction.html b/docs/introduction.html
new file mode 100644
index 0000000..fd22f48
--- /dev/null
+++ b/docs/introduction.html
@@ -0,0 +1,333 @@
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<meta name="description" content="LuaSocket: Introduction to the core">
7<meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network,
8Library, Support">
9<title>LuaSocket: Introduction to the core</title>
10<link rel="stylesheet" href="reference.css" type="text/css">
11</head>
12
13<body>
14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17<div class=header>
18<hr>
19<center>
20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language
25</td></tr>
26</table>
27<p class=bar>
28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a>
33</p>
34</center>
35<hr>
36</div>
37
38<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2>Introduction</h2>
41
42<p>
43LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
44that is composed by two parts: a C core that provides support for the TCP
45and UDP transport layers, and a set of Lua modules that add support for
46the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
47downloading files) protocols and other functionality commonly needed by
48applications that deal with the Internet. This introduction is about the C
49core.
50</p>
51
52<p>
53Communication in LuaSocket is performed via I/O objects. These can
54represent different network domains. Currently, support is provided for TCP
55and UDP, but nothing prevents other developers from implementing SSL, Local
56Domain, Pipes, File Descriptors etc. I/O objects provide a standard
57interface to I/O across different domains and operating systems.
58</p>
59
60<p>
61The API design had two goals in mind. First, users
62experienced with the C API to sockets should feel comfortable using LuaSocket.
63Second, the simplicity and the feel of the Lua language should be
64preserved. 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>
66
67
68<p>
69One of the simplifications is the receive pattern capability.
70Applications can read data from stream domains (such as TCP)
71line by line, block by block, or until the connection is closed.
72All I/O reads are buffered and the performance differences between
73different receive patterns are negligible.
74</p>
75
76<p>
77Another advantage is the flexible timeout control
78mechanism. As in C, all I/O operations are blocking by default. For
79example, the <a href=tcp.html#send><tt>send</tt></a>,
80<a href=tcp.html#receive><tt>receive</tt></a> and
81<a href=tcp.html#accept><tt>accept</tt></a> methods
82of the TCP domain will block the caller application until
83the operation is completed (if ever!). However, with a call to the
84<a href=tcp.html#settimeout><tt>settimeout</tt></a>
85method, an application can specify upper limits on
86the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
87the time LuaSocket can internally be blocked by any OS call (the
88"<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
89call might perform several OS calls, so that the two timeout values are
90<em>not</em> equivalent.
91</p>
92
93<p>
94Finally, the host name resolution is transparent, meaning that most
95functions and methods accept both IP addresses and host names. In case a
96host name is given, the library queries the system's resolver and
97tries the main IP address returned. Note that direct use of IP addresses
98is more efficient, of course. The
99<a href=dns.html#toip><tt>toip</tt></a>
100and <a href=dns.html#tohostname><tt>tohostname</tt></a>
101functions from the DNS module are provided to convert between host names and IP addresses.
102</p>
103
104<p>
105Together, these changes make network programming in LuaSocket much simpler
106than it is in C, as the following sections will show.
107</p>
108
109<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111<h3 id=tcp>TCP</h3>
112
113<p>
114TCP (Transfer Control Protocol) is reliable stream protocol. In other
115words, applications communicating through TCP can send and receive data as
116an error free stream of bytes. Data is split in one end and
117reassembled transparently on the other end. There are no boundaries in
118the data transfers. The library allows users to read data from the
119sockets in several different granularities: patterns are available for
120lines, arbitrary sized blocks or "read up to connection closed", all with
121good performance.
122</p>
123
124<p>
125The library distinguishes three types of TCP sockets: <em>master</em>,
126<em>client</em> and <em>server</em> sockets.
127</p>
128
129<p>
130Master sockets are newly created TCP sockets returned by the function
131<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
132transformed into a server socket
133after it is associated with a <em>local</em> address by a call to the
134<a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the
135<a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket
136can be changed into a client socket with the method
137<a href=tcp.html#connect><tt>connect</tt></a>,
138which associates it with a <em>remote</em> address.
139</p>
140
141<p>
142On server sockets, applications can use the
143<a href=tcp.html#accept><tt>accept</tt></a> method
144to wait for a client connection. Once a connection is established, a
145client socket object is returned representing this connection. The
146other methods available for server socket objects are
147<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
148<a href=tcp.html#setoption><tt>setoption</tt></a>,
149<a href=tcp.html#settimeout><tt>settimeout</tt></a>, and
150<a href=tcp.html#close><tt>close</tt></a>.
151</p>
152
153<p>
154Client sockets are used to exchange data between two applications over
155the Internet. Applications can call the methods
156<a href=tcp.html#send><tt>send</tt></a> and
157<a href=tcp.html#receive><tt>receive</tt></a>
158to send and receive data. The other methods
159available for client socket objects are
160<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
161<a href=tcp.html#getpeername><tt>getpeername</tt></a>,
162<a href=tcp.html#setoption><tt>setoption</tt></a>,
163<a href=tcp.html#settimeout><tt>settimeout</tt></a>,
164<a href=tcp.html#shutdown><tt>shutdown</tt></a>, and
165<a href=tcp.html#close><tt>close</tt></a>.
166</p>
167
168<p>
169Example:
170</p>
171<blockquote>
172<p>
173A simple echo server, using LuaSocket. The program binds to an ephemeral
174port (one that is chosen by the operating system) on the local host and
175awaits client connections on that port. When a connection is established,
176the program reads a line from the remote end and sends it back, closing
177the connection immediately. You can test it using the telnet
178program.
179</p>
180
181<pre class=example>
182-- load namespace
183local socket = require("socket")
184-- create a TCP socket and bind it to the local host, at any port
185local server = assert(socket.bind("*", 0))
186-- find out which port the OS chose for us
187local ip, port = server:getsockname()
188-- print a message informing what's up
189print("Please telnet to localhost on port " .. port)
190print("After connecting, you have 10s to enter a line to be echoed")
191-- loop forever waiting for clients
192while 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()
203end
204</pre>
205</blockquote>
206
207<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
208
209<h3 id=udp>UDP</h3>
210
211<p>
212UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
213other words, applications communicating through UDP send and receive
214data as independent blocks, which are not guaranteed to reach the other
215end. Even when they do reach the other end, they are not guaranteed to be
216error free. Data transfers are atomic, one datagram at a time. Reading
217only part of a datagram discards the rest, so that the following read
218operation will act on the next datagram. The advantages are in
219simplicity (no connection setup) and performance (no error checking or
220error correction).
221</p>
222
223<p>
224Note that although no guarantees are made, these days
225networks are so good that, under normal circumstances, few errors
226happen in practice.
227</p>
228
229<p>
230An UDP socket object is created by the
231<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
232sockets do not need to be connected before use. The method
233<a href=udp.html#sendto><tt>sendto</tt></a>
234can be used immediately after creation to
235send a datagram to IP address and port. Host names are not allowed
236because performing name resolution for each packet would be forbiddingly
237slow. Methods
238<a href=udp.html#receive><tt>receive</tt></a> and
239<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
240can be used to retrieve datagrams, the latter returning the IP and port of
241the sender as extra return values (thus being slightly less
242efficient).
243</p>
244
245<p>
246When communication is performed repeatedly with a single peer, an
247application should call the
248<a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
249permanent partner. Methods
250<a href=udp.html#sendto><tt>sendto</tt></a> and
251<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
252can no longer be used, but the method
253<a href=udp.html#send><tt>send</tt></a> can be used to send data
254directly to the peer, and the method
255<a href=udp.html#receive><tt>receive</tt></a>
256will only return datagrams originating
257from that peer. There is about 30% performance gain due to this practice.
258</p>
259
260<p>
261To associate an UDP socket with a local address, an application calls the
262<a href=udp.html#setsockname><tt>setsockname</tt></a>
263method <em>before</em> sending any datagrams. Otherwise, the socket is
264automatically bound to an ephemeral address before the first data
265transmission and once bound the local address cannot be changed.
266The other methods available for UDP sockets are
267<a href=udp.html#getpeername><tt>getpeername</tt></a>,
268<a href=udp.html#getsockname><tt>getsockname</tt></a>,
269<a href=udp.html#settimeout><tt>settimeout</tt></a>,
270<a href=udp.html#setoption><tt>setoption</tt></a> and
271<a href=udp.html#close><tt>close</tt></a>.
272</p>
273
274<p>
275Example:
276</p>
277<blockquote>
278<p>
279A simple daytime client, using LuaSocket. The program connects to a remote
280server and tries to retrieve the daytime, printing the answer it got or an
281error message.
282</p>
283
284<pre class=example>
285-- change here to the host an port you want to contact
286local host, port = "localhost", 13
287-- load namespace
288local socket = require("socket")
289-- convert host name to ip address
290local ip = assert(socket.dns.toip(host))
291-- create a new UDP object
292local udp = assert(socket.udp())
293-- contact daytime host
294assert(udp:sendto("anything", ip, port))
295-- retrieve the answer and print results
296io.write(assert(udp:receive()))
297</pre>
298</blockquote>
299
300<!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
301
302<h3 id=more>Support modules</h3>
303
304<p> Although not covered in the introduction, LuaSocket offers
305much more than TCP and UDP functionality. As the library
306evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>,
307and <a href=smtp.html>SMTP</a> were built on top of these. These modules
308and many others are covered by the <a href=reference.html>reference manual</a>.
309</p>
310
311<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
312
313<div class=footer>
314<hr>
315<center>
316<p class=bar>
317<a href="index.html">home</a> &middot;
318<a href="index.html#down">download</a> &middot;
319<a href="installation.html">installation</a> &middot;
320<a href="introduction.html">introduction</a> &middot;
321<a href="reference.html">reference</a>
322</p>
323<p>
324<small>
325Last modified by Diego Nehab on <br>
326Thu Apr 20 00:25:36 EDT 2006
327</small>
328</p>
329</center>
330</div>
331
332</body>
333</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-01 23:06:37 +0000