LuaSocket: TCP/IP support for the Lua language

To connect to a server, a client application creates a client socket object with a call to the function connect. Once this object is created, the user can use the functions send and receive to exchange information with the server. After all data exchange is done, the client application can close the connection by calling the close function on the client socket.

On the server side, a server application binds to an address with a call to the bind function, which returns a server socket object. The server application can then accept remote connections on the server socket, with calls to the accept function. This function returns a client socket, through which the server application can communicate with the client application that attempted connection. Both server and client sockets can be closed with the close function.

All functions are available both as stand-alone functions and as methods of the socket objects. For example, the function call send(socket,"test") is equivalent to the function call socket:send("test"), where socket is a client socket.

Returns a client socket object, representing a client attempting connection on the server socket socket. The function blocks until a connection attempt is detected.

bind(address, port [, backlog])

Binds to the address address and port port on the local host. Address can be an IP address or a host name. The optional parameter backlog (default value 1) specifies the number of client connections that can be queued waiting for service. If the queue is full and another client attempts connection, the connection is refused. In case of success, the function returns a server socket, on which the operations accept, close and listen are permitted. In case of error, the function returns nil followed by a string describing the error.

close(socket)

Closes the socket socket. No further operations are allowed on a closed socket. In case socket is a server socket, the address to which it is bound is made available to other applications. It is important to close all used sockets once they are not needed, since, in many systems, each socket uses a file descriptor, which is a limited system resource.

connect(address, port)

Attempts connection to address address and port port. Address can be an IP address or a host name. In case of success, the function returns a client socket on which the operations send, receive and close are permitted. In case of error, the function returns nil followed by a string describing the error.

listen(socket, backlog)

Changes the backlog parameter of the server socket socket.

send(socket, string₁ [, string₂, ... string_N])

Sends the strings string₁, string₂, ... string_N through the client socket socket. The function returns an error code, which is nil in case of success, the string `closed' in case the connection was closed before the transmission was complete or the string `timeout' in case there was a timeout during the operation. After the error code, the function returns the number of bytes accepted by the transport layer.

receive(socket [, pattern₁, pattern₂, ... pattern_N])

Receives pattern₁, pattern₂, ... pattern_N from the client socket socket. A pattern can be one of the following:

• `*l': causes the function to read a line of text from the socket. The line is terminated by a LF character (ASCII~10), optionally preceeded by a CR character (ASCII~13). The CR and LF characters are not returned. This is the default pattern.
• `*lu': causes the function to read a line of text from the socket. The line is assumed to be terminated by a single LF character. If the LF character is is preceeded by a CR character, the CR character is returned in the string, whereas the LF character is not.
• number: causes the function to read number raw bytes from the socket. This is the fastest pattern and should be used whenever possible.

timeout(socket, value [, mode])

Changes the timeout values for the socket socket. By default, all I/O operations are blocking. That is, any call to the functions send and receive will block indefinetely, until the operation completes. The timeout function defines a limit on the ammount of time the functions can block, specified as the value parameter, in seconds. There are two timeout modes, which can be used together:

• `b': blocked timeout. Specifies the upper limit on the ammount of time LuaSocket can be blocked by the operational system waiting for completion of any I/O operation.
• `r': return timeout. Specifies the upper limit on the ammount of time LuaSocket can block a Lua script while performing an I/O operation.