![]() |
IPv4 Sockets support for the Lua language |
home · download · what is · introduction · functions · modules · index
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.
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.
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.
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.
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.
Returns the local IP address and port of the TCP socket or nil in case of error.
receive(socket [, pattern1, pattern2, ... patternN])
Receives pattern1, pattern2, ... patternN from the client socket. A pattern can be one of the following:
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:
send(socket, string1 [, string2, ... stringN])-- 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
Sends the strings string1, string2, ... stringN 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:
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.
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.
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.
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.
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").
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.
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.
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.
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:
The supported options and their expected value types are:options = { ["option-1-name"] = value-1, ["option-2-name"] = value-2, ["option-3-name"] = value-3, ... ... ["option-n-name"] = value-n }
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:
Note that the alias list can be empty.resolved = { ["name"] = "canonic-name", ["alias"] = alias-list, ["ip"] = ip-address-list }
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.
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
![]() | and | ![]() |
Last modified by Diego Nehab on Thu Sep 27 16:18:27 EST 2001 |