LuaSocket API documentation

Version: alpha

Functions

client:close()

client:close()

Closes the TCP object. The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications. No further operations (except for further calls to the close method) are allowed on a closed socket. 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 limited system resources. Garbage-collected objects are automatically closed before destruction, though.

PARAMETERS

None

client:dirty()

client:dirty()

Check the read buffer status. This is an internal method, any use is unlikely to be portable.

PARAMETERS

None

RETURNS

client:getfd()

client:getfd()

Returns the underlying socket descriptor or handle associated to the object. This is an internal method, any use is unlikely to be portable.

PARAMETERS

None

RETURNS

client:getoption()

client:getoption(option)

Gets options for the TCP object. See client:setoption for description of the option names and values.

PARAMETERS

RETURNS

client:getpeername()

client:getpeername()

Returns information about the remote side of a connected client object. It makes no sense to call this method on server objects.

PARAMETERS

None

RETURNS

client:getsockname()

client:getsockname()

Returns the local address information associated to the object.

PARAMETERS

None

RETURNS

client:getstats()

client:getstats()

Returns accounting information on the socket, useful for throttling of bandwidth.

PARAMETERS

None

RETURNS

client:receive()

client:receive([pattern],[prefix])

Reads data from a client object, according to the specified read pattern. Patterns follow the Lua file I/O format, and the difference in performance between patterns is negligible.

PARAMETERS

RETURNS

client:send()

client:send(data,[i],[j])

Sends data through client object. The optional arguments i and j work exactly like the standard string.sub Lua function to allow the selection of a substring to be sent. Output is not buffered. For small strings, it is always better to concatenate them in Lua (with the .. operator) and send the result in one call instead of calling the method several times.

PARAMETERS

RETURNS

client:setfd()

client:setfd(handle)

Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made

PARAMETERS

client:setoption()

client:setoption(option,[value])

Sets options for the TCP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.

PARAMETERS

RETURNS

client:setstats()

client:setstats(received,sent,age)

Resets accounting information on the socket, useful for throttling of bandwidth.

PARAMETERS

RETURNS

client:settimeout()

client:settimeout(value,[mode])

Changes the timeout values for the object. By default, all I/O operations are blocking. That is, any call to the methods send, receive, and accept will block indefinitely, until the operation completes. The settimeout method defines a limit on the amount of time the I/O methods can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code. There are two timeout modes and both can be used together for fine tuning. Although timeout values have millisecond precision in LuaSocket, 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 OS and to and from the Lua interpreter. Also, function that accept host names and perform automatic name resolution might be blocked by the resolver for longer than the specified timeout value.

PARAMETERS

client:shutdown()

client:shutdown(mode)

Shuts down part of a full-duplex connection.

PARAMETERS

RETURNS

connected:close()

connected:close()

Closes a UDP object. The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications. No further operations (except for further calls to the close method) are allowed on a closed socket. 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 limited system resources. Garbage-collected objects are automatically closed before destruction, though.

PARAMETERS

None

connected:getoption()

connected:getoption(option)

Gets an option value from the UDP object. See connected:setoption for description of the option names and values.

PARAMETERS

RETURNS

connected:getpeername()

connected:getpeername()

Retrieves information about the peer associated with a connected UDP object. It makes no sense to call this method on unconnected objects.

PARAMETERS

None

RETURNS

connected:getsockname()

connected:getsockname()

Returns the local address information associated to the object. UDP sockets are not bound to any address until the 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).

PARAMETERS

None

RETURNS

connected:receive()

connected:receive([size])

Receives a datagram from the UDP object. If the UDP object is connected, only datagrams coming from the peer are accepted. Otherwise, the returned datagram can come from any host.

PARAMETERS

RETURNS

connected:send()

connected:send(datagram)

Sends a datagram to the UDP peer of a connected object. In UDP, the send method never blocks and the only way it can fail is if the underlying transport layer refuses to send a message to the specified address (i.e. no interface accepts the address).

PARAMETERS

RETURNS

connected:setoption()

connected:setoption(option,[value])

Sets options for the UDP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.

PARAMETERS

RETURNS

connected:setpeername()

connected:setpeername("*")

