LuaSocket: The socket namespace

The socket namespace

The socket namespace contains the core functionality of LuaSocket.

To obtain the socket namespace, run:

-- loads the socket module
local socket = require("socket")

socket.headers.canonic

The socket.headers.canonic table is used by the HTTP and SMTP modules to translate from lowercase field names back into their canonic capitalization. When a lowercase field name exists as a key in this table, the associated value is substituted in whenever the field name is sent out.

You can obtain the headers namespace if case run-time modifications are required by running:

-- loads the headers module
local headers = require("headers")

socket.bind(address, port [, backlog])

This function is a shortcut that creates and returns a TCP server object bound to a local address and port, ready to accept client connections. Optionally, user can also specify the backlog argument to the listen method (defaults to 32).

Note: The server object returned will have the option "reuseaddr" set to true.

socket.connect[46](address, port [, locaddr] [, locport] [, family])

This function is a shortcut that creates and returns a TCP client object connected to a remote address at a given port. Optionally, the user can also specify the local address and port to bind (locaddr and locport), or restrict the socket family to "inet" or "inet6". Without specifying family to connect, whether a tcp or tcp6 connection is created depends on your system configuration. Two variations of connect are defined as simple helper functions that restrict the family, socket.connect4 and socket.connect6.

socket._DEBUG

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

socket._DATAGRAMSIZE

Default datagram size used by calls to receive and receivefrom. (Unless changed in compile time, the value is 8192.)

socket.gettime()

Returns the UNIX time in seconds. You should subtract the values returned by this function to get meaningful values.

t = socket.gettime()
-- do stuff
print(socket.gettime() - t .. " seconds elapsed")

socket.newtry(finalizer)

Creates and returns a clean try function that allows for cleanup before the exception is raised. This implements the ideas described in LTN012, Using finalized exceptions.

Finalizer is a function that will be called before try throws the exception.

The function returns your customized try function.

Note: This idea saved a lot of work with the implementation of protocols in LuaSocket:

foo = socket.protect(function()
    -- connect somewhere
    local c = socket.try(socket.connect("somewhere", 42))
    -- create a try function that closes 'c' on error
    local try = socket.newtry(function() c:close() end)
    -- do everything reassured c will be closed
    try(c:send("hello there?\r\n"))
    local answer = try(c:receive())
    ...
    try(c:send("good bye\r\n"))
    c:close()
end)

socket.protect(func)

Converts a function that throws exceptions into a safe function. This function only catches exceptions thrown by the try and newtry functions. It does not catch normal Lua errors. This implements the ideas described in LTN012, Using finalized exceptions.

Func is a function that calls try (or assert, or error) to throw exceptions.

Returns an equivalent function that instead of throwing exceptions in case of a failed try call, 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 (or values with non-numeric indices) in the arrays will be silently ignored.

The function returns a list with the sockets ready for reading, a list with the sockets ready for writing and an error message. The error message is "timeout" if a timeout condition was met, "select failed" if the call to select failed, and nil otherwise. The returned tables are doubly keyed both by integers and also by the sockets themselves, to simplify the test if a specific socket has changed status.

Note: select can monitor a limited number of sockets, as defined by the constant socket._SETSIZE. This number may be as high as 1024 or as low as 64 by default, depending on the system. It is usually possible to change this at compile time. Invoking select with a larger number of sockets will raise an error.

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.

Another 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 settimeout method or accept might block forever.

Yet another note: If you close a socket and pass it to select, it will be ignored.

Using select with non-socket objects: Any object that implements getfd and dirty can be used with select, allowing objects from other libraries to be used within a socket.select driven loop.

socket._SETSIZE

The maximum number of sockets that the select function can handle.

socket.sink(mode, socket)

Creates an LTN12 sink from a stream socket object.

Mode defines the behavior 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.skip(d [, ret₁, ret₂ ... ret_N])

Drops a number of arguments and returns the remaining.

D is the number of arguments to drop. Ret₁ to ret_N are the arguments.

The function returns ret_d+1 to ret_N.

Note: This function is useful to avoid creation of dummy variables:

-- get the status code and separator from SMTP server reply
local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))

socket.sleep(time)

Freezes the program execution during a given amount of time.

Time is the number of seconds to sleep for. If time is negative, the function returns immediately.

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

Creates an LTN12 source from a stream socket object.

Mode defines the behavior 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._SOCKETINVALID

The OS value for an invalid socket. This can be used with tcp:getfd and tcp:setfd methods.

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

Throws an exception in case ret₁ is falsy, using ret₂ as the error message. The exception is supposed to be caught by a protected function only. This implements the ideas described in LTN012, Using finalized exceptions.

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

The function returns ret₁ to ret_N if ret₁ is not nil or false. Otherwise, it calls error passing ret₂ wrapped in a table with metatable used by protect to distinguish exceptions from runtime errors.

-- 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.