2004-05-25 08:52:06 +02:00
< !DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
< html >
< head >
2004-06-21 08:07:58 +02:00
< meta name = "description" content = "LuaSocket: The core namespace" >
2004-11-28 09:17:16 +01:00
< meta name = "keywords" content = "Lua, LuaSocket, Socket, Network, Library, Support" >
2004-06-21 08:07:58 +02:00
< title > LuaSocket: The socket namespace< / title >
2004-05-25 08:52:06 +02:00
< link rel = "stylesheet" href = "reference.css" type = "text/css" >
< / head >
< body >
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< div class = header >
< hr >
< center >
< table summary = "LuaSocket logo" >
< tr > < td align = center > < a href = "http://www.lua.org" >
2004-06-21 08:07:58 +02:00
< img width = 128 height = 128 border = 0 alt = "LuaSocket" src = "luasocket.png" >
2004-05-25 08:52:06 +02:00
< / a > < / td > < / tr >
< tr > < td align = center valign = top > Network support for the Lua language
< / td > < / tr >
< / table >
< p class = bar >
2009-05-27 11:31:38 +02:00
< a href = "index.html" > home< / a > ·
< a href = "index.html#download" > download< / a > ·
2004-12-13 07:26:01 +01:00
< a href = "installation.html" > installation< / a > ·
2004-05-25 08:52:06 +02:00
< a href = "introduction.html" > introduction< / a > ·
< a href = "reference.html" > reference< / a >
< / p >
< / center >
< hr >
< / div >
<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
2004-05-26 06:58:32 +02:00
< h2 id = socket > The socket namespace< / h2 >
2004-05-25 08:52:06 +02:00
< p >
2004-06-15 08:24:00 +02:00
The < tt > socket< / tt > namespace contains the core functionality of LuaSocket.
2004-05-25 08:52:06 +02:00
< / p >
2004-06-16 22:41:03 +02:00
< p >
To obtain the < tt > socket< / tt > namespace, run:
< / p >
< pre class = example >
-- loads the socket module
local socket = require("socket")
< / pre >
2016-03-04 19:36:32 +01:00
<!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = "headers.canonic" >
socket.headers.< b > canonic< / b > < / p >
< p > The < tt > socket.headers.canonic< / tt > 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.
< / p >
< p >
You can obtain the < tt > headers< / tt > namespace if case run-time
modifications are required by running:
< / p >
< pre class = example >
-- loads the headers module
local headers = require("headers")
< / pre >
2004-06-21 00:19:54 +02:00
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = bind >
socket.< b > bind(< / b > address, port [, backlog]< b > )< / b >
< / p >
< p class = description >
2004-06-21 08:07:58 +02:00
This function is a shortcut that creates and returns a TCP server object
bound to a local < tt > address< / tt > and < tt > port< / tt > , ready to
accept client connections. Optionally,
user can also specify the < tt > backlog< / tt > argument to the
< a href = tcp.html#listen > < tt > listen< / tt > < / a > method (defaults to 32).
< / p >
< p class = note >
Note: The server object returned will have the option "< tt > reuseaddr< / tt > "
set to < tt > < b > true< / b > < / tt > .
2004-06-21 00:19:54 +02:00
< / p >
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = connect >
2012-05-10 23:14:22 +02:00
socket.< b > connect[46](< / b > address, port [, locaddr] [, locport] [, family]< b > )< / b >
2004-06-21 00:19:54 +02:00
< / p >
< p class = description >
2004-06-21 08:07:58 +02:00
This function is a shortcut that creates and returns a TCP client object
2012-05-10 23:14:22 +02:00
connected to a remote < tt > address< / tt > at a given < tt > port< / tt > . Optionally,
2004-06-21 08:07:58 +02:00
the user can also specify the local address and port to bind
2012-05-10 23:14:22 +02:00
(< tt > locaddr< / tt > and < tt > locport< / tt > ), or restrict the socket family
to "< tt > inet< / tt > " or "< tt > inet6< / tt > ".
Without specifying < tt > family< / tt > to < tt > connect< / tt > , 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
< tt > family< / tt > , < tt > socket.connect4< / tt > and < tt > socket.connect6< / tt > .
2004-06-21 00:19:54 +02:00
< / p >
2004-06-16 22:41:03 +02:00
2004-05-25 08:52:06 +02:00
<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
2015-10-06 05:33:50 +02:00
< p class = name id = debug >
2005-06-14 06:29:23 +02:00
socket.< b > _DEBUG< / b >
2004-05-25 08:52:06 +02:00
< / p >
< p class = description >
This constant is set to < tt > < b > true< / b > < / tt > if the library was compiled
with debug support.
< / p >
2015-10-06 05:33:50 +02:00
<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = debug >
socket.< b > _DATAGRAMSIZE< / b >
< / p >
< p class = description >
Default datagram size used by calls to
< a href = "udp.html#receive" < tt > receive< / tt > < / a > and
< a href = "udp.html#receivefrom" > < tt > receivefrom< / tt > < / a > .
(Unless changed in compile time, the value is 8192.)
< / p >
2009-05-27 11:31:38 +02:00
<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = gettime >
socket.< b > gettime()< / b >
< / p >
< p class = description >
2013-11-08 01:13:36 +01:00
Returns the UNIX time in seconds. You should subtract the values returned by this function
2009-05-27 11:31:38 +02:00
to get meaningful values.
< / p >
< pre class = example >
t = socket.gettime()
-- do stuff
print(socket.gettime() - t .. " seconds elapsed")
< / pre >
2004-06-18 23:41:51 +02:00
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = newtry >
socket.< b > newtry(< / b > finalizer< b > )< / b >
< / p >
< p class = description >
Creates and returns a < em > clean< / em >
< a href = "#try" > < tt > try< / tt > < / a >
function that allows for cleanup before the exception
is raised.
< / p >
< p class = parameters >
< tt > Finalizer< / tt > is a function that will be called before
2016-02-24 00:48:43 +01:00
< tt > try< / tt > throws the exception.
2004-06-18 23:41:51 +02:00
< / p >
< p class = return >
The function returns your customized < tt > try< / tt > function.
< / p >
< p class = note >
Note: This idea saved a < em > lot< / em > of work with the
implementation of protocols in LuaSocket:
< / p >
< pre class = example >
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
2004-12-13 07:26:01 +01:00
try(c:send("hello there?\r\n"))
2004-06-18 23:41:51 +02:00
local answer = try(c:receive())
...
try(c:send("good bye\r\n"))
c:close()
end)
< / pre >
2004-05-25 08:52:06 +02:00
<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = protect >
2004-06-15 08:24:00 +02:00
socket.< b > protect(< / b > func< b > )< / b >
2004-05-25 08:52:06 +02:00
< / p >
< p class = description >
2005-02-08 11:01:01 +01:00
Converts a function that throws exceptions into a safe function. This
function only catches exceptions thrown by the < a href = #try > < tt > try< / tt > < / a >
and < a href = #newtry > < tt > newtry< / tt > < / a > functions. It does not catch normal
Lua errors.
2004-05-25 08:52:06 +02:00
< / p >
< p class = parameters >
2004-06-16 22:41:03 +02:00
< tt > Func< / tt > is a function that calls
< a href = #try > < tt > try< / tt > < / a > (or < tt > assert< / tt > , or < tt > error< / tt > )
to throw exceptions.
2004-05-25 08:52:06 +02:00
< / p >
< p class = return >
2016-02-24 06:59:37 +01:00
Returns an equivalent function that instead of throwing exceptions in case of
a failed < a href = #try > < tt > try< / tt > < / a > call, returns < tt > < b > nil< / b > < / tt >
followed by an error message.
2004-05-25 08:52:06 +02:00
< / p >
2004-05-26 06:58:32 +02:00
<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = select >
socket.< b > select(< / b > recvt, sendt [, timeout]< b > )< / b >
< / p >
< p class = description >
Waits for a number of sockets to change status.
< / p >
< p class = parameters >
< tt > Recvt< / tt > is an array with the sockets to test for characters
available for reading. Sockets in the < tt > sendt< / tt > array are watched to
see if it is OK to immediately write on them. < tt > Timeout< / tt > is the
maximum amount of time (in seconds) to wait for a change in status. A
< tt > < b > nil< / b > < / tt > , negative or omitted < tt > timeout< / tt > value allows the
function to block indefinitely. < tt > Recvt< / tt > and < tt > sendt< / tt > can also
2004-06-16 22:41:03 +02:00
be empty tables or < tt > < b > nil< / b > < / tt > . Non-socket values (or values with
non-numeric indices) in the arrays will be silently ignored.
2004-05-26 06:58:32 +02:00
< / p >
2007-06-12 01:44:54 +02:00
< p class = return > The function returns a list with the sockets ready for
reading, a list with the sockets ready for writing and an error message.
2016-03-04 18:38:56 +01:00
The error message is "< tt > timeout< / tt > " if a timeout
condition was met, "< tt > select failed< / tt > " if the call
to < tt > select< / tt > failed, and
2007-06-12 01:44:54 +02:00
< tt > < b > nil< / b > < / tt > 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.
2004-05-26 06:58:32 +02:00
< / p >
2009-05-27 11:31:38 +02:00
< p class = note >
2016-03-04 18:38:56 +01:00
< b > Note:< / b > < tt > select< / tt > can monitor a limited number
2009-05-27 11:31:38 +02:00
of sockets, as defined by the constant < tt > socket._SETSIZE< / tt > . 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 < tt > select< / tt > with a larger
number of sockets will raise an error.
< / p >
2004-05-26 06:58:32 +02:00
< p class = note >
2004-06-15 08:24:00 +02:00
< b > Important note< / b > : a known bug in WinSock causes < tt > select< / tt > to fail
2004-05-26 06:58:32 +02:00
on non-blocking TCP sockets. The function may return a socket as
writable even though the socket is < em > not< / em > ready for sending.
< / p >
< p class = note >
2004-06-16 03:02:14 +02:00
< b > Another important note< / b > : calling select with a server socket in the receive parameter before a call to accept does < em > not< / em > guarantee
2004-05-26 06:58:32 +02:00
< a href = tcp.html#accept > < tt > accept< / tt > < / a > will return immediately.
2004-06-15 08:24:00 +02:00
Use the < a href = tcp.html#settimeout > < tt > settimeout< / tt > < / a >
2004-05-26 06:58:32 +02:00
method or < tt > accept< / tt > might block forever.
< / p >
2006-04-14 04:04:38 +02:00
< p class = note >
< b > Yet another note< / b > : If you close a socket and pass
it to < tt > select< / tt > , it will be ignored.
< / p >
2011-10-24 20:24:58 +02:00
< p class = note >
< b > Using select with non-socket objects< / b > : Any object that implements < tt > getfd< / tt > and < tt > dirty< / tt > can be used with < tt > select< / tt > , allowing objects from other libraries to be used within a < tt > socket.select< / tt > driven loop.
< / p >
2016-03-04 19:36:32 +01:00
<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = setsize >
socket.< b > _SETSIZE< / b >
< / p >
< p class = description >
The maximum number of sockets that the < a
href=#select>< tt > select< / tt > < / a > function can handle.
< / p >
2004-05-26 06:58:32 +02:00
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = sink >
socket.< b > sink(< / b > mode, socket< b > )< / b >
< / p >
< p class = description >
Creates an
2004-06-15 08:24:00 +02:00
< a href = "http://lua-users.org/wiki/FiltersSourcesAndSinks" > LTN12< / a >
2004-05-26 06:58:32 +02:00
sink from a stream socket object.
< / p >
< p class = parameters >
2005-11-21 08:04:44 +01:00
< tt > Mode< / tt > defines the behavior of the sink. The following
2004-05-26 06:58:32 +02:00
options are available:
< / p >
< ul >
< li > < tt > "http-chunked"< / tt > : sends data through socket after applying the
< em > chunked transfer coding< / em > , closing the socket when done;
< li > < tt > "close-when-done"< / tt > : sends all received data through the
socket, closing the socket when done;
< li > < tt > "keep-open"< / tt > : sends all received data through the
socket, leaving it open when done.
< / ul >
< p >
< tt > Socket< / tt > is the stream socket object used to send the data.
< / p >
< p class = return >
The function returns a sink with the appropriate behavior.
< / p >
2004-06-18 10:02:09 +02:00
<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = skip >
socket.< b > skip(< / b > d [, ret< sub > 1< / sub > , ret< sub > 2< / sub > ... ret< sub > N< / sub > ]< b > )< / b >
< / p >
< p class = description >
Drops a number of arguments and returns the remaining.
< / p >
< p class = parameters >
< tt > D< / tt > is the number of arguments to drop. < tt > Ret< sub > 1< / sub > < / tt > to
< tt > ret< sub > N< / sub > < / tt > are the arguments.
< / p >
< p class = return >
The function returns < tt > ret< sub > d+1< / sub > < / tt > to < tt > ret< sub > N< / sub > < / tt > .
< / p >
< p class = note >
Note: This function is useful to avoid creation of dummy variables:
< / p >
< pre class = example >
-- get the status code and separator from SMTP server reply
local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
< / pre >
<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = sleep >
socket.< b > sleep(< / b > time< b > )< / b >
< / p >
< p class = description >
Freezes the program execution during a given amount of time.
< / p >
< p class = parameters >
2009-05-27 11:31:38 +02:00
< tt > Time< / tt > is the number of seconds to sleep for. If
< tt > time< / tt > is negative, the function returns immediately.
2004-06-18 10:02:09 +02:00
< / p >
2004-05-26 06:58:32 +02:00
<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = source >
socket.< b > source(< / b > mode, socket [, length]< b > )< / b >
< / p >
< p class = description >
Creates an
2004-06-15 08:24:00 +02:00
< a href = "http://lua-users.org/wiki/FiltersSourcesAndSinks" > LTN12< / a >
2004-05-26 06:58:32 +02:00
source from a stream socket object.
< / p >
< p class = parameters >
2004-06-16 06:28:21 +02:00
< tt > Mode< / tt > defines the behavior of the source. The following
2004-05-26 06:58:32 +02:00
options are available:
< / p >
< ul >
< li > < tt > "http-chunked"< / tt > : receives data from socket and removes the
< em > chunked transfer coding< / em > before returning the data;
< li > < tt > "by-length"< / tt > : receives a fixed number of bytes from the
socket. This mode requires the extra argument < tt > length< / tt > ;
< li > < tt > "until-closed"< / tt > : receives data from a socket until the other
side closes the connection.
< / ul >
< p >
< tt > Socket< / tt > is the stream socket object used to receive the data.
< / p >
< p class = return >
The function returns a source with the appropriate behavior.
< / p >
2015-10-06 05:33:50 +02:00
<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< p class = name id = socketinvalid >
socket.< b > _SOCKETINVALID< / b >
< / p >
< p class = description >
The OS value for an invalid socket.
< / p >
2004-05-26 06:58:32 +02:00
<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
2004-05-25 08:52:06 +02:00
< p class = name id = try >
2004-06-16 22:41:03 +02:00
socket.< b > try(< / b > ret< sub > 1< / sub > [, ret< sub > 2< / sub > ... ret< sub > N< / sub > ]< b > )< / b >
2004-05-25 08:52:06 +02:00
< / p >
< p class = description >
2016-02-24 06:59:37 +01:00
Throws an exception in case < tt > ret< sub > 1< / sub > < / tt > is falsy, using
< tt > ret< sub > 2< / sub > < / tt > as the error message. The exception is supposed to be caught
by a < a href = #protect > < tt > protect< / tt > < / a > ed function only.
2004-05-25 08:52:06 +02:00
< / p >
< p class = parameters >
2004-06-18 10:02:09 +02:00
< tt > Ret< sub > 1< / sub > < / tt > to < tt > ret< sub > N< / sub > < / tt > can be arbitrary
2004-06-16 22:41:03 +02:00
arguments, but are usually the return values of a function call
nested with < tt > try< / tt > .
2004-05-25 08:52:06 +02:00
< / p >
< p class = return >
2004-06-16 22:41:03 +02:00
The function returns < tt > ret< / tt > < sub > 1< / sub > to < tt > ret< / tt > < sub > N< / sub > if
2016-02-16 09:44:02 +01:00
< tt > ret< / tt > < sub > 1< / sub > is not < tt > < b > nil< / b > < / tt > or < tt > < b > false< / b > < / tt > .
Otherwise, it calls < tt > error< / tt > passing < tt > ret< / tt > < sub > 2< / sub > wrapped
in a table with metatable used by < a href = #protect > < tt > protect< / tt > < / a > to
distinguish exceptions from runtime errors.
2004-05-25 08:52:06 +02:00
< / p >
< pre class = example >
-- connects or throws an exception with the appropriate error message
c = socket.try(socket.connect("localhost", 80))
< / pre >
2004-06-16 22:41:03 +02:00
<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
2004-05-25 08:52:06 +02:00
2005-08-12 07:56:32 +02:00
< p class = name id = version >
2005-06-14 06:29:23 +02:00
socket.< b > _VERSION< / b >
2004-05-25 08:52:06 +02:00
< / p >
< p class = description >
This constant has a string describing the current LuaSocket version.
< / p >
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
< div class = footer >
< hr >
< center >
< p class = bar >
2009-05-27 11:31:38 +02:00
< a href = "index.html" > home< / a > ·
< a href = "index.html#down" > download< / a > ·
2004-12-13 07:26:01 +01:00
< a href = "installation.html" > installation< / a > ·
2004-05-25 08:52:06 +02:00
< a href = "introduction.html" > introduction< / a > ·
< a href = "reference.html" > reference< / a >
< / p >
< p >
< small >
Last modified by Diego Nehab on < br >
2006-04-20 06:27:13 +02:00
Thu Apr 20 00:25:54 EDT 2006
2004-05-25 08:52:06 +02:00
< / small >
< / p >
< / center >
< / div >
< / body >
< / html >
