LuaSocket: Network support for the Lua language

What is LuaSocket?

LuaSocket is a Lua extension library that is composed by two parts: a C layer that provides support for the TCP and UDP transport layers, and a set of Lua modules that add support for the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and downloading files) protocols and other functionality commonly needed by applications that deal with the Internet.

Network support has been implemented so that it is both efficient and simple to use. LuaSocket can be used by any Lua application once it has been properly linked with and initialized by the interpreter running the Lua application. The code has been tested and runs well on several Windows and Unix platforms.

The library is available under the same terms and conditions 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.

Download

LuaSocket version 2.0 alpha is now available for download! It is compatible with Lua 5.0 and has been tested on Windows XP, Linux, and Mac OS X.

The library can be downloaded in source code from the following links:

luasocket-2.0-alpha.tar.gz
luasocket-2.0-alpha.zip

Besides the full C and Lua source code for the library, the distribution contains several examples, this user's manual and the test procedures.

I am also providing a Windows binary for those that want to give LuaSocket a quick try:

luasocket-2.0.exe

This binary has been compiled with the LUASOCKET_DEBUG option, and should be able to run the automatic test procedures.

Special thanks

Throughout LuaSocket its history, many people gave sugestions that helped improve it. For that, I thank the Lua comunity. Special thanks go to David Burgess, who has pushed the library to a new level of quality and from whom I have learned a lot 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.

What's New

Most of the 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:

Major C code rewrite. Code is modular and extensible. Hopefully, next versions will include code for local domain sockets, file descriptors, pipes (on Unix) and named pipes (on windows) as a bonus;
Following the Lua 5.0 trend, all functions provided by the library are in the namespace socket. 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;
All functions return a non-nil value as first return value if successful. All functions return whatever could be retrieved followed by error message in case of error. The best way to check for errors is to check for the presence of an error message;
UDP connected sockets can break association with peer by calling setpeername with address '*';
TCP has been changed to become more uniform. First create an object, then connect or bind if needed, and finally use I/O functions. The socket.connect and socket.bind functions are still provided for simplicity, but they just call socket.tcp followed by the connect or bind methods;
Better error messages and parameter checking;
socket.sleep and socket.time 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;
Socket options interface has been improved and TCP objects also support socket options.

Incompatibilities with previous versions

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 (http, smtp etc) have been moved to the namespace (i.e. socket.http, socket.smtp etc);
WARNING: The new send, sendto, setpeername and setsockname, ftp.put, ftp.put_cb return convention WILL break old code;
Interface to options has changed;
socket.select refuses tables that have anything that is not an object from the group select{able}. This includes even the 'n' field. Silently ignoring objects was a source of bugs for Lua programs.

Old Versions

All previous versions of the LuaSocket library can be downloaded here. Although these versions are no longer supported, they are still available for those that have compatibility issues.