LuaSocket: IPv4 Sockets support for the Lua language

IPv4 Sockets support for the Lua language

home · download · what is · introduction · functions · modules · index

Function Reference

All the functions of the API are described below. Several examples are given in the distribution, including the automated tests and the full implementation of the protocols FTP, SMTP and HTTP.

Note that although some function names are overloaded, documentation is provided separately for TCP and UDP sockets.

TCP sockets

accept(socket)

Waits for a TCP client to attempt connection with the server socket, and returns a client socket object connected to the remote end. If a timeout condition is met, the function returns nil followed by the string 'timeout'.

bind(address, port [, backlog])

Creates a new TCP server socket and binds it to (address, port) on the local host. Address can be an IP address or a host name. If address is '*', the system binds to all local interfaces (INADDR_ANY). If port is 0, the system automatically chooses an ephemeral port. 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, getsockname 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. The local address to which socket was bound is made available to other applications. No further operations (except for further calls to close) are allowed on a closed socket.

Note: It is important to close all used sockets once they are not needed, since, in many systems, each socket uses a file descriptor, which are a limited system resource.

connect(address, port)

Creates a new TCP client socket and tries to connect to (address, 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 close, getsockname, getpeername, receive, send and timeout are permitted. In case of error, the function returns nil followed by a string describing the error.

getpeername(socket)

Returns the IP address and port of the peer connected to the TCP client socket or nil in case of error. Note that it makes no sense to call getpeername on a server socket object.

getsockname(socket)

Returns the local IP address and port of the TCP socket or nil in case of error.

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

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

'*a': reads from the socket until the connection is closed. No end-of-line translation is performed;
'*l': reads a line of text from the socket. The line is terminated by a LF character (ASCII 10), optionally preceded by a CR character (ASCII 13). The CR and LF characters are not returned. This is the default pattern;
'*lu': reads 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 preceded by a CR character, the CR character is returned in the string, whereas the LF character is not;
'*w': reads a word (maximal sequence of non-white-space characters), skipping leading spaces if necessary;
number: causes the function to read number raw bytes from the socket.

The function returns one value for each pattern, followed by a single error code that can be nil in case of success, the string 'closed' in case the connection was closed before the transmission was completed or the string 'timeout' in case there was a timeout during the operation. The difference in performance between all patterns is negligible.

Note: In case of error, the function always return everything it managed to download before the error condition was met.

select(receive, send [, timeout])

Waits for a number of sockets to change status. Receive is a table with the sockets to test for characters available for reading. Sockets in the send table 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. Receive and send can also be empty tables or nil. Non-socket values in the tables will be silently ignored (that way you can have a handy field named "n").

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.

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

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

Examples:

-- waits for input on three sockets and broadcasts any received lines
server = bind("localhost", 8080)
a = server:accept(); b = server:accept(); c = server:accept()
a:timeout(1); b:timeout(1); c:timeout(1)
while 1 do
  r, _, e = select({a,b,c}, nil)
  for i,v in r do
    l, e = v:receive()
    if e then exit() end
    _, s, e = select(nil, {a,b,c}, 1)
    for j,u in s do
      e = u:send(l, "\n") 
      if e then exit() end
    end
  end
end

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

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 indefinitely, until the operation completes. The timeout function defines a limit on the amount of time the functions can block, specified as the value parameter, in seconds. There are two timeout modes and both can be used together for fine tuning:

'b': blocked timeout. Specifies the upper limit on the amount of time LuaSocket can be blocked by the operating system while waiting for completion of any single I/O operation;
'r': return timeout. Specifies the upper limit on the amount of time LuaSocket can block a Lua script before returning a function call.

The nil timeout value allows operations to block indefinitely. Negative timeout values have the same effect.

Note: although timeout values have millisecond precision, large blocks can cause I/O functions not to respect timeout values due to the time the library takes to transfer blocks to and from the kernel and to and from the Lua interpreter.

UDP sockets

close(socket)

Closes the socket socket. The local address to which it is bound is made available to other applications. No further operations are allowed on a closed socket.

Note: It is important to close all used sockets once they are not needed, since, in many systems, each socket uses a file descriptor, which are a limited system resource.

getpeername(socket)

Returns the IP address and port of the peer of the UDP socket. The function will fail unless a peer has been set with a call to setpeername.

getsockname(socket)

Returns the local IP address and port of the TCP socket or nil in case of error.

Note: UDP sockets are not bound to any address until setsockname or the sendto method is called for the first time (in which case it is bound to an ephemeral port and the wild-card address). The local address cannot be changed thereafter.

receive(socket [, number])

Receives a datagram from the UDP socket socket with up to number bytes. If there are more than number bytes available in the datagram, the remaining are discarded. If there are less then number bytes available in the current datagram, the available bytes are returned. If number is omitted, the maximum datagram size is used. In case of timeout, the function returns nil followed by the string 'timeout'. In case the transmission failed, the function returns nil followed by the string 'refused'.

receivefrom(socket [, number])

Works exactly as the receive function, except it returns the sender ip and port as extra return values and is therefore slightly less efficient.

select(receive, send [, timeout])

Waits for a number of sockets to change status. Receive is a table with the sockets to test for characters available for reading. OK Sockets in the send table are watched to see if it is 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. Receive and send can also be empty tables or nil. Non-socket values in the tables will be silently ignored (that way you can have a handy field named "n").

send(socket, string)

Sends string to the UDP peer of socket socket. The method setpeername MUST have been called on socket. If successful, the function returns nil. In case of timeout, the function returns the string 'timeout'. In case the transmission failed, the function returns the string 'refused'.

sendto(socket, string, ip, port)

Sends string to (ip, port). In case of timeout, the function returns the string 'timeout'. Ip MUST be an IP address, for performance reasons. In case the transmission failed, the function returns the string 'refused'.

setpeername(socket, address, port)

Sets the socket UDP peer to (address, port). Address can be an IP address or a host name. After a call to setpeername, the send and receive MUST be used instead of sendto and receivefrom. Outgoing datagrams will be sent to the specified peer, and datagrams received from other peers will be discarded by the OS. Since the address of the peer does not have to be passed to and from the OS, this practice is recommended when the same peer is used for several transmissions and can lead to up to 30% performance gains.

setsockname(socket, address, port)

Binds the UDP socket to a local address (address, port). Address can be an IP address or a host name. If address is '*' the system binds to all local interfaces (INADDR_ANY). If port is 0, the system chooses an ephemeral port. If successful, the function returns nil. In case of error, the function returns an error message.

timeout(socket, value)

Changes the timeout value for the socket socket. By default, all operations are blocking. The timeout function defines a limit on the amount of time the functions can block, specified as the value parameter, in seconds. A nil or negative timeout value allows operations to block indefinitely.

Note: there is no send buffer on an UDP socket. Therefore, a send operation on an UDP socket should never block, regardless of the timeout value. Receive operations, however, can block the application.

udpsocket([options])

Creates and returns an UDP socket object, on which the methods close, getpeername, getsockname, receive, receivefrom, send, sendto, setpeername, setsockname and timeout can be used. In case of error, the function returns nil and an error message.

The table options allows users to specify non-default socket options at socket creation time. The table must be in the format:

options = {
  ["option-1-name"] = value-1,
  ["option-2-name"] = value-2,
  ["option-3-name"] = value-3,
         ...            ...
  ["option-n-name"] = value-n
}

The supported options and their expected value types are:

SO_KEEPALIVE: a number
SO_DONTROUTE: a number
SO_BROADCAST: a number
SO_LINGER: a table in the format {l_onoff = number, l_linger = number}.

Note: UDP socket options should only be used by advanced users.

DNS Services

The following functions can be used to convert between host names and IP addresses. All information returned by the resolver is returned by these functions, as a table in the form:

resolved = {
  ["name"] = "canonic-name",
  ["alias"] = alias-list,
  ["ip"] = ip-address-list
}

Note that the alias list can be empty.

tohostname(address)

Returns a string with the canonic host name of given address, followed by a table with all information returned by the resolver. Address can be an IP address or host name. In case of error, the function returns nil followed by an error message.

toip(address)

Returns a string with the first IP address found for address, followed by a table with all information returned by the resolver. Address can be an IP address or host name. In case of error, the function returns nil followed by an error message.

home · download · what is · introduction · functions · modules · index

Created with Vim and Best Viewed on Any Browser
Last modified by Diego Nehab on
Thu Sep 27 16:18:27 EST 2001

	and
Last modified by Diego Nehab on Thu Sep 27 16:18:27 EST 2001