Changes the peer of a UDP object. This method turns an unconnected UDP object into a connected UDP object or vice versa. For connected objects, outgoing datagrams will be sent to the specified peer, and datagrams received from other peers will be discarded by the OS. Connected UDP objects must use the send and receive methods instead of sendto and receivefrom. Since the address of the peer does not have to be passed to and from the OS, the use of connected UDP objects is recommended when the same peer is used for several transmissions and can result in up to 30% performance gains.

PARAMETERS

RETURNS

connected:settimeout()

connected:settimeout(value)

Changes the timeout values for the object. By default, the receive and receivefrom operations are blocking. That is, any call to the methods will block indefinitely, until data arrives. The settimeout function defines a limit on the amount of time the functions can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code. In UDP, the send and sendto methods never block (the datagram is just passed to the OS and the call returns immediately). Therefore, the settimeout method has no effect on them.

PARAMETERS

master:bind()

master:bind(address,port)

Binds a master object to address and port on the local host.

PARAMETERS

RETURNS

master:close()

master:close()

Closes the TCP object. The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications. No further operations (except for further calls to the close method) are allowed on a closed socket. 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 limited system resources. Garbage-collected objects are automatically closed before destruction, though.

PARAMETERS

None

master:connect()

master:connect(address,port)

Attempts to connect a master object to a remote host, transforming it into a client object. Client objects support methods send, receive, getsockname, getpeername, settimeout, and close. Note that the function socket.connect is available and is a shortcut for the creation of client sockets.

PARAMETERS

RETURNS

master:dirty()

master:dirty()

Check the read buffer status. This is an internal method, any use is unlikely to be portable.

PARAMETERS

None

RETURNS

master:getfd()

master:getfd()

Returns the underlying socket descriptor or handle associated to the object. This is an internal method, any use is unlikely to be portable.

PARAMETERS

None

RETURNS

master:getsockname()

master:getsockname()

Returns the local address information associated to the object.

PARAMETERS

None

RETURNS

master:getstats()

master:getstats()

Returns accounting information on the socket, useful for throttling of bandwidth.

PARAMETERS

None

RETURNS

master:listen()

master:listen(backlog)

Specifies the socket is willing to receive connections, transforming the object into a server object. Server objects support the accept, getsockname, setoption, settimeout, and close methods.

PARAMETERS

RETURNS

master:setfd()

master:setfd(handle)

Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made

PARAMETERS

master:setstats()

master:setstats(received,sent,age)

Resets accounting information on the socket, useful for throttling of bandwidth.

PARAMETERS

RETURNS

master:settimeout()

master:settimeout(value,[mode])

Changes the timeout values for the object. By default, all I/O operations are blocking. That is, any call to the methods send, receive, and accept will block indefinitely, until the operation completes. The settimeout method defines a limit on the amount of time the I/O methods can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code. There are two timeout modes and both can be used together for fine tuning. Although timeout values have millisecond precision in LuaSocket, 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 OS and to and from the Lua interpreter. Also, function that accept host names and perform automatic name resolution might be blocked by the resolver for longer than the specified timeout value.

PARAMETERS

server:accept()

server:accept()

Waits for a remote connection on the server object and returns a client object representing that connection. Calling socket.select with a server object in the recvt parameter before a call to accept does not guarantee accept will return immediately. Use the settimeout method or accept might block until another client shows up.

PARAMETERS

None

RETURNS

server:close()

server:close()

Closes the TCP object. The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications. No further operations (except for further calls to the close method) are allowed on a closed socket. 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 limited system resources. Garbage-collected objects are automatically closed before destruction, though.

PARAMETERS

None

server:dirty()

server:dirty()

Check the read buffer status. This is an internal method, any use is unlikely to be portable.

PARAMETERS

None

RETURNS

server:getfd()

server:getfd()

Returns the underlying socket descriptor or handle associated to the object. This is an internal method, any use is unlikely to be portable.

PARAMETERS

None

RETURNS

server:getoption()

server:getoption(option)

Gets options for the TCP object. See server:setoption for description of the option names and values.

PARAMETERS

RETURNS

server:getsockname()

server:getsockname()

