2003-08-31 03:00:15 +02:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
|
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<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 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
|
2004-06-16 06:28:21 +02:00
|
|
|
that is composed by two parts: a C core that provides support for the TCP
|
2003-08-31 03:00:15 +02:00
|
|
|
and UDP transport layers, and a set of Lua modules that add support for
|
2004-06-16 06:28:21 +02:00
|
|
|
functionality commonly needed by applications that deal with the Internet.
|
2003-08-31 03:00:15 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2004-06-16 06:28:21 +02:00
|
|
|
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
|
2004-06-16 01:00:56 +02:00
|
|
|
been properly initialized by the interpreter running the
|
2003-08-31 03:00:15 +02:00
|
|
|
Lua application. The code has been tested and runs well on several Windows
|
|
|
|
|
and Unix platforms.
|
|
|
|
|
</p>
|
|
|
|
|
|
2004-06-16 06:28:21 +02:00
|
|
|
<p>
|
2004-06-16 22:41:03 +02:00
|
|
|
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
|
2004-06-16 06:28:21 +02:00
|
|
|
protocols. These provide a very natural and generic interface to the e
|
|
|
|
|
functionality covered by the protocols.
|
2004-06-16 22:41:03 +02:00
|
|
|
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.
|
2004-06-16 06:28:21 +02:00
|
|
|
</p>
|
|
|
|
|
|
2003-08-31 03:00:15 +02:00
|
|
|
<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>
|
2004-06-16 01:00:56 +02:00
|
|
|
Copyright © 1999-2004 Tecgraf/PUC-Rio. All rights reserved. <br>
|
2003-08-31 03:00:15 +02:00
|
|
|
Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
2004-01-20 21:24:51 +01:00
|
|
|
<h2 id=download>Download</h2>
|
2003-08-31 03:00:15 +02:00
|
|
|
|
|
|
|
|
<p>
|
2004-06-16 01:00:56 +02:00
|
|
|
LuaSocket version 2.0 beta is now available for download! It is
|
2003-08-31 03:00:15 +02:00
|
|
|
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>
|
2004-06-16 01:00:56 +02:00
|
|
|
<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>
|
2003-08-31 03:00:15 +02:00
|
|
|
</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>
|
2004-06-18 23:41:51 +02:00
|
|
|
I am also providing PC Win32 binaries for those that want to give
|
2003-08-31 03:00:15 +02:00
|
|
|
LuaSocket a quick try:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
<p>
|
2004-06-18 23:41:51 +02:00
|
|
|
<a href="luasocket-2.0-beta-win32.zip">luasocket-2.0-beta-win32.zip</a>
|
2003-08-31 03:00:15 +02:00
|
|
|
</p>
|
|
|
|
|
</blockquote>
|
|
|
|
|
|
|
|
|
|
<p>
|
2004-06-18 23:41:51 +02:00
|
|
|
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:
|
2003-08-31 03:00:15 +02:00
|
|
|
</p>
|
|
|
|
|
|
2004-06-18 23:41:51 +02:00
|
|
|
<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>
|
|
|
|
|
|
2004-02-04 15:29:11 +01:00
|
|
|
<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<h2 id=thanks>Special thanks</h2>
|
|
|
|
|
|
|
|
|
|
<p>
|
2004-06-16 06:28:21 +02:00
|
|
|
Throughout LuaSocket's history, many people gave suggestions that helped
|
|
|
|
|
improve it. For that, I thank the Lua community.
|
2004-02-04 15:29:11 +01:00
|
|
|
Special thanks go to
|
2004-06-16 06:28:21 +02:00
|
|
|
David Burgess, who has helped push the library to a new level of quality and
|
2004-06-16 01:00:56 +02:00
|
|
|
from whom I have learned a lot of stuff that doesn't show up in RFCs.
|
2004-02-04 15:29:11 +01:00
|
|
|
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>
|
|
|
|
|
|
2003-08-31 03:00:15 +02:00
|
|
|
<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<h2 id=new>What's New</h2>
|
|
|
|
|
|
2004-02-04 15:29:11 +01:00
|
|
|
|
2003-08-31 03:00:15 +02:00
|
|
|
<p>
|
2004-06-16 06:28:21 +02:00
|
|
|
<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
|
2003-08-31 03:00:15 +02:00
|
|
|
that made the interface simpler and more consistent. Here are some of
|
|
|
|
|
the changes that made it into version 2.0:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2004-06-16 06:28:21 +02:00
|
|
|
<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;
|
2003-08-31 03:00:15 +02:00
|
|
|
|
2004-06-16 06:28:21 +02:00
|
|
|
<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
|
2003-08-31 03:00:15 +02:00
|
|
|
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.
|
2004-06-16 01:00:56 +02:00
|
|
|
All functions return <b><tt>nil</tt></b> followed by error message
|
2004-06-16 06:28:21 +02:00
|
|
|
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;
|
2003-08-31 03:00:15 +02:00
|
|
|
|
2004-06-16 01:00:56 +02:00
|
|
|
<li> Better error messages and parameter checking;
|
|
|
|
|
|
|
|
|
|
<li> Should be interrupt safe;
|
|
|
|
|
|
|
|
|
|
<li> UDP connected sockets can break association with peer by calling
|
2003-08-31 03:00:15 +02:00
|
|
|
<tt>setpeername</tt> with address '<tt>*</tt>';
|
|
|
|
|
|
2004-06-16 06:28:21 +02:00
|
|
|
<li> Sets returned by <tt>socket.select</tt> are associative;
|
2004-06-16 01:00:56 +02:00
|
|
|
|
2004-06-16 06:28:21 +02:00
|
|
|
<li> Select checks if sockets have buffered data and returns immediately;
|
2003-08-31 03:00:15 +02:00
|
|
|
|
|
|
|
|
<li> <tt>socket.sleep</tt> and <tt>socket.time</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;
|
|
|
|
|
|
2004-06-16 01:00:56 +02:00
|
|
|
<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
|
2004-06-16 06:28:21 +02:00
|
|
|
support socket options and many new options were added.
|
2004-06-16 01:00:56 +02:00
|
|
|
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>
|
2004-06-16 03:02:14 +02:00
|
|
|
Lots of changes in the Lua modules, too!
|
2004-06-16 01:00:56 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2004-06-16 06:28:21 +02:00
|
|
|
<li> Every module loads only the modules that it needs. There is no waste
|
|
|
|
|
of memory. LuaSocket core takes only 20k of memory;
|
|
|
|
|
|
2004-06-16 03:02:14 +02:00
|
|
|
<li> New MIME and LTN12 modules make all other modules much more powerful;
|
2004-06-16 06:28:21 +02:00
|
|
|
|
2004-06-16 03:02:14 +02:00
|
|
|
<li> Support for multipart messages in the SMTP module;
|
2004-06-16 06:28:21 +02:00
|
|
|
|
|
|
|
|
<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;
|
|
|
|
|
|
2004-06-16 03:02:14 +02:00
|
|
|
<li> FTP, HTTP, and SMTP are implemented in multiple levels in such a way
|
2004-06-16 06:28:21 +02:00
|
|
|
that users will have no problems extending the functionality to satisfy
|
|
|
|
|
personal needs;
|
|
|
|
|
|
|
|
|
|
<li> SMTP knows how to perform LOGIN and PLAIN authentication.
|
|
|
|
|
|
2003-08-31 03:00:15 +02:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
|
|
|
|
|
|
<h3 id=incompatible>Incompatibilities with previous versions</h3>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2004-06-16 01:00:56 +02:00
|
|
|
|
2003-08-31 03:00:15 +02:00
|
|
|
<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>
|
2004-06-16 06:28:21 +02:00
|
|
|
etc) are independent now and should be "<tt>require</tt>"d;
|
2004-06-16 01:00:56 +02:00
|
|
|
|
|
|
|
|
<li> FTP, SMTP and HTTP are completely new; I am sure you will
|
|
|
|
|
agree the new stuff is better;
|
2003-08-31 03:00:15 +02:00
|
|
|
|
2004-06-16 01:00:56 +02:00
|
|
|
<li> WARNING: The new <tt>send</tt>, <tt><b>receive</b></tt>,
|
2003-08-31 03:00:15 +02:00
|
|
|
<tt>sendto</tt>, <tt>setpeername</tt> and <tt>setsockname</tt>,
|
2004-06-16 01:00:56 +02:00
|
|
|
return convention WILL break old code;
|
2003-08-31 03:00:15 +02:00
|
|
|
|
2004-06-16 03:02:14 +02:00
|
|
|
<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> Interface to options has changed.
|
2003-08-31 03:00:15 +02:00
|
|
|
|
|
|
|
|
</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>
|
2004-06-17 09:00:43 +02:00
|
|
|
Thu Jun 17 02:47:14 EDT 2004
|
2003-08-31 03:00:15 +02:00
|
|
|
</small>
|
|
|
|
|
</p>
|
|
|
|
|
</center>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
