LuaSocket: Network support for the Lua language

What is LuaSocket?

LuaSocket is a Lua 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.

The core support has been implemented so that it is both efficient and simple to use. It is available to any Lua application once it has been properly initialized by the interpreter in use. The code has been tested and runs well on several Windows and Unix platforms.

Among the support modules, the most commonly used implement the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and downloading files) client protocols. These provide a very natural and generic interface to the functionality defined by each protocol. In addition, you will find that the MIME (common encodings), URL (anything you could possible want to do with one) and LTN12 (filters, sinks, sources and pumps) modules can be very handy.

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 (final) 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 LuaSocket project page at LuaForge. Besides the full C and Lua source code for the library, the distribution contains several examples, this user's manual and basic test procedures.

Danilo Tuler is maintaining Win32 binaries for LuaSocket, which are also available from LuaForge. These are compatible with the LuaBinaries available from LuaForge.

For those that want to give LuaSocket a quick try, download the stand-alone archive and unpack everything into a directory, say c:\luasocket. Then set LUA_INIT to load the compat-5.1.lua and set LUA_PATH and LUA_CPATH to look for files in the current directory:

c:\luasocket\> set LUA_INIT=@c:\luasocket\compat-5.1.lua
c:\luasocket\> set LUA_CPATH=?.dll
c:\luasocket\> set LUA_PATH=?.lua

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:

c:\luasocket\> lua50
Lua 5.0.2  Copyright (C) 1994-2004 Tecgraf, PUC-Rio
> http = require"socket.http"
> print(http.request"http://www.cs.princeton.edu/~diego/professional/luasocket/")
--> the source to this web page gets dumped to terminal

When you are done playing, take a look at the installation section of the manual to find out how to properly install the library.

Special thanks

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. Recently, Mike Pall has been helping a lot too! Thanks to you all!

What's New

There is no big change for the 2.0 (final) release. It is basically a bug fix release. The only improvement is in the non-blocking support.

New: sample module dispatch.lua implements a coroutine based dispatcher;
New: sample check-links.lua works both in blocking and non-blocking mode using coroutines (using the new dispatcher);
New: sample forward.lua implements a coroutine based forward server (using the new dispatcher);
Improved: tcp:send(data, i, j) to return (i+sent-1). This is great for non-blocking I/O, but might break some code;
Improved: HTTP, SMTP, and FTP functions to accept a new field create that overrides the function used to create socket objects;
Improved: smtp.message now supports multipart/alternative (for the HTML messages we all love so much);
Fixed: smtp.send was hanging on errors returned by LTN12 sources;
Fixed: url.absolute() to work when base_url is in parsed form;
Fixed: http.request() not to redirect when the location header is empty (naughty servers...);
Fixed: tcp{client}:shutdown() to check for class instead of group;
Fixed: The manual to stop using socket.try() in place of assert(), since it can't;
Improved: Got rid of package.loaded.base = _G kludge;
Fixed: Parts of the manual referred to require("http") instead of require("socket.http");
Improved: Socket and MIME binaries are called 'core' each inside their directory (ex. "socket/core.dll"). The 'l' prefix was just a bad idea;
Improved: Using bundles in Mac OS X, instead of dylibs;
Fixed: luasocket.h to export luaopen_socket_core;
Fixed: udp:setpeername() so you can "disconnect" an UDP socket;
Fixed: A weird bug in HTTP support that caused some requests to fail (Florian Berger);
Fixed: Bug in socket.select() that caused sockets with descriptor 0 to be ignored (Renato Maia);
Fixed: "Bug" that caused dns.toip() to crash under uLinux (William Trenker);
Fixed: "Bug" that caused gethostbyname to crash under VMS (Renato Maia);
Fixed: tcp:send("") to return 0 bytes sent (Alexander Marinov);
Improved: socket.DEBUG and socket.VERSION became socket._DEBUGs and socket._VERSION for uniformity with other libraries;
Improved: socket.select now works on empty sets on Windows.

Incompatibilities with previous versions

If you use the return value of tcp:send() and you use the extra parameters to select only part of the string to be sent, your code is now broken, but when you fix it, it will be much simpler;
If you check socket.DEBUG or socket.VERSION, change it to socket._DEBUG or socket._VERSION.

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.