Returns the local address information associated to the object.

PARAMETERS

None

RETURNS

server:getstats()

server:getstats()

Returns accounting information on the socket, useful for throttling of bandwidth.

PARAMETERS

None

RETURNS

server:setfd()

server:setfd(handle)

Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made

PARAMETERS

server:setoption()

server:setoption(option,[value])

Sets options for the TCP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.

PARAMETERS

RETURNS

server:setstats()

server:setstats(received,sent,age)

Resets accounting information on the socket, useful for throttling of bandwidth.

PARAMETERS

RETURNS

server:settimeout()

server:settimeout(value,[mode])

Changes the timeout values for the object. By default, all I/O operations are blocking. That is, any call to the methods send, receive, and accept will block indefinitely, until the operation completes. The settimeout method defines a limit on the amount of time the I/O methods can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code. There are two timeout modes and both can be used together for fine tuning. Although timeout values have millisecond precision in LuaSocket, 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 OS and to and from the Lua interpreter. Also, function that accept host names and perform automatic name resolution might be blocked by the resolver for longer than the specified timeout value.

PARAMETERS

socket.connect()

socket.connect(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.

PARAMETERS

RETURNS

socket.dns.getaddrinfo()

socket.dns.getaddrinfo(address)

This function converts a host name to IPv4 or IPv6 address. The supplied address can be an IPv4 or IPv6 address or host name. The function returns a table with all information returned by the resolver:

{
 [1] = {
    family = family-name-1,
    addr = address-1
  },
  ...
  [n] = {
    family = family-name-n,
    addr = address-n
  }
}

PARAMETERS

RETURNS

socket.dns.gethostname()

socket.dns.gethostname()

Returns the standard host name for the machine as a string.

PARAMETERS

None

RETURNS

socket.dns.getnameinfo()

socket.dns.getnameinfo(address)

This function converts an address to host name. The supplied address can be an IPv4 or IPv6 address or host name. The function returns a table with all information returned by the resolver:

{
  [1] = host-name-1,
  ...
  [n] = host-name-n,
}

PARAMETERS

RETURNS

socket.dns.tohostname()

socket.dns.tohostname(address)

This function converts from an IPv4 address to host name. The address can be an IPv4 address or a host name.

PARAMETERS

RETURNS

socket.dns.toip()

socket.dns.toip(address)

This function converts a host name to IPv4 address. The address can be an IP address or a host name.

PARAMETERS

RETURNS

socket.gettime()

socket.gettime()

Returns the time in seconds, relative to the system epoch (Unix epoch time since January 1, 1970 (UTC) or Windows file time since January 1, 1601 (UTC)). You should use the values returned by this function for relative measurements only.

PARAMETERS

None

RETURNS

EXAMPLES

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

socket.newtry()

socket.newtry(finalizer)

This function creates and returns a clean try function that allows for cleanup before the exception is raised. The finalizer function will be called in protected mode (see protect).

PARAMETERS

RETURNS

EXAMPLES

-- 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()

socket.protect()

socket.protect(func)

Converts a function that throws exceptions into a safe function. This function only catches exceptions thrown by try functions. It does not catch normal Lua errors. Beware that if your function performs some illegal operation that raises an error, the protected function will catch the error and return it as a string. This is because try functions uses errors as the mechanism to throw exceptions.

PARAMETERS

RETURNS

EXAMPLES

local dostuff = socket.protect(function()
    local try = socket.newtry()
    local c = try(socket.connect("myserver.com", 80))
    try = socket.newtry(function() c:close() end)
    try(c:send("hello?\r\n"))
    local answer = try(c:receive())
    c:close()
end)

local n, error = dostuff()

socket.select()

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

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 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. Recvt and sendt parameters can be empty tables or nil. Non-socket values (or values with non-numeric indices) in these arrays will be silently ignored. 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. This function 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. 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. 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. 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.)

PARAMETERS

RETURNS

socket.skip()

socket.skip(d,[ret1],[ret2],[retN])

This function drops a number of arguments and returns the remaining. It is useful to avoid creation of dummy variables: D is the number of arguments to drop. Ret1 to retN are the arguments. The function returns retD+1 to retN.

PARAMETERS

