1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta name="description" content="The LuaSocket Homepage">
<meta name="keywords" content="Lua, Library, Network, Support, Internet">
<title>LuaSocket: Network support for the Lua language </title>
<link rel="stylesheet" href="reference.css" type="text/css">
</head>
<body>
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header>
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
</a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language
</td></tr>
</table>
<p class=bar>
<a href="home.html">home</a> ·
<a href="home.html#download">download</a> ·
<a href="introduction.html">introduction</a> ·
<a href="reference.html">reference</a>
</p>
</center>
<hr>
</div>
<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=whatis>What is LuaSocket?</h2>
<p>
LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
that is composed by two parts: a C core that provides support for the TCP
and UDP transport layers, and a set of Lua modules that add support for
functionality commonly needed by applications that deal with the Internet.
</p>
<p>
The core support has been implemented so that it is both efficient and
simple to use. The core can be used by any Lua application once it has
been properly initialized by the interpreter running the
Lua application. The code has been tested and runs well on several Windows
and Unix platforms.
</p>
<p>
The most used modules implement the
<a href=smtp.html>SMTP</a>
(sending e-mails),
<a href=http.html>HTTP</a>
(WWW access) and
<a href=ftp.html>FTP</a>
(uploading and downloading files) client
protocols. These provide a very natural and generic interface to the e
functionality covered by the protocols.
In addition, you will find that the
<a href=mime.html>MIME</a> (common encodings),
<a href=url.html>URL</a>
(anything you could possible want to do with one) and
<a href=ltn12.html>LTN12</a>
(filters, sinks, sources and pumps) modules can be very handy.
</p>
<p>
The library is available under the same
<a href="http://www.lua.org/copyright.html">
terms and conditions</a> as the Lua language, the MIT license. The idea is
that if you can use Lua in a project, you should also be able to use
LuaSocket.
</p>
<p>
Copyright © 1999-2004 Tecgraf/PUC-Rio. All rights reserved. <br>
Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
</p>
<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=download>Download</h2>
<p>
LuaSocket version 2.0 beta is now available for download! It is
compatible with Lua 5.0 and has been tested on
Windows XP, Linux, and Mac OS X.
</p>
<p>
The library can be downloaded in source code from the following links:
</p>
<blockquote>
<p>
<a href="luasocket-2.0-beta.tar.gz">luasocket-2.0-beta.tar.gz</a> <br>
<a href="luasocket-2.0-beta.zip">luasocket-2.0-beta.zip</a>
</p>
</blockquote>
<p>
Besides the full C and Lua source code for the library, the distribution
contains several examples, this user's manual and the test procedures.
</p>
<p>
I am also providing PC Win32 binaries for those that want to give
LuaSocket a quick try:
</p>
<blockquote>
<p>
<a href="luasocket-2.0-beta-win32.zip">luasocket-2.0-beta-win32.zip</a>
</p>
</blockquote>
<p>
The quick and dirty way to use these binaries is to unpack everything into a
directory, say <tt>c:\luasocket</tt> (include all Lua files from the
LuaSocket distrbitution in the same directory too!).
Then set <tt>LUA_INIT</tt> to load the <tt>lua.lua</tt> helper file:
</p>
<pre class=example>
c:\luasocket\> set LUA_INIT=@lua.lua
</pre>
<p>
From that directory, you can then run the interpreter and it should find all
files it needs. To download this manual page from the Internet, for example,
do the following:
</p>
<pre class=example>
c:\luasocket\> lua
Lua 5.0.2 Copyright (C) 1994-2004 Tecgraf, PUC-Rio
> http = require"http"
> print(http.request"http://www.tecgraf.puc-rio.br/luasocket/")
--> this file
</pre>
<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=thanks>Special thanks</h2>
<p>
Throughout LuaSocket's history, many people gave suggestions that helped
improve it. For that, I thank the Lua community.
Special thanks go to
David Burgess, who has helped push the library to a new level of quality and
from whom I have learned a lot of stuff that doesn't show up in RFCs.
Special thanks also to Carlos Cassino, who played a big part in the
extensible design seen in the C core of LuaSocket 2.0.
</p>
<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=new>What's New</h2>
<p>
<em>Everything</em> is new! Many changes for 2.0 happened in the C layer,
which has been almost completely rewritten. The code has been ported to
Lua 5.0 and greatly improved. There have also been some API changes
that made the interface simpler and more consistent. Here are some of
the changes that made it into version 2.0:
</p>
<ul>
<li> Major C code rewrite. Code is modular and extensible. Hopefully, other
developers will be motivated to provide code for SSL, local domain
sockets, file descriptors, pipes (on Unix) and named pipes etc;
<li> Everything that is exported by the library is exported inside
namespaces. These should be obtained with calls to the
<tt>require</tt> function;
<li> Functions such as
send/receive/timeout/close etc do not exist anymore as stand-alone
functions. They are now only available as methods of the appropriate
objects;
<li> All functions return a non-nil value as first return value if successful.
All functions return <b><tt>nil</tt></b> followed by error message
in case of error. This made the library much easier to use;
<li> Greatly reduced the number of times the C select is called
during data transfers, by calling only on failure. This might
improve a lot the maximum throughput;
<li> TCP has been changed to become more uniform. It's possible to first
create a TCP object,
then connect or bind if needed, and finally use I/O functions.
<tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still
provided for simplicity;
<li> This allows for setting a timeout value before connecting;
<li> And also allows binding to a local address before connecting;
<li> New <tt>socket.dns.gethostname</tt> function and <tt>shutdown</tt>
method;
<li> Better error messages and parameter checking;
<li> Should be interrupt safe;
<li> UDP connected sockets can break association with peer by calling
<tt>setpeername</tt> with address '<tt>*</tt>';
<li> Sets returned by <tt>socket.select</tt> are associative;
<li> Select checks if sockets have buffered data and returns immediately;
<li> <tt>socket.sleep</tt> and <tt>socket.gettime</tt> are now part of the
library and are supported. They used to be available only when
LUASOCKET_DEBUG was defined, but it turns out they might be useful for
applications;
<li> <tt>socket.try</tt> and <tt>socket.protect</tt> provide a simple
interface to exceptions that proved very in the implementation of
high-level modules;
<li> Socket options interface has been improved. TCP objects also
support socket options and many new options were added.
</ul>
<p>
Lots of changes in the Lua modules, too!
</p>
<ul>
<li> Every module loads only the modules that it needs. There is no waste
of memory. LuaSocket core takes only 20k of memory;
<li> New MIME and LTN12 modules make all other modules much more powerful;
<li> Support for multipart messages in the SMTP module;
<li> The old callback mechanism of FTP and HTTP has been replaced with LTN12 sources and sinks, with advantage;
<li> Common implementation for low-level FTP and SMTP;
<li> FTP, HTTP, and SMTP are implemented in multiple levels in such a way
that users will have no problems extending the functionality to satisfy
personal needs;
<li> SMTP knows how to perform LOGIN and PLAIN authentication.
</ul>
<!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=incompatible>Incompatibilities with previous versions</h3>
<ul>
<li> The introduction of namespaces affects all programs that use LuaSocket,
specially code that relies on global functions. These are no longer
available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt>
etc) are independent now and should be "<tt>require</tt>"d;
<li> FTP, SMTP and HTTP are completely new; I am sure you will
agree the new stuff is better;
<li> WARNING: The new <tt>send</tt>, <tt><b>receive</b></tt>,
<tt>sendto</tt>, <tt>setpeername</tt> and <tt>setsockname</tt>,
return convention WILL break old code;
<li> To enable local binding before connect, the <tt>bind</tt> method
does not call <tt>listen</tt> anymore. It is the new <tt>listen</tt>
method that turns a TCP object into a server object;
<li> <tt>socket.time</tt> changed to <tt>socket.gettime</tt> for uniformity;
<li> Interface to options has changed.
</ul>
<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=old>Old Versions</h2>
<p>
All previous versions of the LuaSocket library can be downloaded
<a href="http://www.tecgraf.puc-rio.br/luasocket/old">here</a>. Although
these versions are no longer supported, they are still available for
those that have compatibility issues.
</p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html#down">download</a> ·
<a href="introduction.html">introduction</a> ·
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Thu Jun 17 02:47:14 EDT 2004
</small>
</p>
</center>
</div>
</body>
</html>
|
