luasocket/doc/index.html

315 lines
9.8 KiB
HTML
Raw Normal View History

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> &middot;
<a href="home.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<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 &copy; 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&nbsp;5.0 and has been tested on
Windows&nbsp;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\&gt; 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\&gt; lua
Lua 5.0.2 Copyright (C) 1994-2004 Tecgraf, PUC-Rio
&gt; http = require"http"
&gt; print(http.request"http://www.tecgraf.puc-rio.br/luasocket/")
--&gt; this file
</pre>
<!-- 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.
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.
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>
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> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Thu Jun 17 02:47:14 EDT 2004
2003-08-31 03:00:15 +02:00
</small>
</p>
</center>
</div>
</body>
</html>