RETURNS

EXAMPLES

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

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

socket.sleep()

socket.sleep(time)

Freezes the program execution during a given amount of time.

PARAMETERS

socket.tcp()

socket.tcp()

Creates and returns an IPv4 TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.

PARAMETERS

None

RETURNS

socket.tcp6()

socket.tcp6()

Creates and returns an IPv6 TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method. Note: The TCP object returned will have the option "ipv6-v6only" set to true.

PARAMETERS

None

RETURNS

socket.udp()

socket.udp()

Creates and returns an unconnected IPv4 UDP object. Unconnected objects support the sendto, receive, receivefrom, getoption, getsockname, setoption, settimeout, setpeername, setsockname, and close methods. The setpeername method is used to connect the object.

PARAMETERS

None

RETURNS

socket.udp6()

socket.udp6()

Creates and returns an unconnected IPv6 UDP object. Unconnected objects support the sendto, receive, receivefrom, getoption, getsockname, setoption, settimeout, setpeername, setsockname, and close methods. The setpeername method is used to connect the object. Note: The UDP object returned will have the option "ipv6-v6only" set to true.

PARAMETERS

None

RETURNS

unconnected:close()

unconnected:close()

Closes a UDP object. The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications. No further operations (except for further calls to the close method) are allowed on a closed socket. 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 limited system resources. Garbage-collected objects are automatically closed before destruction, though.

PARAMETERS

None

unconnected:getoption()

unconnected:getoption(option)

Gets an option value from the UDP object. See unconnected:setoption for description of the option names and values.

PARAMETERS

RETURNS

unconnected:getsockname()

unconnected:getsockname()

Returns the local address information associated to the object. UDP sockets are not bound to any address until the 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).

PARAMETERS

None

RETURNS

unconnected:receive()

unconnected:receive([size])

Receives a datagram from the UDP object. If the UDP object is connected, only datagrams coming from the peer are accepted. Otherwise, the returned datagram can come from any host.

PARAMETERS

RETURNS

unconnected:receivefrom()

unconnected:receivefrom([size])

Works exactly as the receive method, except it returns the IP address and port as extra return values (and is therefore slightly less efficient).

PARAMETERS

RETURNS

unconnected:sendto()

unconnected:sendto(datagram,ip,port)

Sends a datagram to the specified IP address and port number. In UDP, the send method never blocks and the only way it can fail is if the underlying transport layer refuses to send a message to the specified address (i.e. no interface accepts the address).

PARAMETERS

RETURNS

unconnected:setoption()

unconnected:setoption(option,[value])

Sets options for the UDP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.

PARAMETERS

RETURNS

unconnected:setpeername()

unconnected:setpeername(address,port)

Changes the peer of a UDP object. This method turns an unconnected UDP object into a connected UDP object or vice versa. For connected objects, outgoing datagrams will be sent to the specified peer, and datagrams received from other peers will be discarded by the OS. Connected UDP objects must use the send and receive methods instead of sendto and receivefrom. Since the address of the peer does not have to be passed to and from the OS, the use of connected UDP objects is recommended when the same peer is used for several transmissions and can result in up to 30% performance gains.

PARAMETERS

RETURNS

unconnected:setsockname()

unconnected:setsockname(address,port)

Binds the UDP object to a local address. This method can only be called before any datagram is sent through the UDP object, and only once. Otherwise, the system automatically binds the object to all local interfaces and chooses an ephemeral port as soon as the first datagram is sent. After the local address is set, either automatically by the system or explicitly by setsockname, it cannot be changed.

PARAMETERS

RETURNS

unconnected:settimeout()

unconnected:settimeout(value)

Changes the timeout values for the object. By default, the receive and receivefrom operations are blocking. That is, any call to the methods will block indefinitely, until data arrives. The settimeout function defines a limit on the amount of time the functions can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code. In UDP, the send and sendto methods never block (the datagram is just passed to the OS and the call returns immediately). Therefore, the settimeout method has no effect on them.

PARAMETERS

Constants

socket._SETSIZE

This constant contains the maximum number of sockets that the select function can handle.

socket._VERSION

This constant has a string describing the current LuaSocket version.