LuaSocket: Network support for the Lua language

The socket namespace

The socket namespace contains the namespace tables for all LuaSocket modules as well as function that didn't belong in any specific module, functions that are so commonly used that deserve a shortcut and a few constants.

socket.debug

This constant is set to true if the library was compiled with debug support.

socket.protect(function)

Converts a function that throws exceptions into a safe function.

Function is a function that calls try to throw exceptions.

The function an equivalent function that instead of throwing exceptoins, returns nil followed by an error message.

socket.select(recvt, sendt [, timeout])

Waits for a number of sockets to change status.

Recvt is an array with the sockets to test for characters available for reading. Sockets in the sendt array are watched to see if it is OK to immediately write on them. Timeout is the maximum amount of time (in seconds) to wait for a change in status. A nil, negative or omitted timeout value allows the function to block indefinitely. Recvt and sendt can also be empty tables or nil. Non-socket values in the arrays will be silently ignored.

The function returns a table with the sockets ready for reading, a table with the sockets ready for writing and an error message. The error message is "timeout" if a timeout condition was met and nil otherwise. The returned tables are associative, to simplify the test if a specific socket has changed status.

Important Note: a known bug in WinSock causes select to fail on non-blocking TCP sockets. The function may return a socket as writable even though the socket is not ready for sending.

Important note: calling select with a server socket in the receive parameter before a call to accept does not guarantee accept will return immediately. Use the timeout method or accept might block forever.

Interesting note: as mentioned in some manuals, calling select with both sets empty and a non-null timeout is a fairly portable way to sleep with sub-second precision.

socket.sink(mode, socket)

Creates an LTN012 sink from a stream socket object.

Mode defines the behaviour of the sink. The following options are available:

"http-chunked": sends data through socket after applying the chunked transfer coding, closing the socket when done;
"close-when-done": sends all received data through the socket, closing the socket when done;
"keep-open": sends all received data through the socket, leaving it open when done.

Socket is the stream socket object used to send the data.

The function returns a sink with the appropriate behavior.

socket.source(mode, socket [, length])

Creates an LTN012 source from a stream socket object.

Mode defines the behaviour of the source. The following options are available:

"http-chunked": receives data from socket and removes the chunked transfer coding before returning the data;
"by-length": receives a fixed number of bytes from the socket. This mode requires the extra argument length;
"until-closed": receives data from a socket until the other side closes the connection.

Socket is the stream socket object used to receive the data.

The function returns a source with the appropriate behavior.

socket.try(ret₁, ret₂ ... ret_N)

Throws an exception in case of error.

Ret₁, ret₂ ... ret_N can be arbitrary arguments, but are usually the return values of a function call that nested with the call to try.

The function returns ret₁, ret₂ ... ret_N if ret₁ is not nil. Otherwise, calls error passing ret₂.

-- connects or throws an exception with the appropriate error message
c = socket.try(socket.connect("localhost", 80))

socket.version

This constant has a string describing the current LuaSocket version.