mirror of
https://github.com/lunarmodules/luasocket.git
synced 2024-11-16 02:08:21 +01:00
Added gettimeout for completeness.
Also documented. Rordered manuals so order is alphabetical.
This commit is contained in:
Diego Nehab
parent
cdce73b226
commit
944305dc21
@ -72,34 +72,6 @@ local mime = require("mime")
|
|||||||
|
|
||||||
<h3 id=high>High-level filters</h3>
|
<h3 id=high>High-level filters</h3>
|
||||||
|
|
||||||
<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="normalize">
|
|
||||||
mime.<b>normalize(</b>[marker]<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Converts most common end-of-line markers to a specific given marker.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=parameters>
|
|
||||||
<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
|
|
||||||
end-of-line marker defined by the MIME standard.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
The function returns a filter that performs the conversion.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: There is no perfect solution to this problem. Different end-of-line
|
|
||||||
markers are an evil that will probably plague developers forever.
|
|
||||||
This function, however, will work perfectly for text created with any of
|
|
||||||
the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
|
|
||||||
or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
|
|
||||||
markers, the function will still work well, although it doesn't
|
|
||||||
guarantee that the number of empty lines will be correct.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
@ -159,6 +131,35 @@ base64 = ltn12.filter.chain(
|
|||||||
)
|
)
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
|
<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="normalize">
|
||||||
|
mime.<b>normalize(</b>[marker]<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Converts most common end-of-line markers to a specific given marker.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=parameters>
|
||||||
|
<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
|
||||||
|
end-of-line marker defined by the MIME standard.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The function returns a filter that performs the conversion.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: There is no perfect solution to this problem. Different end-of-line
|
||||||
|
markers are an evil that will probably plague developers forever.
|
||||||
|
This function, however, will work perfectly for text created with any of
|
||||||
|
the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
|
||||||
|
or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
|
||||||
|
markers, the function will still work well, although it doesn't
|
||||||
|
guarantee that the number of empty lines will be correct.
|
||||||
|
</p>
|
||||||
|
|
||||||
<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id="stuff">
|
<p class=name id="stuff">
|
||||||
@ -466,7 +467,7 @@ marker.
|
|||||||
<p>
|
<p>
|
||||||
<small>
|
<small>
|
||||||
Last modified by Diego Nehab on <br>
|
Last modified by Diego Nehab on <br>
|
||||||
Thu Apr 20 00:25:44 EDT 2006
|
Fri Mar 4 15:19:17 BRT 2016
|
||||||
</small>
|
</small>
|
||||||
</p>
|
</p>
|
||||||
</center>
|
</center>
|
||||||
|
|||||||
@ -187,6 +187,7 @@ Support, Manual">
|
|||||||
<a href="tcp.html#getpeername">getpeername</a>,
|
<a href="tcp.html#getpeername">getpeername</a>,
|
||||||
<a href="tcp.html#getsockname">getsockname</a>,
|
<a href="tcp.html#getsockname">getsockname</a>,
|
||||||
<a href="tcp.html#getstats">getstats</a>,
|
<a href="tcp.html#getstats">getstats</a>,
|
||||||
|
<a href="tcp.html#gettimeout">gettimeout</a>,
|
||||||
<a href="tcp.html#listen">listen</a>,
|
<a href="tcp.html#listen">listen</a>,
|
||||||
<a href="tcp.html#receive">receive</a>,
|
<a href="tcp.html#receive">receive</a>,
|
||||||
<a href="tcp.html#send">send</a>,
|
<a href="tcp.html#send">send</a>,
|
||||||
@ -207,6 +208,7 @@ Support, Manual">
|
|||||||
<a href="udp.html#getoption">getoption</a>,
|
<a href="udp.html#getoption">getoption</a>,
|
||||||
<a href="udp.html#getpeername">getpeername</a>,
|
<a href="udp.html#getpeername">getpeername</a>,
|
||||||
<a href="udp.html#getsockname">getsockname</a>,
|
<a href="udp.html#getsockname">getsockname</a>,
|
||||||
|
<a href="udp.html#gettimeout">gettimeout</a>,
|
||||||
<a href="udp.html#receive">receive</a>,
|
<a href="udp.html#receive">receive</a>,
|
||||||
<a href="udp.html#receivefrom">receivefrom</a>,
|
<a href="udp.html#receivefrom">receivefrom</a>,
|
||||||
<a href="udp.html#send">send</a>,
|
<a href="udp.html#send">send</a>,
|
||||||
|
|||||||
235
doc/smtp.html
235
doc/smtp.html
@ -114,6 +114,124 @@ the SMTP module:
|
|||||||
<li> <tt>ZONE</tt>: default time zone.
|
<li> <tt>ZONE</tt>: default time zone.
|
||||||
</ul>
|
</ul>
|
||||||
|
|
||||||
|
<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id=message>
|
||||||
|
smtp.<b>message(</b>mesgt<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Returns a <em>simple</em>
|
||||||
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=parameters>
|
||||||
|
The only parameter of the function is a table describing the message.
|
||||||
|
<tt>Mesgt</tt> has the following form (notice the recursive structure):
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<blockquote>
|
||||||
|
<table summary="Mesgt table structure">
|
||||||
|
<tr><td><tt>
|
||||||
|
mesgt = {<br>
|
||||||
|
headers = <i>header-table</i>,<br>
|
||||||
|
body = <i>LTN12 source</i> or <i>string</i> or
|
||||||
|
<i>multipart-mesgt</i><br>
|
||||||
|
}<br>
|
||||||
|
<br>
|
||||||
|
multipart-mesgt = {<br>
|
||||||
|
[preamble = <i>string</i>,]<br>
|
||||||
|
[1] = <i>mesgt</i>,<br>
|
||||||
|
[2] = <i>mesgt</i>,<br>
|
||||||
|
...<br>
|
||||||
|
[<i>n</i>] = <i>mesgt</i>,<br>
|
||||||
|
[epilogue = <i>string</i>,]<br>
|
||||||
|
}<br>
|
||||||
|
</tt></td></tr>
|
||||||
|
</table>
|
||||||
|
</blockquote>
|
||||||
|
|
||||||
|
<p class=parameters>
|
||||||
|
For a simple message, all that is needed is a set of <tt>headers</tt>
|
||||||
|
and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
|
||||||
|
or as a <em>simple</em>
|
||||||
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||||
|
source. For multipart messages, the body is a table that
|
||||||
|
recursively defines each part as an independent message, plus an optional
|
||||||
|
<tt>preamble</tt> and <tt>epilogue</tt>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The function returns a <em>simple</em>
|
||||||
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
||||||
|
source that produces the
|
||||||
|
message contents as defined by <tt>mesgt</tt>, chunk by chunk.
|
||||||
|
Hopefully, the following
|
||||||
|
example will make things clear. When in doubt, refer to the appropriate RFC
|
||||||
|
as listed in the introduction. </p>
|
||||||
|
|
||||||
|
<pre class=example>
|
||||||
|
-- load the smtp support and its friends
|
||||||
|
local smtp = require("socket.smtp")
|
||||||
|
local mime = require("mime")
|
||||||
|
local ltn12 = require("ltn12")
|
||||||
|
|
||||||
|
-- creates a source to send a message with two parts. The first part is
|
||||||
|
-- plain text, the second part is a PNG image, encoded as base64.
|
||||||
|
source = smtp.message{
|
||||||
|
headers = {
|
||||||
|
-- Remember that headers are *ignored* by smtp.send.
|
||||||
|
from = "Sicrano de Oliveira <sicrano@example.com>",
|
||||||
|
to = "Fulano da Silva <fulano@example.com>",
|
||||||
|
subject = "Here is a message with attachments"
|
||||||
|
},
|
||||||
|
body = {
|
||||||
|
preamble = "If your client doesn't understand attachments, \r\n" ..
|
||||||
|
"it will still display the preamble and the epilogue.\r\n" ..
|
||||||
|
"Preamble will probably appear even in a MIME enabled client.",
|
||||||
|
-- first part: no headers means plain text, us-ascii.
|
||||||
|
-- The mime.eol low-level filter normalizes end-of-line markers.
|
||||||
|
[1] = {
|
||||||
|
body = mime.eol(0, [[
|
||||||
|
Lines in a message body should always end with CRLF.
|
||||||
|
The smtp module will *NOT* perform translation. However, the
|
||||||
|
send function *DOES* perform SMTP stuffing, whereas the message
|
||||||
|
function does *NOT*.
|
||||||
|
]])
|
||||||
|
},
|
||||||
|
-- second part: headers describe content to be a png image,
|
||||||
|
-- sent under the base64 transfer content encoding.
|
||||||
|
-- notice that nothing happens until the message is actually sent.
|
||||||
|
-- small chunks are loaded into memory right before transmission and
|
||||||
|
-- translation happens on the fly.
|
||||||
|
[2] = {
|
||||||
|
headers = {
|
||||||
|
["content-type"] = 'image/png; name="image.png"',
|
||||||
|
["content-disposition"] = 'attachment; filename="image.png"',
|
||||||
|
["content-description"] = 'a beautiful image',
|
||||||
|
["content-transfer-encoding"] = "BASE64"
|
||||||
|
},
|
||||||
|
body = ltn12.source.chain(
|
||||||
|
ltn12.source.file(io.open("image.png", "rb")),
|
||||||
|
ltn12.filter.chain(
|
||||||
|
mime.encode("base64"),
|
||||||
|
mime.wrap()
|
||||||
|
)
|
||||||
|
)
|
||||||
|
},
|
||||||
|
epilogue = "This might also show up, but after the attachments"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
-- finally send it
|
||||||
|
r, e = smtp.send{
|
||||||
|
from = "<sicrano@example.com>",
|
||||||
|
rcpt = "<fulano@example.com>",
|
||||||
|
source = source,
|
||||||
|
}
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
|
||||||
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id=send>
|
<p class=name id=send>
|
||||||
@ -275,123 +393,6 @@ r, e = smtp.send{
|
|||||||
}
|
}
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id=message>
|
|
||||||
smtp.<b>message(</b>mesgt<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Returns a <em>simple</em>
|
|
||||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=parameters>
|
|
||||||
The only parameter of the function is a table describing the message.
|
|
||||||
<tt>Mesgt</tt> has the following form (notice the recursive structure):
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<blockquote>
|
|
||||||
<table summary="Mesgt table structure">
|
|
||||||
<tr><td><tt>
|
|
||||||
mesgt = {<br>
|
|
||||||
headers = <i>header-table</i>,<br>
|
|
||||||
body = <i>LTN12 source</i> or <i>string</i> or
|
|
||||||
<i>multipart-mesgt</i><br>
|
|
||||||
}<br>
|
|
||||||
<br>
|
|
||||||
multipart-mesgt = {<br>
|
|
||||||
[preamble = <i>string</i>,]<br>
|
|
||||||
[1] = <i>mesgt</i>,<br>
|
|
||||||
[2] = <i>mesgt</i>,<br>
|
|
||||||
...<br>
|
|
||||||
[<i>n</i>] = <i>mesgt</i>,<br>
|
|
||||||
[epilogue = <i>string</i>,]<br>
|
|
||||||
}<br>
|
|
||||||
</tt></td></tr>
|
|
||||||
</table>
|
|
||||||
</blockquote>
|
|
||||||
|
|
||||||
<p class=parameters>
|
|
||||||
For a simple message, all that is needed is a set of <tt>headers</tt>
|
|
||||||
and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
|
|
||||||
or as a <em>simple</em>
|
|
||||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
||||||
source. For multipart messages, the body is a table that
|
|
||||||
recursively defines each part as an independent message, plus an optional
|
|
||||||
<tt>preamble</tt> and <tt>epilogue</tt>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
The function returns a <em>simple</em>
|
|
||||||
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
||||||
source that produces the
|
|
||||||
message contents as defined by <tt>mesgt</tt>, chunk by chunk.
|
|
||||||
Hopefully, the following
|
|
||||||
example will make things clear. When in doubt, refer to the appropriate RFC
|
|
||||||
as listed in the introduction. </p>
|
|
||||||
|
|
||||||
<pre class=example>
|
|
||||||
-- load the smtp support and its friends
|
|
||||||
local smtp = require("socket.smtp")
|
|
||||||
local mime = require("mime")
|
|
||||||
local ltn12 = require("ltn12")
|
|
||||||
|
|
||||||
-- creates a source to send a message with two parts. The first part is
|
|
||||||
-- plain text, the second part is a PNG image, encoded as base64.
|
|
||||||
source = smtp.message{
|
|
||||||
headers = {
|
|
||||||
-- Remember that headers are *ignored* by smtp.send.
|
|
||||||
from = "Sicrano de Oliveira <sicrano@example.com>",
|
|
||||||
to = "Fulano da Silva <fulano@example.com>",
|
|
||||||
subject = "Here is a message with attachments"
|
|
||||||
},
|
|
||||||
body = {
|
|
||||||
preamble = "If your client doesn't understand attachments, \r\n" ..
|
|
||||||
"it will still display the preamble and the epilogue.\r\n" ..
|
|
||||||
"Preamble will probably appear even in a MIME enabled client.",
|
|
||||||
-- first part: no headers means plain text, us-ascii.
|
|
||||||
-- The mime.eol low-level filter normalizes end-of-line markers.
|
|
||||||
[1] = {
|
|
||||||
body = mime.eol(0, [[
|
|
||||||
Lines in a message body should always end with CRLF.
|
|
||||||
The smtp module will *NOT* perform translation. However, the
|
|
||||||
send function *DOES* perform SMTP stuffing, whereas the message
|
|
||||||
function does *NOT*.
|
|
||||||
]])
|
|
||||||
},
|
|
||||||
-- second part: headers describe content to be a png image,
|
|
||||||
-- sent under the base64 transfer content encoding.
|
|
||||||
-- notice that nothing happens until the message is actually sent.
|
|
||||||
-- small chunks are loaded into memory right before transmission and
|
|
||||||
-- translation happens on the fly.
|
|
||||||
[2] = {
|
|
||||||
headers = {
|
|
||||||
["content-type"] = 'image/png; name="image.png"',
|
|
||||||
["content-disposition"] = 'attachment; filename="image.png"',
|
|
||||||
["content-description"] = 'a beautiful image',
|
|
||||||
["content-transfer-encoding"] = "BASE64"
|
|
||||||
},
|
|
||||||
body = ltn12.source.chain(
|
|
||||||
ltn12.source.file(io.open("image.png", "rb")),
|
|
||||||
ltn12.filter.chain(
|
|
||||||
mime.encode("base64"),
|
|
||||||
mime.wrap()
|
|
||||||
)
|
|
||||||
)
|
|
||||||
},
|
|
||||||
epilogue = "This might also show up, but after the attachments"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
-- finally send it
|
|
||||||
r, e = smtp.send{
|
|
||||||
from = "<sicrano@example.com>",
|
|
||||||
rcpt = "<fulano@example.com>",
|
|
||||||
source = source,
|
|
||||||
}
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<div class=footer>
|
<div class=footer>
|
||||||
|
|||||||
@ -51,6 +51,30 @@ To obtain the <tt>socket</tt> namespace, run:
|
|||||||
local socket = require("socket")
|
local socket = require("socket")
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
|
<!-- 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>
|
||||||
|
|
||||||
|
|
||||||
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id=bind>
|
<p class=name id=bind>
|
||||||
@ -129,29 +153,6 @@ t = socket.gettime()
|
|||||||
print(socket.gettime() - t .. " seconds elapsed")
|
print(socket.gettime() - t .. " seconds elapsed")
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
<!-- socket.headers ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<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>
|
|
||||||
|
|
||||||
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id=newtry>
|
<p class=name id=newtry>
|
||||||
@ -283,6 +284,18 @@ it to <tt>select</tt>, it will be ignored.
|
|||||||
<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.
|
<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>
|
</p>
|
||||||
|
|
||||||
|
<!-- 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>
|
||||||
|
|
||||||
|
|
||||||
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id=sink>
|
<p class=name id=sink>
|
||||||
@ -390,17 +403,6 @@ side closes the connection.
|
|||||||
The function returns a source with the appropriate behavior.
|
The function returns a source with the appropriate behavior.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<!-- 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>
|
|
||||||
|
|
||||||
<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id=socketinvalid>
|
<p class=name id=socketinvalid>
|
||||||
|
|||||||
315
doc/tcp.html
315
doc/tcp.html
@ -38,84 +38,6 @@
|
|||||||
|
|
||||||
<h2 id="tcp">TCP</h2>
|
<h2 id="tcp">TCP</h2>
|
||||||
|
|
||||||
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="socket.tcp">
|
|
||||||
socket.<b>tcp()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Creates and returns an TCP master object. A master object can
|
|
||||||
be transformed into a server object with the method
|
|
||||||
<a href=#listen><tt>listen</tt></a> (after a call to <a
|
|
||||||
href=#bind><tt>bind</tt></a>) or into a client object with
|
|
||||||
the method <a href=#connect><tt>connect</tt></a>. The only other
|
|
||||||
method supported by a master object is the
|
|
||||||
<a href=#close><tt>close</tt></a> method.</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
In case of success, a new master object is returned. In case of error,
|
|
||||||
<b><tt>nil</tt></b> is returned, followed by an error message.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: The choice between IPv4 and IPv6 happens during a call to
|
|
||||||
<a href=#bind><tt>bind</tt></a> or <a
|
|
||||||
href=#bind><tt>connect</tt></a>, depending on the address
|
|
||||||
family obtained from the resolver.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: Before the choice between IPv4 and IPv6 happens,
|
|
||||||
the internal socket object is invalid and therefore <a
|
|
||||||
href=#setoption><tt>setoption</tt></a> will fail.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="socket.tcp4">
|
|
||||||
socket.<b>tcp4()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Creates and returns an IPv4 TCP master object. A master object can
|
|
||||||
be transformed into a server object with the method
|
|
||||||
<a href=#listen><tt>listen</tt></a> (after a call to <a
|
|
||||||
href=#bind><tt>bind</tt></a>) or into a client object with
|
|
||||||
the method <a href=#connect><tt>connect</tt></a>. The only other
|
|
||||||
method supported by a master object is the
|
|
||||||
<a href=#close><tt>close</tt></a> method.</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
In case of success, a new master object is returned. In case of error,
|
|
||||||
<b><tt>nil</tt></b> is returned, followed by an error message.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="socket.tcp6">
|
|
||||||
socket.<b>tcp6()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Creates and returns an IPv6 TCP master object. A master object can
|
|
||||||
be transformed into a server object with the method
|
|
||||||
<a href=#listen><tt>listen</tt></a> (after a call to <a
|
|
||||||
href=#bind><tt>bind</tt></a>) or into a client object with
|
|
||||||
the method <a href=#connect><tt>connect</tt></a>. The only other
|
|
||||||
method supported by a master object is the
|
|
||||||
<a href=#close><tt>close</tt></a> method.</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
In case of success, a new master object is returned. In case of error,
|
|
||||||
<b><tt>nil</tt></b> is returned, followed by an error message.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: The TCP object returned will have the option
|
|
||||||
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id="accept">
|
<p class=name id="accept">
|
||||||
@ -252,6 +174,78 @@ first success or until the last failure. If the timeout was
|
|||||||
set to zero, only the first address is tried.
|
set to zero, only the first address is tried.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="dirty">
|
||||||
|
master:<b>dirty()</b><br>
|
||||||
|
client:<b>dirty()</b><br>
|
||||||
|
server:<b>dirty()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Check the read buffer status.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: <b>This is an internal method, use at your own risk.</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="getfd">
|
||||||
|
master:<b>getfd()</b><br>
|
||||||
|
client:<b>getfd()</b><br>
|
||||||
|
server:<b>getfd()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Returns the underling socket descriptor or handle associated to the object.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The descriptor or handle. In case the object has been closed, the return will be -1.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: <b>This is an internal method. Unlikely to be
|
||||||
|
portable. Use at your own risk. </b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="getoption">
|
||||||
|
client:<b>getoption(</b>option)</b><br>
|
||||||
|
server:<b>getoption(</b>option)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Gets options for the TCP object.
|
||||||
|
See <a href=#setoption><tt>setoption</tt></a> for description of the
|
||||||
|
option names and values.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=parameters>
|
||||||
|
<tt>Option</tt> is a string with the option name.
|
||||||
|
<ul>
|
||||||
|
|
||||||
|
<li> '<tt>keepalive</tt>'
|
||||||
|
<li> '<tt>linger</tt>'
|
||||||
|
<li> '<tt>reuseaddr</tt>'
|
||||||
|
<li> '<tt>tcp-nodelay</tt>'
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The method returns the option <tt>value</tt> in case of success, or
|
||||||
|
<b><tt>nil</tt></b> followed by an error message otherwise.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id="getpeername">
|
<p class=name id="getpeername">
|
||||||
@ -310,6 +304,20 @@ The method returns the number of bytes received, the number of bytes sent,
|
|||||||
and the age of the socket object in seconds.
|
and the age of the socket object in seconds.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="gettimeout">
|
||||||
|
master:<b>gettimeout()</b><br>
|
||||||
|
client:<b>gettimeout()</b><br>
|
||||||
|
server:<b>gettimeout()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Returns the current block timeout followed by the curent
|
||||||
|
total timeout.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id="listen">
|
<p class=name id="listen">
|
||||||
@ -483,34 +491,6 @@ followed by an error message otherwise.
|
|||||||
Note: The descriptions above come from the man pages.
|
Note: The descriptions above come from the man pages.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="getoption">
|
|
||||||
client:<b>getoption(</b>option)</b><br>
|
|
||||||
server:<b>getoption(</b>option)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Gets options for the TCP object.
|
|
||||||
See <a href=#setoption><tt>setoption</tt></a> for description of the
|
|
||||||
option names and values.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=parameters>
|
|
||||||
<tt>Option</tt> is a string with the option name.
|
|
||||||
<ul>
|
|
||||||
|
|
||||||
<li> '<tt>keepalive</tt>'
|
|
||||||
<li> '<tt>linger</tt>'
|
|
||||||
<li> '<tt>reuseaddr</tt>'
|
|
||||||
<li> '<tt>tcp-nodelay</tt>'
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
The method returns the option <tt>value</tt> in case of success, or
|
|
||||||
<b><tt>nil</tt></b> followed by an error message otherwise.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id="setstats">
|
<p class=name id="setstats">
|
||||||
@ -615,46 +595,6 @@ This is the default mode;
|
|||||||
This function returns 1.
|
This function returns 1.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="dirty">
|
|
||||||
master:<b>dirty()</b><br>
|
|
||||||
client:<b>dirty()</b><br>
|
|
||||||
server:<b>dirty()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Check the read buffer status.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: <b>This is an internal method, any use is unlikely to be portable.</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class=name id="getfd">
|
|
||||||
master:<b>getfd()</b><br>
|
|
||||||
client:<b>getfd()</b><br>
|
|
||||||
server:<b>getfd()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=description>
|
|
||||||
Returns the underling socket descriptor or handle associated to the object.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
The descriptor or handle. In case the object has been closed, the return will be -1.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: <b>This is an internal method, any use is unlikely to be portable.</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class=name id="setfd">
|
<p class=name id="setfd">
|
||||||
@ -672,9 +612,90 @@ No return value.
|
|||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p class=note>
|
<p class=note>
|
||||||
Note: <b>This is an internal method, any use is unlikely to be portable.</b>
|
Note: <b>This is an internal method. Unlikely to be
|
||||||
|
portable. Use at your own risk. </b>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="socket.tcp">
|
||||||
|
socket.<b>tcp()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Creates and returns an TCP master object. A master object can
|
||||||
|
be transformed into a server object with the method
|
||||||
|
<a href=#listen><tt>listen</tt></a> (after a call to <a
|
||||||
|
href=#bind><tt>bind</tt></a>) or into a client object with
|
||||||
|
the method <a href=#connect><tt>connect</tt></a>. The only other
|
||||||
|
method supported by a master object is the
|
||||||
|
<a href=#close><tt>close</tt></a> method.</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
In case of success, a new master object is returned. In case of error,
|
||||||
|
<b><tt>nil</tt></b> is returned, followed by an error message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: The choice between IPv4 and IPv6 happens during a call to
|
||||||
|
<a href=#bind><tt>bind</tt></a> or <a
|
||||||
|
href=#bind><tt>connect</tt></a>, depending on the address
|
||||||
|
family obtained from the resolver.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: Before the choice between IPv4 and IPv6 happens,
|
||||||
|
the internal socket object is invalid and therefore <a
|
||||||
|
href=#setoption><tt>setoption</tt></a> will fail.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="socket.tcp4">
|
||||||
|
socket.<b>tcp4()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Creates and returns an IPv4 TCP master object. A master object can
|
||||||
|
be transformed into a server object with the method
|
||||||
|
<a href=#listen><tt>listen</tt></a> (after a call to <a
|
||||||
|
href=#bind><tt>bind</tt></a>) or into a client object with
|
||||||
|
the method <a href=#connect><tt>connect</tt></a>. The only other
|
||||||
|
method supported by a master object is the
|
||||||
|
<a href=#close><tt>close</tt></a> method.</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
In case of success, a new master object is returned. In case of error,
|
||||||
|
<b><tt>nil</tt></b> is returned, followed by an error message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="socket.tcp6">
|
||||||
|
socket.<b>tcp6()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Creates and returns an IPv6 TCP master object. A master object can
|
||||||
|
be transformed into a server object with the method
|
||||||
|
<a href=#listen><tt>listen</tt></a> (after a call to <a
|
||||||
|
href=#bind><tt>bind</tt></a>) or into a client object with
|
||||||
|
the method <a href=#connect><tt>connect</tt></a>. The only other
|
||||||
|
method supported by a master object is the
|
||||||
|
<a href=#close><tt>close</tt></a> method.</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
In case of success, a new master object is returned. In case of error,
|
||||||
|
<b><tt>nil</tt></b> is returned, followed by an error message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: The TCP object returned will have the option
|
||||||
|
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<div class=footer>
|
<div class=footer>
|
||||||
|
|||||||
833
doc/udp.html
833
doc/udp.html
@ -39,6 +39,430 @@
|
|||||||
|
|
||||||
<h2 id="udp">UDP</h2>
|
<h2 id="udp">UDP</h2>
|
||||||
|
|
||||||
|
<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="close">
|
||||||
|
connected:<b>close()</b><br>
|
||||||
|
unconnected:<b>close()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
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 <tt>close</tt>
|
||||||
|
method) are allowed on a closed socket.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
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 limited system resources.
|
||||||
|
Garbage-collected objects are automatically closed before
|
||||||
|
destruction, though.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="getoption">
|
||||||
|
connected:<b>getoption()</b><br>
|
||||||
|
unconnected:<b>getoption()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Gets an option value from the UDP object.
|
||||||
|
See <a href=#setoption><tt>setoption</tt></a> for
|
||||||
|
description of the option names and values.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters"><tt>Option</tt> is a string with the option name.
|
||||||
|
<ul>
|
||||||
|
<li> '<tt>dontroute</tt>'
|
||||||
|
<li> '<tt>broadcast</tt>'
|
||||||
|
<li> '<tt>reuseaddr</tt>'
|
||||||
|
<li> '<tt>reuseport</tt>'
|
||||||
|
<li> '<tt>ip-multicast-loop</tt>'
|
||||||
|
<li> '<tt>ipv6-v6only</tt>'
|
||||||
|
<li> '<tt>ip-multicast-if</tt>'
|
||||||
|
<li> '<tt>ip-multicast-ttl</tt>'
|
||||||
|
<li> '<tt>ip-add-membership</tt>'
|
||||||
|
<li> '<tt>ip-drop-membership</tt>'
|
||||||
|
</ul>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The method returns the option <tt>value</tt> in case of
|
||||||
|
success, or
|
||||||
|
<b><tt>nil</tt></b> followed by an error message otherwise.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="getpeername">
|
||||||
|
connected:<b>getpeername()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Retrieves information about the peer
|
||||||
|
associated with a connected UDP object.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
Returns a string with the IP address of the peer, the
|
||||||
|
port number that peer is using for the connection,
|
||||||
|
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
||||||
|
In case of error, the method returns <b><tt>nil</tt></b>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: It makes no sense to call this method on unconnected objects.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="getsockname">
|
||||||
|
connected:<b>getsockname()</b><br>
|
||||||
|
unconnected:<b>getsockname()</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Returns the local address information associated to the object.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<p class=return>
|
||||||
|
The method returns a string with local IP address, a number with
|
||||||
|
the local port,
|
||||||
|
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
||||||
|
In case of error, the method returns <b><tt>nil</tt></b>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: UDP sockets are not bound to any address
|
||||||
|
until the <a href="#setsockname"><tt>setsockname</tt></a> or the
|
||||||
|
<a href="#sendto"><tt>sendto</tt></a> method is called for the
|
||||||
|
first time (in which case it is bound to an ephemeral port and the
|
||||||
|
wild-card address).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class=name id="gettimeout">
|
||||||
|
connected:<b>settimeout(</b>value<b>)</b><br>
|
||||||
|
unconnected:<b>settimeout(</b>value<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=description>
|
||||||
|
Returns the current timeout value.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="receive">
|
||||||
|
connected:<b>receive(</b>[size]<b>)</b><br>
|
||||||
|
unconnected:<b>receive(</b>[size]<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters">
|
||||||
|
The optional <tt>size</tt> parameter
|
||||||
|
specifies the maximum size of the datagram to be retrieved. If
|
||||||
|
there are more than <tt>size</tt> bytes available in the datagram,
|
||||||
|
the excess bytes are discarded. If there are less then
|
||||||
|
<tt>size</tt> bytes available in the current datagram, the
|
||||||
|
available bytes are returned.
|
||||||
|
If <tt>size</tt> is omitted, the
|
||||||
|
compile-time constant <a
|
||||||
|
href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used
|
||||||
|
(it defaults to 8192 bytes). Larger sizes will cause a
|
||||||
|
temporary buffer to be allocated for the operation.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="return">
|
||||||
|
In case of success, the method returns the
|
||||||
|
received datagram. In case of timeout, the method returns
|
||||||
|
<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="receivefrom">
|
||||||
|
unconnected:<b>receivefrom(</b>[size]<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Works exactly as the <a href="#receive"><tt>receive</tt></a>
|
||||||
|
method, except it returns the IP
|
||||||
|
address and port as extra return values (and is therefore slightly less
|
||||||
|
efficient).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="send">
|
||||||
|
connected:<b>send(</b>datagram<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Sends a datagram to the UDP peer of a connected object.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters">
|
||||||
|
<tt>Datagram</tt> is a string with the datagram contents.
|
||||||
|
The maximum datagram size for UDP is 64K minus IP layer overhead.
|
||||||
|
However datagrams larger than the link layer packet size will be
|
||||||
|
fragmented, which may deteriorate performance and/or reliability.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="return">
|
||||||
|
If successful, the method returns 1. In case of
|
||||||
|
error, the method returns <b><tt>nil</tt></b> followed by an error message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: In UDP, the <tt>send</tt> 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).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="sendto">
|
||||||
|
unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Sends a datagram to the specified IP address and port number.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters">
|
||||||
|
<tt>Datagram</tt> is a string with the
|
||||||
|
datagram contents.
|
||||||
|
The maximum datagram size for UDP is 64K minus IP layer overhead.
|
||||||
|
However datagrams larger than the link layer packet size will be
|
||||||
|
fragmented, which may deteriorate performance and/or reliability.
|
||||||
|
<tt>Ip</tt> is the IP address of the recipient.
|
||||||
|
Host names are <em>not</em> allowed for performance reasons.
|
||||||
|
|
||||||
|
<tt>Port</tt> is the port number at the recipient.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="return">
|
||||||
|
If successful, the method returns 1. In case of
|
||||||
|
error, the method returns <b><tt>nil</tt></b> followed by an error message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: In UDP, the <tt>send</tt> 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).
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="setoption">
|
||||||
|
connected:<b>setoption(</b>option [, value]<b>)</b><br>
|
||||||
|
unconnected:<b>setoption(</b>option [, value]<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
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.</p>
|
||||||
|
<p class="parameters"><tt>Option</tt> is a string with the option
|
||||||
|
name, and <tt>value</tt> depends on the option being set:
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<ul>
|
||||||
|
<li> '<tt>dontroute</tt>': Indicates that outgoing
|
||||||
|
messages should bypass the standard routing facilities.
|
||||||
|
Receives a boolean value;
|
||||||
|
<li> '<tt>broadcast</tt>': Requests permission to send
|
||||||
|
broadcast datagrams on the socket.
|
||||||
|
Receives a boolean value;
|
||||||
|
<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
|
||||||
|
validating addresses supplied in a <tt>bind()</tt> call
|
||||||
|
should allow reuse of local addresses.
|
||||||
|
Receives a boolean value;
|
||||||
|
<li> '<tt>reuseport</tt>': Allows completely duplicate
|
||||||
|
bindings by multiple processes if they all set
|
||||||
|
'<tt>reuseport</tt>' before binding the port.
|
||||||
|
Receives a boolean value;
|
||||||
|
<li> '<tt>ip-multicast-loop</tt>':
|
||||||
|
Specifies whether or not a copy of an outgoing multicast
|
||||||
|
datagram is delivered to the sending host as long as it is a
|
||||||
|
member of the multicast group.
|
||||||
|
Receives a boolean value;
|
||||||
|
<li> '<tt>ipv6-v6only</tt>':
|
||||||
|
Specifies whether to restrict <tt>inet6</tt> sockets to
|
||||||
|
sending and receiving only IPv6 packets.
|
||||||
|
Receive a boolean value;
|
||||||
|
<li> '<tt>ip-multicast-if</tt>':
|
||||||
|
Sets the interface over which outgoing multicast datagrams
|
||||||
|
are sent.
|
||||||
|
Receives an IP address;
|
||||||
|
<li> '<tt>ip-multicast-ttl</tt>':
|
||||||
|
Sets the Time To Live in the IP header for outgoing
|
||||||
|
multicast datagrams.
|
||||||
|
Receives a number;
|
||||||
|
<li> '<tt>ip-add-membership</tt>':
|
||||||
|
Joins the multicast group specified.
|
||||||
|
Receives a table with fields
|
||||||
|
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
||||||
|
IP address;
|
||||||
|
<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
|
||||||
|
group specified.
|
||||||
|
Receives a table with fields
|
||||||
|
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
||||||
|
IP address.
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<p class="return">
|
||||||
|
The method returns 1 in case of success, or
|
||||||
|
<b><tt>nil</tt></b> followed by an error message otherwise.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: The descriptions above come from the man pages.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
|
||||||
|
<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="setpeername">
|
||||||
|
connected:<b>setpeername(</b>'*'<b>)</b><br>
|
||||||
|
unconnected:<b>setpeername(</b>address, port<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Changes the peer of a UDP object. This
|
||||||
|
method turns an unconnected UDP object into a connected UDP
|
||||||
|
object or vice versa.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
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 <a href="#send"><tt>send</tt></a> and
|
||||||
|
<a href="#receive"><tt>receive</tt></a> methods instead of
|
||||||
|
<a href="#sendto"><tt>sendto</tt></a> and
|
||||||
|
<a href="#receivefrom"><tt>receivefrom</tt></a>.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters">
|
||||||
|
<tt>Address</tt> can be an IP address or a
|
||||||
|
host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
|
||||||
|
'<tt>*</tt>' and the object is connected, the peer association is
|
||||||
|
removed and the object becomes an unconnected object again. In that
|
||||||
|
case, the <tt>port</tt> argument is ignored.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="return">
|
||||||
|
In case of error the method returns
|
||||||
|
<b><tt>nil</tt></b> followed by an error message. In case of success, the
|
||||||
|
method returns 1.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: 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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class=note>
|
||||||
|
Note: Starting with LuaSocket 3.0, the host name resolution
|
||||||
|
depends on whether the socket was created by <a
|
||||||
|
href=#socket.udp><tt>socket.udp</tt></a> or <a
|
||||||
|
href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
|
||||||
|
the appropriate family are tried in succession until the
|
||||||
|
first success or until the last failure.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="setsockname">
|
||||||
|
unconnected:<b>setsockname(</b>address, port<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Binds the UDP object to a local address.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters">
|
||||||
|
<tt>Address</tt> can be an IP address or a
|
||||||
|
host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
|
||||||
|
all local interfaces using the constant <tt>INADDR_ANY</tt>. If
|
||||||
|
<tt>port</tt> is 0, the system chooses an ephemeral port.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="return">
|
||||||
|
If successful, the method returns 1. In case of
|
||||||
|
error, the method returns <b><tt>nil</tt></b> followed by an error
|
||||||
|
message.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: 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 <tt>setsockname</tt>, it cannot be
|
||||||
|
changed.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
<p class="name" id="settimeout">
|
||||||
|
connected:<b>settimeout(</b>value<b>)</b><br>
|
||||||
|
unconnected:<b>settimeout(</b>value<b>)</b>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="description">
|
||||||
|
Changes the timeout values for the object. By default, the
|
||||||
|
<a href="#receive"><tt>receive</tt></a> and
|
||||||
|
<a href="#receivefrom"><tt>receivefrom</tt></a>
|
||||||
|
operations are blocking. That is, any call to the methods will block
|
||||||
|
indefinitely, until data arrives. The <tt>settimeout</tt> 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.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="parameters">
|
||||||
|
The amount of time to wait is specified as
|
||||||
|
the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
|
||||||
|
<tt>value</tt> allows operations to block indefinitely. Negative
|
||||||
|
timeout values have the same effect.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: In UDP, the <a href="#send"><tt>send</tt></a>
|
||||||
|
and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
|
||||||
|
datagram is just passed to the OS and the call returns
|
||||||
|
immediately). Therefore, the <tt>settimeout</tt> method has no
|
||||||
|
effect on them.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p class="note">
|
||||||
|
Note: The old <tt>timeout</tt> method is
|
||||||
|
deprecated. The name has been changed for sake of uniformity, since
|
||||||
|
all other method names already contained verbs making their
|
||||||
|
imperative nature obvious.
|
||||||
|
</p>
|
||||||
|
|
||||||
<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
<p class="name" id="socket.udp">
|
<p class="name" id="socket.udp">
|
||||||
@ -145,416 +569,7 @@ Note: The TCP object returned will have the option
|
|||||||
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="close">
|
|
||||||
connected:<b>close()</b><br>
|
|
||||||
unconnected:<b>close()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
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 <tt>close</tt>
|
|
||||||
method) are allowed on a closed socket.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
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 limited system resources.
|
|
||||||
Garbage-collected objects are automatically closed before
|
|
||||||
destruction, though.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="getpeername">
|
|
||||||
connected:<b>getpeername()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Retrieves information about the peer
|
|
||||||
associated with a connected UDP object.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
Returns a string with the IP address of the peer, the
|
|
||||||
port number that peer is using for the connection,
|
|
||||||
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
|
||||||
In case of error, the method returns <b><tt>nil</tt></b>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: It makes no sense to call this method on unconnected objects.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="getsockname">
|
|
||||||
connected:<b>getsockname()</b><br>
|
|
||||||
unconnected:<b>getsockname()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Returns the local address information associated to the object.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
The method returns a string with local IP address, a number with
|
|
||||||
the local port,
|
|
||||||
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
|
|
||||||
In case of error, the method returns <b><tt>nil</tt></b>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: UDP sockets are not bound to any address
|
|
||||||
until the <a href="#setsockname"><tt>setsockname</tt></a> or the
|
|
||||||
<a href="#sendto"><tt>sendto</tt></a> method is called for the
|
|
||||||
first time (in which case it is bound to an ephemeral port and the
|
|
||||||
wild-card address).
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="receive">
|
|
||||||
connected:<b>receive(</b>[size]<b>)</b><br>
|
|
||||||
unconnected:<b>receive(</b>[size]<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters">
|
|
||||||
The optional <tt>size</tt> parameter
|
|
||||||
specifies the maximum size of the datagram to be retrieved. If
|
|
||||||
there are more than <tt>size</tt> bytes available in the datagram,
|
|
||||||
the excess bytes are discarded. If there are less then
|
|
||||||
<tt>size</tt> bytes available in the current datagram, the
|
|
||||||
available bytes are returned.
|
|
||||||
If <tt>size</tt> is omitted, the
|
|
||||||
compile-time constant <a
|
|
||||||
href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used
|
|
||||||
(it defaults to 8192 bytes). Larger sizes will cause a
|
|
||||||
temporary buffer to be allocated for the operation.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="return">
|
|
||||||
In case of success, the method returns the
|
|
||||||
received datagram. In case of timeout, the method returns
|
|
||||||
<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="receivefrom">
|
|
||||||
unconnected:<b>receivefrom(</b>[size]<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Works exactly as the <a href="#receive"><tt>receive</tt></a>
|
|
||||||
method, except it returns the IP
|
|
||||||
address and port as extra return values (and is therefore slightly less
|
|
||||||
efficient).
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="getoption">
|
|
||||||
connected:<b>getoption()</b><br>
|
|
||||||
unconnected:<b>getoption()</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Gets an option value from the UDP object.
|
|
||||||
See <a href=#setoption><tt>setoption</tt></a> for
|
|
||||||
description of the option names and values.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters"><tt>Option</tt> is a string with the option name.
|
|
||||||
<ul>
|
|
||||||
<li> '<tt>dontroute</tt>'
|
|
||||||
<li> '<tt>broadcast</tt>'
|
|
||||||
<li> '<tt>reuseaddr</tt>'
|
|
||||||
<li> '<tt>reuseport</tt>'
|
|
||||||
<li> '<tt>ip-multicast-loop</tt>'
|
|
||||||
<li> '<tt>ipv6-v6only</tt>'
|
|
||||||
<li> '<tt>ip-multicast-if</tt>'
|
|
||||||
<li> '<tt>ip-multicast-ttl</tt>'
|
|
||||||
<li> '<tt>ip-add-membership</tt>'
|
|
||||||
<li> '<tt>ip-drop-membership</tt>'
|
|
||||||
</ul>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=return>
|
|
||||||
The method returns the option <tt>value</tt> in case of
|
|
||||||
success, or
|
|
||||||
<b><tt>nil</tt></b> followed by an error message otherwise.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="send">
|
|
||||||
connected:<b>send(</b>datagram<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Sends a datagram to the UDP peer of a connected object.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters">
|
|
||||||
<tt>Datagram</tt> is a string with the datagram contents.
|
|
||||||
The maximum datagram size for UDP is 64K minus IP layer overhead.
|
|
||||||
However datagrams larger than the link layer packet size will be
|
|
||||||
fragmented, which may deteriorate performance and/or reliability.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="return">
|
|
||||||
If successful, the method returns 1. In case of
|
|
||||||
error, the method returns <b><tt>nil</tt></b> followed by an error message.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: In UDP, the <tt>send</tt> 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).
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="sendto">
|
|
||||||
unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Sends a datagram to the specified IP address and port number.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters">
|
|
||||||
<tt>Datagram</tt> is a string with the
|
|
||||||
datagram contents.
|
|
||||||
The maximum datagram size for UDP is 64K minus IP layer overhead.
|
|
||||||
However datagrams larger than the link layer packet size will be
|
|
||||||
fragmented, which may deteriorate performance and/or reliability.
|
|
||||||
<tt>Ip</tt> is the IP address of the recipient.
|
|
||||||
Host names are <em>not</em> allowed for performance reasons.
|
|
||||||
|
|
||||||
<tt>Port</tt> is the port number at the recipient.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="return">
|
|
||||||
If successful, the method returns 1. In case of
|
|
||||||
error, the method returns <b><tt>nil</tt></b> followed by an error message.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: In UDP, the <tt>send</tt> 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).
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="setpeername">
|
|
||||||
connected:<b>setpeername(</b>'*'<b>)</b><br>
|
|
||||||
unconnected:<b>setpeername(</b>address, port<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Changes the peer of a UDP object. This
|
|
||||||
method turns an unconnected UDP object into a connected UDP
|
|
||||||
object or vice versa.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
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 <a href="#send"><tt>send</tt></a> and
|
|
||||||
<a href="#receive"><tt>receive</tt></a> methods instead of
|
|
||||||
<a href="#sendto"><tt>sendto</tt></a> and
|
|
||||||
<a href="#receivefrom"><tt>receivefrom</tt></a>.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters">
|
|
||||||
<tt>Address</tt> can be an IP address or a
|
|
||||||
host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
|
|
||||||
'<tt>*</tt>' and the object is connected, the peer association is
|
|
||||||
removed and the object becomes an unconnected object again. In that
|
|
||||||
case, the <tt>port</tt> argument is ignored.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="return">
|
|
||||||
In case of error the method returns
|
|
||||||
<b><tt>nil</tt></b> followed by an error message. In case of success, the
|
|
||||||
method returns 1.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: 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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: Starting with LuaSocket 3.0, the host name resolution
|
|
||||||
depends on whether the socket was created by <a
|
|
||||||
href=#socket.udp><tt>socket.udp</tt></a> or <a
|
|
||||||
href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
|
|
||||||
the appropriate family are tried in succession until the
|
|
||||||
first success or until the last failure.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="setsockname">
|
|
||||||
unconnected:<b>setsockname(</b>address, port<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Binds the UDP object to a local address.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters">
|
|
||||||
<tt>Address</tt> can be an IP address or a
|
|
||||||
host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
|
|
||||||
all local interfaces using the constant <tt>INADDR_ANY</tt>. If
|
|
||||||
<tt>port</tt> is 0, the system chooses an ephemeral port.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="return">
|
|
||||||
If successful, the method returns 1. In case of
|
|
||||||
error, the method returns <b><tt>nil</tt></b> followed by an error
|
|
||||||
message.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: 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 <tt>setsockname</tt>, it cannot be
|
|
||||||
changed.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="setoption">
|
|
||||||
connected:<b>setoption(</b>option [, value]<b>)</b><br>
|
|
||||||
unconnected:<b>setoption(</b>option [, value]<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
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.</p>
|
|
||||||
<p class="parameters"><tt>Option</tt> is a string with the option
|
|
||||||
name, and <tt>value</tt> depends on the option being set:
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<ul>
|
|
||||||
<li> '<tt>dontroute</tt>': Indicates that outgoing
|
|
||||||
messages should bypass the standard routing facilities.
|
|
||||||
Receives a boolean value;
|
|
||||||
<li> '<tt>broadcast</tt>': Requests permission to send
|
|
||||||
broadcast datagrams on the socket.
|
|
||||||
Receives a boolean value;
|
|
||||||
<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
|
|
||||||
validating addresses supplied in a <tt>bind()</tt> call
|
|
||||||
should allow reuse of local addresses.
|
|
||||||
Receives a boolean value;
|
|
||||||
<li> '<tt>reuseport</tt>': Allows completely duplicate
|
|
||||||
bindings by multiple processes if they all set
|
|
||||||
'<tt>reuseport</tt>' before binding the port.
|
|
||||||
Receives a boolean value;
|
|
||||||
<li> '<tt>ip-multicast-loop</tt>':
|
|
||||||
Specifies whether or not a copy of an outgoing multicast
|
|
||||||
datagram is delivered to the sending host as long as it is a
|
|
||||||
member of the multicast group.
|
|
||||||
Receives a boolean value;
|
|
||||||
<li> '<tt>ipv6-v6only</tt>':
|
|
||||||
Specifies whether to restrict <tt>inet6</tt> sockets to
|
|
||||||
sending and receiving only IPv6 packets.
|
|
||||||
Receive a boolean value;
|
|
||||||
<li> '<tt>ip-multicast-if</tt>':
|
|
||||||
Sets the interface over which outgoing multicast datagrams
|
|
||||||
are sent.
|
|
||||||
Receives an IP address;
|
|
||||||
<li> '<tt>ip-multicast-ttl</tt>':
|
|
||||||
Sets the Time To Live in the IP header for outgoing
|
|
||||||
multicast datagrams.
|
|
||||||
Receives a number;
|
|
||||||
<li> '<tt>ip-add-membership</tt>':
|
|
||||||
Joins the multicast group specified.
|
|
||||||
Receives a table with fields
|
|
||||||
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
|
||||||
IP address;
|
|
||||||
<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
|
|
||||||
group specified.
|
|
||||||
Receives a table with fields
|
|
||||||
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
|
|
||||||
IP address.
|
|
||||||
</ul>
|
|
||||||
|
|
||||||
<p class="return">
|
|
||||||
The method returns 1 in case of success, or
|
|
||||||
<b><tt>nil</tt></b> followed by an error message otherwise.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class=note>
|
|
||||||
Note: The descriptions above come from the man pages.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
||||||
|
|
||||||
<p class="name" id="settimeout">
|
|
||||||
connected:<b>settimeout(</b>value<b>)</b><br>
|
|
||||||
unconnected:<b>settimeout(</b>value<b>)</b>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="description">
|
|
||||||
Changes the timeout values for the object. By default, the
|
|
||||||
<a href="#receive"><tt>receive</tt></a> and
|
|
||||||
<a href="#receivefrom"><tt>receivefrom</tt></a>
|
|
||||||
operations are blocking. That is, any call to the methods will block
|
|
||||||
indefinitely, until data arrives. The <tt>settimeout</tt> 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.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="parameters">
|
|
||||||
The amount of time to wait is specified as
|
|
||||||
the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
|
|
||||||
<tt>value</tt> allows operations to block indefinitely. Negative
|
|
||||||
timeout values have the same effect.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: In UDP, the <a href="#send"><tt>send</tt></a>
|
|
||||||
and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
|
|
||||||
datagram is just passed to the OS and the call returns
|
|
||||||
immediately). Therefore, the <tt>settimeout</tt> method has no
|
|
||||||
effect on them.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<p class="note">
|
|
||||||
Note: The old <tt>timeout</tt> method is
|
|
||||||
deprecated. The name has been changed for sake of uniformity, since
|
|
||||||
all other method names already contained verbs making their
|
|
||||||
imperative nature obvious.
|
|
||||||
</p>
|
|
||||||
|
|
||||||
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
||||||
|
|
||||||
|
|||||||
@ -36,6 +36,7 @@ static int meth_accept(lua_State *L);
|
|||||||
static int meth_close(lua_State *L);
|
static int meth_close(lua_State *L);
|
||||||
static int meth_getoption(lua_State *L);
|
static int meth_getoption(lua_State *L);
|
||||||
static int meth_setoption(lua_State *L);
|
static int meth_setoption(lua_State *L);
|
||||||
|
static int meth_gettimeout(lua_State *L);
|
||||||
static int meth_settimeout(lua_State *L);
|
static int meth_settimeout(lua_State *L);
|
||||||
static int meth_getfd(lua_State *L);
|
static int meth_getfd(lua_State *L);
|
||||||
static int meth_setfd(lua_State *L);
|
static int meth_setfd(lua_State *L);
|
||||||
@ -65,6 +66,7 @@ static luaL_Reg tcp_methods[] = {
|
|||||||
{"setpeername", meth_connect},
|
{"setpeername", meth_connect},
|
||||||
{"setsockname", meth_bind},
|
{"setsockname", meth_bind},
|
||||||
{"settimeout", meth_settimeout},
|
{"settimeout", meth_settimeout},
|
||||||
|
{"gettimeout", meth_gettimeout},
|
||||||
{"shutdown", meth_shutdown},
|
{"shutdown", meth_shutdown},
|
||||||
{NULL, NULL}
|
{NULL, NULL}
|
||||||
};
|
};
|
||||||
@ -350,6 +352,12 @@ static int meth_settimeout(lua_State *L)
|
|||||||
return timeout_meth_settimeout(L, &tcp->tm);
|
return timeout_meth_settimeout(L, &tcp->tm);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
static int meth_gettimeout(lua_State *L)
|
||||||
|
{
|
||||||
|
p_tcp tcp = (p_tcp) auxiliar_checkgroup(L, "tcp{any}", 1);
|
||||||
|
return timeout_meth_gettimeout(L, &tcp->tm);
|
||||||
|
}
|
||||||
|
|
||||||
/*=========================================================================*\
|
/*=========================================================================*\
|
||||||
* Library functions
|
* Library functions
|
||||||
\*=========================================================================*/
|
\*=========================================================================*/
|
||||||
|
|||||||
@ -173,6 +173,16 @@ int timeout_meth_settimeout(lua_State *L, p_timeout tm) {
|
|||||||
return 1;
|
return 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/*-------------------------------------------------------------------------*\
|
||||||
|
* Gets timeout values for IO operations
|
||||||
|
* Lua Output: block, total
|
||||||
|
\*-------------------------------------------------------------------------*/
|
||||||
|
int timeout_meth_gettimeout(lua_State *L, p_timeout tm) {
|
||||||
|
lua_pushnumber(L, tm->block);
|
||||||
|
lua_pushnumber(L, tm->total);
|
||||||
|
return 2;
|
||||||
|
}
|
||||||
|
|
||||||
/*=========================================================================*\
|
/*=========================================================================*\
|
||||||
* Test support functions
|
* Test support functions
|
||||||
\*=========================================================================*/
|
\*=========================================================================*/
|
||||||
|
|||||||
@ -22,6 +22,7 @@ p_timeout timeout_markstart(p_timeout tm);
|
|||||||
double timeout_getstart(p_timeout tm);
|
double timeout_getstart(p_timeout tm);
|
||||||
double timeout_gettime(void);
|
double timeout_gettime(void);
|
||||||
int timeout_meth_settimeout(lua_State *L, p_timeout tm);
|
int timeout_meth_settimeout(lua_State *L, p_timeout tm);
|
||||||
|
int timeout_meth_gettimeout(lua_State *L, p_timeout tm);
|
||||||
|
|
||||||
#define timeout_iszero(tm) ((tm)->block == 0.0)
|
#define timeout_iszero(tm) ((tm)->block == 0.0)
|
||||||
|
|
||||||
|
|||||||
@ -36,6 +36,7 @@ static int meth_receivefrom(lua_State *L);
|
|||||||
static int meth_getfamily(lua_State *L);
|
static int meth_getfamily(lua_State *L);
|
||||||
static int meth_getsockname(lua_State *L);
|
static int meth_getsockname(lua_State *L);
|
||||||
static int meth_getpeername(lua_State *L);
|
static int meth_getpeername(lua_State *L);
|
||||||
|
static int meth_gettimeout(lua_State *L);
|
||||||
static int meth_setsockname(lua_State *L);
|
static int meth_setsockname(lua_State *L);
|
||||||
static int meth_setpeername(lua_State *L);
|
static int meth_setpeername(lua_State *L);
|
||||||
static int meth_close(lua_State *L);
|
static int meth_close(lua_State *L);
|
||||||
@ -66,6 +67,7 @@ static luaL_Reg udp_methods[] = {
|
|||||||
{"setpeername", meth_setpeername},
|
{"setpeername", meth_setpeername},
|
||||||
{"setsockname", meth_setsockname},
|
{"setsockname", meth_setsockname},
|
||||||
{"settimeout", meth_settimeout},
|
{"settimeout", meth_settimeout},
|
||||||
|
{"gettimeout", meth_gettimeout},
|
||||||
{NULL, NULL}
|
{NULL, NULL}
|
||||||
};
|
};
|
||||||
|
|
||||||
@ -347,6 +349,11 @@ static int meth_settimeout(lua_State *L) {
|
|||||||
return timeout_meth_settimeout(L, &udp->tm);
|
return timeout_meth_settimeout(L, &udp->tm);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
static int meth_gettimeout(lua_State *L) {
|
||||||
|
p_udp udp = (p_udp) auxiliar_checkgroup(L, "udp{any}", 1);
|
||||||
|
return timeout_meth_gettimeout(L, &udp->tm);
|
||||||
|
}
|
||||||
|
|
||||||
/*-------------------------------------------------------------------------*\
|
/*-------------------------------------------------------------------------*\
|
||||||
* Turns a master udp object into a client object.
|
* Turns a master udp object into a client object.
|
||||||
\*-------------------------------------------------------------------------*/
|
\*-------------------------------------------------------------------------*/
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user