dany/luasocket
1
0
Fork 0
mirror of https://github.com/lunarmodules/luasocket.git synced 2024-12-26 12:28:21 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'upstream/master' into test-builds

Browse Source
This commit is contained in:
Caleb Maclennan 2022-03-24 18:11:07 +03:00
commit 2de8ddfbb8
No known key found for this signature in database
GPG Key ID: B538286DE04ECFE5
28 changed files with 1002 additions and 984 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.github/workflows/luacheck.yml vendored
View File

@ -9,11 +9,5 @@ jobs:
steps: steps:
- name: Checkout - name: Checkout
uses: actions/checkout@v3 uses: actions/checkout@v3
- name: Setup ‘lua’ - name: Luacheck
uses: leafo/gh-actions-lua@v9 uses: lunarmodules/luacheck@v0
- name: Setup ‘luarocks’
uses: leafo/gh-actions-luarocks@v4
- name: Setup ‘luacheck’
run: luarocks install luacheck
- name: Run ‘luacheck’ linter
run: luacheck .

3
LICENSE
View File

@ -1,5 +1,4 @@
LuaSocket 3.0 license Copyright (C) 2004-2022 Diego Nehab
Copyright © 2004-2013 Diego Nehab
Permission is hereby granted, free of charge, to any person obtaining a Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"), copy of this software and associated documentation files (the "Software"),

2
README
View File

@ -3,7 +3,7 @@ and Linux.
Please use the project page at GitHub Please use the project page at GitHub
https://github.com/diegonehab/luasocket https://github.com/lunarmodules/luasocket
to file bug reports or propose changes. to file bug reports or propose changes.

50
doc/dns.html → docs/dns.html
View File

@ -13,17 +13,17 @@
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -36,13 +36,13 @@
<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=dns>DNS</h2> <h2 id="dns">DNS</h2>
<p> <p>
IPv4 name resolution functions IPv4 name resolution functions
<a href=#toip><tt>dns.toip</tt></a> <a href="#toip"><tt>dns.toip</tt></a>
and and
<a href=#tohostname><tt>dns.tohostname</tt></a> <a href="#tohostname"><tt>dns.tohostname</tt></a>
return <em>all</em> information obtained from return <em>all</em> information obtained from
the resolver in a table of the form: the resolver in a table of the form:
</p> </p>
@ -61,7 +61,7 @@ Note that the <tt>alias</tt> list can be empty.
<p> <p>
The more general name resolution function The more general name resolution function
<a href=#getaddrinfo><tt>dns.getaddrinfo</tt></a>, which <a href="#getaddrinfo"><tt>dns.getaddrinfo</tt></a>, which
supports both IPv6 and IPv4, supports both IPv6 and IPv4,
returns <em>all</em> information obtained from returns <em>all</em> information obtained from
the resolver in a table of the form: the resolver in a table of the form:
@ -88,19 +88,19 @@ addresses, and <tt>"inet6"</tt> for IPv6 addresses.
<!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=getaddrinfo> <p class="name" id="getaddrinfo">
socket.dns.<b>getaddrinfo(</b>address<b>)</b> socket.dns.<b>getaddrinfo(</b>address<b>)</b>
</p> </p>
<p class=description> <p class="description">
Converts from host name to address. Converts from host name to address.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Address</tt> can be an IPv4 or IPv6 address or host name. <tt>Address</tt> can be an IPv4 or IPv6 address or host name.
</p> </p>
<p class=return> <p class="return">
The function returns a table with all information returned by The function returns a table with all information returned by
the resolver. In case of error, the function returns <b><tt>nil</tt></b> the resolver. In case of error, the function returns <b><tt>nil</tt></b>
followed by an error message. followed by an error message.
@ -108,29 +108,29 @@ followed by an error message.
<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=gethostname> <p class="name" id="gethostname">
socket.dns.<b>gethostname()</b> socket.dns.<b>gethostname()</b>
</p> </p>
<p class=description> <p class="description">
Returns the standard host name for the machine as a string. Returns the standard host name for the machine as a string.
</p> </p>
<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=tohostname> <p class="name" id="tohostname">
socket.dns.<b>tohostname(</b>address<b>)</b> socket.dns.<b>tohostname(</b>address<b>)</b>
</p> </p>
<p class=description> <p class="description">
Converts from IPv4 address to host name. Converts from IPv4 address to host name.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Address</tt> can be an IP address or host name. <tt>Address</tt> can be an IP address or host name.
</p> </p>
<p class=return> <p class="return">
The function returns a string with the canonic host name of the given The function returns a string with the canonic host name of the given
<tt>address</tt>, followed by a table with all information returned by <tt>address</tt>, followed by a table with all information returned by
the resolver. In case of error, the function returns <b><tt>nil</tt></b> the resolver. In case of error, the function returns <b><tt>nil</tt></b>
@ -139,19 +139,19 @@ followed by an error message.
<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=toip> <p class="name" id="toip">
socket.dns.<b>toip(</b>address<b>)</b> socket.dns.<b>toip(</b>address<b>)</b>
</p> </p>
<p class=description> <p class="description">
Converts from host name to IPv4 address. Converts from host name to IPv4 address.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Address</tt> can be an IP address or host name. <tt>Address</tt> can be an IP address or host name.
</p> </p>
<p class=return> <p class="return">
Returns a string with the first IP address found for <tt>address</tt>, Returns a string with the first IP address found for <tt>address</tt>,
followed by a table with all information returned by the resolver. followed by a table with all information returned by the resolver.
In case of error, the function returns <b><tt>nil</tt></b> followed by an error In case of error, the function returns <b><tt>nil</tt></b> followed by an error
@ -160,10 +160,10 @@ message.
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

72
doc/ftp.html → docs/ftp.html
View File

@ -13,17 +13,17 @@
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -36,7 +36,7 @@
<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=ftp>FTP</h2> <h2 id="ftp">FTP</h2>
<p> <p>
FTP (File Transfer Protocol) is a protocol used to transfer files FTP (File Transfer Protocol) is a protocol used to transfer files
@ -63,7 +63,7 @@ LTN012, Filters sources and sinks</a> is necessary.
To obtain the <tt>ftp</tt> namespace, run: To obtain the <tt>ftp</tt> namespace, run:
</p> </p>
<pre class=example> <pre class="example">
-- loads the FTP module and any libraries it requires -- loads the FTP module and any libraries it requires
local ftp = require("socket.ftp") local ftp = require("socket.ftp")
</pre> </pre>
@ -85,15 +85,15 @@ the FTP module:
</p> </p>
<ul> <ul>
<li> <tt>PASSWORD</tt>: default anonymous password. <li> <tt>PASSWORD</tt>: default anonymous password.</li>
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
<li> <tt>USER</tt>: default anonymous user; <li> <tt>USER</tt>: default anonymous user;</li>
</ul> </ul>
<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=get> <p class="name" id="get">
ftp.<b>get(</b>url<b>)</b><br> ftp.<b>get(</b>url<b>)</b><br>
ftp.<b>get{</b><br> ftp.<b>get{</b><br>
&nbsp;&nbsp;host = <i>string</i>,<br> &nbsp;&nbsp;host = <i>string</i>,<br>
@ -109,14 +109,14 @@ ftp.<b>get{</b><br>
<b>}</b> <b>}</b>
</p> </p>
<p class=description> <p class="description">
The <tt>get</tt> function has two forms. The simple form has fixed The <tt>get</tt> function has two forms. The simple form has fixed
functionality: it downloads the contents of a URL and returns it as a functionality: it downloads the contents of a URL and returns it as a
string. The generic form allows a <em>lot</em> more control, as explained string. The generic form allows a <em>lot</em> more control, as explained
below. below.
</p> </p>
<p class=parameters> <p class="parameters">
If the argument of the <tt>get</tt> function is a table, the function If the argument of the <tt>get</tt> function is a table, the function
expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
@ -129,28 +129,28 @@ optional arguments are the following:
</p> </p>
<ul> <ul>
<li><tt>user</tt>, <tt>password</tt>: User name and password used for <li><tt>user</tt>, <tt>password</tt>: User name and password used for
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
<li><tt>command</tt>: The FTP command used to obtain data. Defaults to <li><tt>command</tt>: The FTP command used to obtain data. Defaults to
"<tt>retr</tt>", but see example below; "<tt>retr</tt>", but see example below;</li>
<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
"<tt>a</tt>". Defaults to whatever is the server default; "<tt>a</tt>". Defaults to whatever is the server default;</li>
<li><tt>step</tt>: <li><tt>step</tt>:
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
pump step function used to pass data from the pump step function used to pass data from the
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
<li><tt>create</tt>: An optional function to be used instead of <li><tt>create</tt>: An optional function to be used instead of
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
</ul> </ul>
<p class=return> <p class="return">
If successful, the simple version returns the URL contents as a If successful, the simple version returns the URL contents as a
string, and the generic function returns 1. In case of error, both string, and the generic function returns 1. In case of error, both
functions return <b><tt>nil</tt></b> and an error message describing the functions return <b><tt>nil</tt></b> and an error message describing the
error. error.
</p> </p>
<pre class=example> <pre class="example">
-- load the ftp support -- load the ftp support
local ftp = require("socket.ftp") local ftp = require("socket.ftp")
@ -159,7 +159,7 @@ local ftp = require("socket.ftp")
f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
</pre> </pre>
<pre class=example> <pre class="example">
-- load needed modules -- load needed modules
local ftp = require("socket.ftp") local ftp = require("socket.ftp")
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
@ -178,7 +178,7 @@ end
<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=put> <p class="name" id="put">
ftp.<b>put(</b>url, content<b>)</b><br> ftp.<b>put(</b>url, content<b>)</b><br>
ftp.<b>put{</b><br> ftp.<b>put{</b><br>
&nbsp;&nbsp;host = <i>string</i>,<br> &nbsp;&nbsp;host = <i>string</i>,<br>
@ -194,13 +194,13 @@ ftp.<b>put{</b><br>
<b>}</b> <b>}</b>
</p> </p>
<p class=description> <p class="description">
The <tt>put</tt> function has two forms. The simple form has fixed The <tt>put</tt> function has two forms. The simple form has fixed
functionality: it uploads a string of content into a URL. The generic form functionality: it uploads a string of content into a URL. The generic form
allows a <em>lot</em> more control, as explained below. allows a <em>lot</em> more control, as explained below.
</p> </p>
<p class=parameters> <p class="parameters">
If the argument of the <tt>put</tt> function is a table, the function If the argument of the <tt>put</tt> function is a table, the function
expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
@ -214,26 +214,26 @@ optional arguments are the following:
</p> </p>
<ul> <ul>
<li><tt>user</tt>, <tt>password</tt>: User name and password used for <li><tt>user</tt>, <tt>password</tt>: User name and password used for
authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
<li><tt>command</tt>: The FTP command used to send data. Defaults to <li><tt>command</tt>: The FTP command used to send data. Defaults to
"<tt>stor</tt>", but see example below; "<tt>stor</tt>", but see example below;</li>
<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
"<tt>a</tt>". Defaults to whatever is the server default; "<tt>a</tt>". Defaults to whatever is the server default;</li>
<li><tt>step</tt>: <li><tt>step</tt>:
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
pump step function used to pass data from the pump step function used to pass data from the
server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
<li><tt>create</tt>: An optional function to be used instead of <li><tt>create</tt>: An optional function to be used instead of
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
</ul> </ul>
<p class=return> <p class="return">
Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
message describing the reason for failure. message describing the reason for failure.
</p> </p>
<pre class=example> <pre class="example">
-- load the ftp support -- load the ftp support
local ftp = require("socket.ftp") local ftp = require("socket.ftp")
@ -244,7 +244,7 @@ f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
"wrong password, of course") "wrong password, of course")
</pre> </pre>
<pre class=example> <pre class="example">
-- load the ftp support -- load the ftp support
local ftp = require("socket.ftp") local ftp = require("socket.ftp")
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
@ -265,10 +265,10 @@ f, e = ftp.put{
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

78
doc/http.html → docs/http.html
View File

@ -13,17 +13,17 @@
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="introduction.html">introduction</a> &middot; <a href="introduction.html">introduction</a> &middot;
@ -59,7 +59,7 @@ string oriented requests, through generic
To obtain the <tt>http</tt> namespace, run: To obtain the <tt>http</tt> namespace, run:
</p> </p>
<pre class=example> <pre class="example">
-- loads the HTTP module and any libraries it requires -- loads the HTTP module and any libraries it requires
local http = require("socket.http") local http = require("socket.http")
</pre> </pre>
@ -97,11 +97,11 @@ headers = {<br>
<p> <p>
Field names are case insensitive (as specified by the standard) and all Field names are case insensitive (as specified by the standard) and all
functions work with lowercase field names (but see functions work with lowercase field names (but see
<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). <a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
Field values are left unmodified. Field values are left unmodified.
</p> </p>
<p class=note> <p class="note">
Note: MIME headers are independent of order. Therefore, there is no problem Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table. in representing them in a Lua table.
</p> </p>
@ -112,19 +112,19 @@ the HTTP module:
</p> </p>
<ul> <ul>
<li> <tt>PROXY</tt>: default proxy used for connections; <li> <tt>PROXY</tt>: default proxy used for connections;</li>
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
<li> <tt>USERAGENT</tt>: default user agent reported to server. <li> <tt>USERAGENT</tt>: default user agent reported to server.</li>
</ul> </ul>
<p class=note id="post"> <p class="note">
Note: These constants are global. Changing them will also Note: These constants are global. Changing them will also
change the behavior other code that might be using LuaSocket. change the behavior other code that might be using LuaSocket.
</p> </p>
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="request"> <p class="name" id="request">
http.<b>request(</b>url [, body]<b>)</b><br> http.<b>request(</b>url [, body]<b>)</b><br>
http.<b>request{</b><br> http.<b>request{</b><br>
&nbsp;&nbsp;url = <i>string</i>,<br> &nbsp;&nbsp;url = <i>string</i>,<br>
@ -140,14 +140,14 @@ http.<b>request{</b><br>
<b>}</b> <b>}</b>
</p> </p>
<p class=description> <p class="description">
The request function has two forms. The simple form downloads The request function has two forms. The simple form downloads
a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based
on strings. The generic form performs any HTTP method and is on strings. The generic form performs any HTTP method and is
<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based. <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based.
</p> </p>
<p class=parameters> <p class="parameters">
If the first argument of the <tt>request</tt> function is a string, it If the first argument of the <tt>request</tt> function is a string, it
should be an <tt>url</tt>. In that case, if a <tt>body</tt> should be an <tt>url</tt>. In that case, if a <tt>body</tt>
is provided as a string, the function will perform a <tt>POST</tt> method is provided as a string, the function will perform a <tt>POST</tt> method
@ -155,7 +155,7 @@ in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the
<tt>url</tt> <tt>url</tt>
</p> </p>
<p class=parameters> <p class="parameters">
If the first argument is instead a table, the most important fields are If the first argument is instead a table, the most important fields are
the <tt>url</tt> and the <em>simple</em> the <tt>url</tt> and the <em>simple</em>
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
@ -169,27 +169,29 @@ function discards the downloaded data. The optional parameters are the
following: following:
</p> </p>
<ul> <ul>
<li><tt>method</tt>: The HTTP request method. Defaults to "GET"; <li><tt>method</tt>: The HTTP request method. Defaults to "GET";</li>
<li><tt>headers</tt>: Any additional HTTP headers to send with the request; <li><tt>headers</tt>: Any additional HTTP headers to send with the request;</li>
<li><tt>source</tt>: <em>simple</em> <li><tt>source</tt>: <em>simple</em>
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
source to provide the request body. If there source to provide the request body. If there
is a body, you need to provide an appropriate "<tt>content-length</tt>" is a body, you need to provide an appropriate "<tt>content-length</tt>"
request header field, or the function will attempt to send the body as request header field, or the function will attempt to send the body as
"<tt>chunked</tt>" (something few servers support). Defaults to the empty source; "<tt>chunked</tt>" (something few servers support). Defaults to the empty source;</li>
<li><tt>step</tt>: <li><tt>step</tt>:
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
pump step function used to move data. pump step function used to move data.
Defaults to the LTN12 <tt>pump.step</tt> function. Defaults to the LTN12 <tt>pump.step</tt> function.</li>
<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;</li>
<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
function from automatically following 301 or 302 server redirect messages; function from automatically following 301 or 302 server redirect messages;</li>
<li><tt>create</tt>: An optional function to be used instead of <li><tt>create</tt>: An optional function to be used instead of
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
<li><tt>maxredirects</tt>: An optional number specifying the maximum number of redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean <tt>false</tt> value means no maximum (unlimited). <li><tt>maxredirects</tt>: An optional number specifying the maximum number of
redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean
<tt>false</tt> value means no maximum (unlimited).</li>
</ul> </ul>
<p class=return> <p class="return">
In case of failure, the function returns <tt><b>nil</b></tt> followed by an In case of failure, the function returns <tt><b>nil</b></tt> followed by an
error message. If successful, the simple form returns the response error message. If successful, the simple form returns the response
body as a string, followed by the response status code, the response body as a string, followed by the response status code, the response
@ -198,7 +200,7 @@ information, except the first return value is just the number 1 (the body
goes to the <tt>sink</tt>). goes to the <tt>sink</tt>).
</p> </p>
<p class=return> <p class="return">
Even when the server fails to provide the contents of the requested URL (URL not found, for example), Even when the server fails to provide the contents of the requested URL (URL not found, for example),
it usually returns a message body (a web page informing the it usually returns a message body (a web page informing the
URL was not found or some other useless page). To make sure the URL was not found or some other useless page). To make sure the
@ -207,11 +209,11 @@ a list of the possible values and their meanings, refer to <a
href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
</p> </p>
<p class=description> <p class="description">
Here are a few examples with the simple interface: Here are a few examples with the simple interface:
</p> </p>
<pre class=example> <pre class="example">
-- load the http module -- load the http module
local io = require("io") local io = require("io")
local http = require("socket.http") local http = require("socket.http")
@ -237,11 +239,11 @@ r, e = http.request("http://wrong.host/")
-- r is nil, and e returns with value "host not found" -- r is nil, and e returns with value "host not found"
</pre> </pre>
<p class=description> <p class="description">
And here is an example using the generic interface: And here is an example using the generic interface:
</p> </p>
<pre class=example> <pre class="example">
-- load the http module -- load the http module
http = require("socket.http") http = require("socket.http")
@ -263,7 +265,7 @@ r, c, h = http.request {
-- } -- }
</pre> </pre>
<p class=note id="post"> <p class="note" id="post">
Note: When sending a POST request, simple interface adds a Note: When sending a POST request, simple interface adds a
"<tt>Content-type: application/x-www-form-urlencoded</tt>" "<tt>Content-type: application/x-www-form-urlencoded</tt>"
header to the request. This is the type used by header to the request. This is the type used by
@ -271,21 +273,21 @@ HTML forms. If you need another type, use the generic
interface. interface.
</p> </p>
<p class=note id="authentication"> <p class="note" id="authentication">
Note: Some URLs are protected by their Note: Some URLs are protected by their
servers from anonymous download. For those URLs, the server must receive servers from anonymous download. For those URLs, the server must receive
some sort of authentication along with the request or it will deny some sort of authentication along with the request or it will deny
download and return status "401&nbsp;Authentication Required". download and return status "401&nbsp;Authentication Required".
</p> </p>
<p class=note> <p class="note">
The HTTP/1.1 standard defines two authentication methods: the Basic The HTTP/1.1 standard defines two authentication methods: the Basic
Authentication Scheme and the Digest Authentication Scheme, both Authentication Scheme and the Digest Authentication Scheme, both
explained in detail in explained in detail in
<a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>. <a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>.
</p> </p>
<p class=note>The Basic Authentication Scheme sends <p class="note">The Basic Authentication Scheme sends
<tt>&lt;user&gt;</tt> and <tt>&lt;user&gt;</tt> and
<tt>&lt;password&gt;</tt> unencrypted to the server and is therefore <tt>&lt;password&gt;</tt> unencrypted to the server and is therefore
considered unsafe. Unfortunately, by the time of this implementation, considered unsafe. Unfortunately, by the time of this implementation,
@ -294,7 +296,7 @@ Therefore, this is the method used by the toolkit whenever
authentication is required. authentication is required.
</p> </p>
<pre class=example> <pre class="example">
-- load required modules -- load required modules
http = require("socket.http") http = require("socket.http")
mime = require("mime") mime = require("mime")
@ -314,10 +316,10 @@ r, c = http.request {
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

100
doc/index.html → docs/index.html
View File

@ -13,17 +13,17 @@
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -36,7 +36,7 @@
<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=whatis>What is LuaSocket?</h2> <h2 id="whatis">What is LuaSocket?</h2>
<p> <p>
LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
@ -53,19 +53,19 @@ and runs well on several Windows and UNIX platforms. </p>
<p> <p>
Among the support modules, the most commonly used implement the Among the support modules, the most commonly used implement the
<a href=smtp.html>SMTP</a> <a href="smtp.html">SMTP</a>
(sending e-mails), (sending e-mails),
<a href=http.html>HTTP</a> <a href="http.html">HTTP</a>
(WWW access) and (WWW access) and
<a href=ftp.html>FTP</a> <a href="ftp.html">FTP</a>
(uploading and downloading files) client (uploading and downloading files) client
protocols. These provide a very natural and generic interface to the protocols. These provide a very natural and generic interface to the
functionality defined by each protocol. functionality defined by each protocol.
In addition, you will find that the In addition, you will find that the
<a href=mime.html>MIME</a> (common encodings), <a href="mime.html">MIME</a> (common encodings),
<a href=url.html>URL</a> <a href="url.html">URL</a>
(anything you could possible want to do with one) and (anything you could possible want to do with one) and
<a href=ltn12.html>LTN12</a> <a href="ltn12.html">LTN12</a>
(filters, sinks, sources and pumps) modules can be very handy. (filters, sinks, sources and pumps) modules can be very handy.
</p> </p>
@ -79,12 +79,12 @@ LuaSocket.
<p> <p>
Copyright &copy; 1999-2013 Diego Nehab. All rights reserved. <br> Copyright &copy; 1999-2013 Diego Nehab. All rights reserved. <br>
Author: <A href="http://www.impa.br/~diego">Diego Nehab</a> Author: <a href="http://www.impa.br/~diego">Diego Nehab</a>
</p> </p>
<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=download>Download</h2> <h2 id="download">Download</h2>
<p> <p>
LuaSocket version 3.0-rc1 is now available for download! LuaSocket version 3.0-rc1 is now available for download!
@ -95,20 +95,20 @@ are it works well on most UNIX distributions and Windows flavors.
<p> <p>
The current version of the library can be found at The current version of the library can be found at
the <a href="https://github.com/diegonehab/luasocket">LuaSocket the <a href="https://github.com/lunarmodules/luasocket">LuaSocket
project page</a> on GitHub. Besides the full C and Lua source code project page</a> on GitHub. Besides the full C and Lua source code
for the library, the distribution contains several examples, for the library, the distribution contains several examples,
this user's manual and basic test procedures. this user's manual and basic test procedures.
</p> </p>
<p> Take a look at the <a <p> Take a look at the <a
href=installation.html>installation</a> section of the href="installation.html">installation</a> section of the
manual to find out how to properly install the library. manual to find out how to properly install the library.
</p> </p>
<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=thanks>Special thanks</h2> <h2 id="thanks">Special thanks</h2>
<p> <p>
This marks the first release of LuaSocket that This marks the first release of LuaSocket that
@ -123,7 +123,7 @@ that has helped bring this library back to life.
<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=new>What's New</h2> <h2 id="new">What's New</h2>
<p> <p>
Main changes for LuaSocket&nbsp;3.0-rc1 are IPv6 support Main changes for LuaSocket&nbsp;3.0-rc1 are IPv6 support
@ -131,58 +131,58 @@ and Lua&nbsp;5.2 compatibility.
</p> </p>
<ul> <ul>
<li> Added: Compatible with Lua&nbsp;5.2 <li> Added: Compatible with Lua&nbsp;5.2</li>
<ul> <ul>
<li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>, <li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>,
package tables will <em>not</em> be exported as globals! package tables will <em>not</em> be exported as globals!</li>
</ul> </ul>
<li> Added: IPv6 support; <li> Added: IPv6 support;</li>
<ul> <ul>
<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses; <li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;</li>
<li> <tt>Getpeername</tt> and <tt>getsockname</tt> support <li> <tt>Getpeername</tt> and <tt>getsockname</tt> support
IPv6 addresses, and return the socket family as a third value; IPv6 addresses, and return the socket family as a third value;</li>
<li> URL module updated to support IPv6 host names; <li> URL module updated to support IPv6 host names;</li>
<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions; <li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;</li>
<li> New <tt>socket.dns.getaddrinfo</tt> and <li> New <tt>socket.dns.getaddrinfo</tt> and
<tt>socket.dns.getnameinfo</tt> functions; <tt>socket.dns.getnameinfo</tt> functions;</li>
</ul> </ul>
<li> Added: <tt>getoption</tt> method; <li> Added: <tt>getoption</tt> method;</li>
<li> Fixed: <tt>url.unescape</tt> was returning additional values; <li> Fixed: <tt>url.unescape</tt> was returning additional values;</li>
<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>, <li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>,
<tt>mime.b64</tt>, and <tt>mime.unb64</tt> could <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could
mistaking their own stack slots for functions arguments; mistaking their own stack slots for functions arguments;</li>
<li> Fixed: Receiving zero-length datagram is now possible; <li> Fixed: Receiving zero-length datagram is now possible;</li>
<li> Improved: Hidden all internal library symbols; <li> Improved: Hidden all internal library symbols;</li>
<li> Improved: Better error messages; <li> Improved: Better error messages;</li>
<li> Improved: Better documentation of socket options. <li> Improved: Better documentation of socket options.</li>
<li> Fixed: manual sample of HTTP authentication now uses correct <li> Fixed: manual sample of HTTP authentication now uses correct
"authorization" header (Alexandre Ittner); "authorization" header (Alexandre Ittner);</li>
<li> Fixed: failure on bind() was destroying the socket (Sam Roberts); <li> Fixed: failure on bind() was destroying the socket (Sam Roberts);</li>
<li> Fixed: receive() returns immediatelly if prefix can satisfy <li> Fixed: receive() returns immediatelly if prefix can satisfy
bytes requested (M Joonas Pihlaja); bytes requested (M Joonas Pihlaja);</li>
<li> Fixed: multicast didn't work on Windows, or anywhere <li> Fixed: multicast didn't work on Windows, or anywhere
else for that matter (Herbert Leuwer, Adrian Sietsma); else for that matter (Herbert Leuwer, Adrian Sietsma);</li>
<li> Fixed: select() now reports an error when called with more <li> Fixed: select() now reports an error when called with more
sockets than FD_SETSIZE (Lorenzo Leonini); sockets than FD_SETSIZE (Lorenzo Leonini);</li>
<li> Fixed: manual links to home.html changed to index.html <li> Fixed: manual links to home.html changed to index.html
(Robert Hahn); (Robert Hahn);</li>
<li> Fixed: mime.unb64() would return an empty string on results that started <li> Fixed: mime.unb64() would return an empty string on results that started
with a null character (Robert Raschke); with a null character (Robert Raschke);</li>
<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray); <li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);</li>
<li> Fixed: calling sleep() with negative numbers could <li> Fixed: calling sleep() with negative numbers could
block forever, wasting CPU. Now it returns immediately (MPB); block forever, wasting CPU. Now it returns immediately (MPB);</li>
<li> Improved: FTP commands are now sent in upper case to <li> Improved: FTP commands are now sent in upper case to
help buggy servers (Anders Eurenius); help buggy servers (Anders Eurenius);</li>
<li> Improved: known headers now sent in canonic <li> Improved: known headers now sent in canonic
capitalization to help buggy servers (Joseph Stewart); capitalization to help buggy servers (Joseph Stewart);</li>
<li> Improved: Clarified tcp:receive() in the manual (MPB); <li> Improved: Clarified tcp:receive() in the manual (MPB);</li>
<li> Improved: Decent makefiles (LHF). <li> Improved: Decent makefiles (LHF).</li>
<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei). <li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).</li>
</ul> </ul>
<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=old>Old Versions</h2> <h2 id="old">Old Versions</h2>
<p> <p>
All previous versions of the LuaSocket library can be downloaded <a All previous versions of the LuaSocket library can be downloaded <a
@ -193,10 +193,10 @@ still available for those that have compatibility issues.
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot; <a href="introduction.html">introduction</a> &middot;

0
doc/installation.html → docs/installation.html
View File

0
doc/introduction.html → docs/introduction.html
View File

136
doc/ltn12.html → docs/ltn12.html
View File

@ -14,17 +14,17 @@ Pump, Support, Library">
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -37,7 +37,7 @@ Pump, Support, Library">
<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=ltn12>LTN12</h2> <h2 id="ltn12">LTN12</h2>
<p> The <tt>ltn12</tt> namespace implements the ideas described in <p> The <tt>ltn12</tt> namespace implements the ideas described in
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
@ -50,7 +50,7 @@ functionality provided by this module.
To obtain the <tt>ltn12</tt> namespace, run: To obtain the <tt>ltn12</tt> namespace, run:
</p> </p>
<pre class=example> <pre class="example">
-- loads the LTN21 module -- loads the LTN21 module
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
</pre> </pre>
@ -61,32 +61,32 @@ local ltn12 = require("ltn12")
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="filter.chain"> <p class="name" id="filter.chain">
ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
[, ... filter<sub>N</sub>]<b>)</b> [, ... filter<sub>N</sub>]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns a filter that passes all data it receives through each of a Returns a filter that passes all data it receives through each of a
series of given filters. series of given filters.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple <tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
filters. filters.
</p> </p>
<p class=return> <p class="return">
The function returns the chained filter. The function returns the chained filter.
</p> </p>
<p class=note> <p class="note">
The nesting of filters can be arbitrary. For instance, the useless filter The nesting of filters can be arbitrary. For instance, the useless filter
below doesn't do anything but return the data that was passed to it, below doesn't do anything but return the data that was passed to it,
unaltered. unaltered.
</p> </p>
<pre class=example> <pre class="example">
-- load required modules -- load required modules
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
local mime = require("mime") local mime = require("mime")
@ -102,26 +102,26 @@ id = ltn12.filter.chain(
<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="filter.cycle"> <p class="name" id="filter.cycle">
ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b> ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns a high-level filter that cycles though a low-level filter by Returns a high-level filter that cycles though a low-level filter by
passing it each chunk and updating a context between calls. passing it each chunk and updating a context between calls.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Low</tt> is the low-level filter to be cycled, <tt>Low</tt> is the low-level filter to be cycled,
<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra <tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra
argument the low-level filter might take. argument the low-level filter might take.
</p> </p>
<p class=return> <p class="return">
The function returns the high-level filter. The function returns the high-level filter.
</p> </p>
<pre class=example> <pre class="example">
-- load the ltn12 module -- load the ltn12 module
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
@ -137,15 +137,15 @@ end
<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="pump.all"> <p class="name" id="pump.all">
ltn12.pump.<b>all(</b>source, sink<b>)</b> ltn12.pump.<b>all(</b>source, sink<b>)</b>
</p> </p>
<p class=description> <p class="description">
Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
</p> </p>
<p class=return> <p class="return">
If successful, the function returns a value that evaluates to If successful, the function returns a value that evaluates to
<b><tt>true</tt></b>. In case <b><tt>true</tt></b>. In case
of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
@ -153,15 +153,15 @@ of error, the function returns a <b><tt>false</tt></b> value, followed by an err
<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="pump.step"> <p class="name" id="pump.step">
ltn12.pump.<b>step(</b>source, sink<b>)</b> ltn12.pump.<b>step(</b>source, sink<b>)</b>
</p> </p>
<p class=description> <p class="description">
Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
</p> </p>
<p class=return> <p class="return">
If successful, the function returns a value that evaluates to If successful, the function returns a value that evaluates to
<b><tt>true</tt></b>. In case <b><tt>true</tt></b>. In case
of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. of error, the function returns a <b><tt>false</tt></b> value, followed by an error message.
@ -173,52 +173,52 @@ of error, the function returns a <b><tt>false</tt></b> value, followed by an err
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="sink.chain"> <p class="name" id="sink.chain">
ltn12.sink.<b>chain(</b>filter, sink<b>)</b> ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>. Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>.
</p> </p>
<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="sink.error"> <p class="name" id="sink.error">
ltn12.sink.<b>error(</b>message<b>)</b> ltn12.sink.<b>error(</b>message<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a sink that aborts transmission with the error Creates and returns a sink that aborts transmission with the error
<tt>message</tt>. <tt>message</tt>.
</p> </p>
<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="sink.file"> <p class="name" id="sink.file">
ltn12.sink.<b>file(</b>handle, message<b>)</b> ltn12.sink.<b>file(</b>handle, message<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates a sink that sends data to a file. Creates a sink that sends data to a file.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
<tt>message</tt> should give the reason for failure. <tt>message</tt> should give the reason for failure.
</p> </p>
<p class=return> <p class="return">
The function returns a sink that sends all data to the given <tt>handle</tt> The function returns a sink that sends all data to the given <tt>handle</tt>
and closes the file when done, or a sink that aborts the transmission with and closes the file when done, or a sink that aborts the transmission with
the error <tt>message</tt> the error <tt>message</tt>
</p> </p>
<p class=note> <p class="note">
In the following example, notice how the prototype is designed to In the following example, notice how the prototype is designed to
fit nicely with the <tt>io.open</tt> function. fit nicely with the <tt>io.open</tt> function.
</p> </p>
<pre class=example> <pre class="example">
-- load the ltn12 module -- load the ltn12 module
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
@ -231,45 +231,45 @@ ltn12.pump.all(
<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="sink.null"> <p class="name" id="sink.null">
ltn12.sink.<b>null()</b> ltn12.sink.<b>null()</b>
</p> </p>
<p class=description> <p class="description">
Returns a sink that ignores all data it receives. Returns a sink that ignores all data it receives.
</p> </p>
<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="sink.simplify"> <p class="name" id="sink.simplify">
ltn12.sink.<b>simplify(</b>sink<b>)</b> ltn12.sink.<b>simplify(</b>sink<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a simple sink given a fancy <tt>sink</tt>. Creates and returns a simple sink given a fancy <tt>sink</tt>.
</p> </p>
<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="sink.table"> <p class="name" id="sink.table">
ltn12.sink.<b>table(</b>[table]<b>)</b> ltn12.sink.<b>table(</b>[table]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates a sink that stores all chunks in a table. The chunks can later be Creates a sink that stores all chunks in a table. The chunks can later be
efficiently concatenated into a single string. efficiently concatenated into a single string.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Table</tt> is used to hold the chunks. If <tt>Table</tt> is used to hold the chunks. If
<tt><b>nil</b></tt>, the function creates its own table. <tt><b>nil</b></tt>, the function creates its own table.
</p> </p>
<p class=return> <p class="return">
The function returns the sink and the table used to store the chunks. The function returns the sink and the table used to store the chunks.
</p> </p>
<pre class=example> <pre class="example">
-- load needed modules -- load needed modules
local http = require("socket.http") local http = require("socket.http")
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
@ -291,89 +291,89 @@ end
<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.cat"> <p class="name" id="source.cat">
ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ..., ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
source<sub>N</sub>]<b>)</b> source<sub>N</sub>]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates a new source that produces the concatenation of the data produced Creates a new source that produces the concatenation of the data produced
by a number of sources. by a number of sources.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original <tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
sources. sources.
</p> </p>
<p class=return> <p class="return">
The function returns the new source. The function returns the new source.
</p> </p>
<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.chain"> <p class="name" id="source.chain">
ltn12.source.<b>chain(</b>source, filter<b>)</b> ltn12.source.<b>chain(</b>source, filter<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
before returning it. before returning it.
</p> </p>
<p class=return> <p class="return">
The function returns the new source. The function returns the new source.
</p> </p>
<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.empty"> <p class="name" id="source.empty">
ltn12.source.<b>empty()</b> ltn12.source.<b>empty()</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns an empty source. Creates and returns an empty source.
</p> </p>
<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.error"> <p class="name" id="source.error">
ltn12.source.<b>error(</b>message<b>)</b> ltn12.source.<b>error(</b>message<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a source that aborts transmission with the error Creates and returns a source that aborts transmission with the error
<tt>message</tt>. <tt>message</tt>.
</p> </p>
<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.file"> <p class="name" id="source.file">
ltn12.source.<b>file(</b>handle, message<b>)</b> ltn12.source.<b>file(</b>handle, message<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates a source that produces the contents of a file. Creates a source that produces the contents of a file.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
<tt>message</tt> should give the reason for failure. <tt>message</tt> should give the reason for failure.
</p> </p>
<p class=return> <p class="return">
The function returns a source that reads chunks of data from The function returns a source that reads chunks of data from
given <tt>handle</tt> and returns it to the user, given <tt>handle</tt> and returns it to the user,
closing the file when done, or a source that aborts the transmission with closing the file when done, or a source that aborts the transmission with
the error <tt>message</tt> the error <tt>message</tt>
</p> </p>
<p class=note> <p class="note">
In the following example, notice how the prototype is designed to In the following example, notice how the prototype is designed to
fit nicely with the <tt>io.open</tt> function. fit nicely with the <tt>io.open</tt> function.
</p> </p>
<pre class=example> <pre class="example">
-- load the ltn12 module -- load the ltn12 module
local ltn12 = require("ltn12") local ltn12 = require("ltn12")
@ -386,41 +386,41 @@ ltn12.pump.all(
<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.simplify"> <p class="name" id="source.simplify">
ltn12.source.<b>simplify(</b>source<b>)</b> ltn12.source.<b>simplify(</b>source<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a simple source given a fancy <tt>source</tt>. Creates and returns a simple source given a fancy <tt>source</tt>.
</p> </p>
<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.string"> <p class="name" id="source.string">
ltn12.source.<b>string(</b>string<b>)</b> ltn12.source.<b>string(</b>string<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a source that produces the contents of a Creates and returns a source that produces the contents of a
<tt>string</tt>, chunk by chunk. <tt>string</tt>, chunk by chunk.
</p> </p>
<!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="source.table"> <p class="name" id="source.table">
ltn12.source.<b>table(</b>table<b>)</b> ltn12.source.<b>table(</b>table<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless. Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless.
</p> </p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

0
doc/lua05.ppt → docs/lua05.ppt
View File

0
doc/luasocket.png → docs/luasocket.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

154
doc/mime.html → docs/mime.html
View File

@ -13,17 +13,17 @@
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -36,7 +36,7 @@
<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=mime>MIME</h2> <h2 id="mime">MIME</h2>
<p> <p>
The <tt>mime</tt> namespace offers filters that apply and remove common The <tt>mime</tt> namespace offers filters that apply and remove common
@ -62,7 +62,7 @@ LTN012, Filters sources and sinks</a>.
To obtain the <tt>mime</tt> namespace, run: To obtain the <tt>mime</tt> namespace, run:
</p> </p>
<pre class=example> <pre class="example">
-- loads the MIME module and everything it requires -- loads the MIME module and everything it requires
local mime = require("mime") local mime = require("mime")
</pre> </pre>
@ -70,40 +70,40 @@ local mime = require("mime")
<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=high>High-level filters</h3> <h3 id="high">High-level filters</h3>
<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="decode"> <p class="name" id="decode">
mime.<b>decode(</b>"base64"<b>)</b><br> mime.<b>decode(</b>"base64"<b>)</b><br>
mime.<b>decode(</b>"quoted-printable"<b>)</b> mime.<b>decode(</b>"quoted-printable"<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns a filter that decodes data from a given transfer content Returns a filter that decodes data from a given transfer content
encoding. encoding.
</p> </p>
<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="encode"> <p class="name" id="encode">
mime.<b>encode(</b>"base64"<b>)</b><br> mime.<b>encode(</b>"base64"<b>)</b><br>
mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b> mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns a filter that encodes data according to a given transfer content Returns a filter that encodes data according to a given transfer content
encoding. encoding.
</p> </p>
<p class=parameters> <p class="parameters">
In the Quoted-Printable case, the user can specify whether the data is In the Quoted-Printable case, the user can specify whether the data is
textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>". "<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
</p> </p>
<p class=note> <p class="note">
Although both transfer content encodings specify a limit for the line Although both transfer content encodings specify a limit for the line
length, the encoding filters do <em>not</em> break text into lines (for length, the encoding filters do <em>not</em> break text into lines (for
added flexibility). added flexibility).
@ -111,19 +111,19 @@ Below is a filter that converts binary data to the Base64 transfer content
encoding and breaks it into lines of the correct size. encoding and breaks it into lines of the correct size.
</p> </p>
<pre class=example> <pre class="example">
base64 = ltn12.filter.chain( base64 = ltn12.filter.chain(
mime.encode("base64"), mime.encode("base64"),
mime.wrap("base64") mime.wrap("base64")
) )
</pre> </pre>
<p class=note> <p class="note">
Note: Text data <em>has</em> to be converted to canonic form Note: Text data <em>has</em> to be converted to canonic form
<em>before</em> being encoded. <em>before</em> being encoded.
</p> </p>
<pre class=example> <pre class="example">
base64 = ltn12.filter.chain( base64 = ltn12.filter.chain(
mime.normalize(), mime.normalize(),
mime.encode("base64"), mime.encode("base64"),
@ -133,24 +133,24 @@ base64 = ltn12.filter.chain(
<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="normalize"> <p class="name" id="normalize">
mime.<b>normalize(</b>[marker]<b>)</b> mime.<b>normalize(</b>[marker]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Converts most common end-of-line markers to a specific given marker. Converts most common end-of-line markers to a specific given marker.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic <tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
end-of-line marker defined by the MIME standard. end-of-line marker defined by the MIME standard.
</p> </p>
<p class=return> <p class="return">
The function returns a filter that performs the conversion. The function returns a filter that performs the conversion.
</p> </p>
<p class=note> <p class="note">
Note: There is no perfect solution to this problem. Different end-of-line Note: There is no perfect solution to this problem. Different end-of-line
markers are an evil that will probably plague developers forever. markers are an evil that will probably plague developers forever.
This function, however, will work perfectly for text created with any of This function, however, will work perfectly for text created with any of
@ -162,33 +162,33 @@ guarantee that the number of empty lines will be correct.
<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="stuff"> <p class="name" id="stuff">
mime.<b>stuff()</b><br> mime.<b>stuff()</b><br>
</p> </p>
<p class=description> <p class="description">
Creates and returns a filter that performs stuffing of SMTP messages. Creates and returns a filter that performs stuffing of SMTP messages.
</p> </p>
<p class=note> <p class="note">
Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
uses this filter automatically. You don't need to chain it with your uses this filter automatically. You don't need to chain it with your
source, or apply it to your message body. source, or apply it to your message body.
</p> </p>
<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="wrap"> <p class="name" id="wrap">
mime.<b>wrap(</b>"text" [, length]<b>)</b><br> mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
mime.<b>wrap(</b>"base64"<b>)</b><br> mime.<b>wrap(</b>"base64"<b>)</b><br>
mime.<b>wrap(</b>"quoted-printable"<b>)</b> mime.<b>wrap(</b>"quoted-printable"<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns a filter that breaks data into lines. Returns a filter that breaks data into lines.
</p> </p>
<p class=parameters> <p class="parameters">
The "<tt>text</tt>" line-wrap filter simply breaks text into lines by The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
inserting CRLF end-of-line markers at appropriate positions. inserting CRLF end-of-line markers at appropriate positions.
<tt>Length</tt> defaults 76. <tt>Length</tt> defaults 76.
@ -199,11 +199,11 @@ not to break lines in the middle of an escaped character. In that case, the
line length is fixed at 76. line length is fixed at 76.
</p> </p>
<p class=note> <p class="note">
For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following: For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
</p> </p>
<pre class=example> <pre class="example">
qp = ltn12.filter.chain( qp = ltn12.filter.chain(
mime.normalize(), mime.normalize(),
mime.encode("quoted-printable"), mime.encode("quoted-printable"),
@ -211,26 +211,26 @@ qp = ltn12.filter.chain(
) )
</pre> </pre>
<p class=note> <p class="note">
Note: To break into lines with a different end-of-line convention, apply Note: To break into lines with a different end-of-line convention, apply
a normalization filter after the line break filter. a normalization filter after the line break filter.
</p> </p>
<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h3 id=low>Low-level filters</h3> <h3 id="low">Low-level filters</h3>
<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="b64"> <p class="name" id="b64">
A, B = mime.<b>b64(</b>C [, D]<b>)</b> A, B = mime.<b>b64(</b>C [, D]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to perform Base64 encoding. Low-level filter to perform Base64 encoding.
</p> </p>
<p class=description> <p class="description">
<tt>A</tt> is the encoded version of the largest prefix of <tt>A</tt> is the encoded version of the largest prefix of
<tt>C..D</tt> <tt>C..D</tt>
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
@ -239,56 +239,56 @@ If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
the encoding of the remaining bytes of <tt>C</tt>. the encoding of the remaining bytes of <tt>C</tt>.
</p> </p>
<p class=note> <p class="note">
Note: The simplest use of this function is to encode a string into it's Note: The simplest use of this function is to encode a string into it's
Base64 transfer content encoding. Notice the extra parenthesis around the Base64 transfer content encoding. Notice the extra parenthesis around the
call to <tt>mime.b64</tt>, to discard the second return value. call to <tt>mime.b64</tt>, to discard the second return value.
</p> </p>
<pre class=example> <pre class="example">
print((mime.b64("diego:password"))) print((mime.b64("diego:password")))
--&gt; ZGllZ286cGFzc3dvcmQ= --&gt; ZGllZ286cGFzc3dvcmQ=
</pre> </pre>
<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="dot"> <p class="name" id="dot">
A, n = mime.<b>dot(</b>m [, B]<b>)</b> A, n = mime.<b>dot(</b>m [, B]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to perform SMTP stuffing and enable transmission of Low-level filter to perform SMTP stuffing and enable transmission of
messages containing the sequence "CRLF.CRLF". messages containing the sequence "CRLF.CRLF".
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the <tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
number of characters from the sequence CRLF seen in the end of <tt>B</tt>. number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
'<tt>m</tt>' should tell the same, but for the previous chunk. '<tt>m</tt>' should tell the same, but for the previous chunk.
</p> </p>
<p class=note>Note: The message body is defined to begin with <p class="note">Note: The message body is defined to begin with
an implicit CRLF. Therefore, to stuff a message correctly, the an implicit CRLF. Therefore, to stuff a message correctly, the
first <tt>m</tt> should have the value 2. first <tt>m</tt> should have the value 2.
</p> </p>
<pre class=example> <pre class="example">
print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n"))) print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
--&gt; ..\nStuffing the message.\n..\n.. --&gt; ..\nStuffing the message.\n..\n..
</pre> </pre>
<p class=note> <p class="note">
Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
uses this filter automatically. You don't need to uses this filter automatically. You don't need to
apply it again. apply it again.
</p> </p>
<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="eol"> <p class="name" id="eol">
A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b> A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to perform end-of-line marker translation. Low-level filter to perform end-of-line marker translation.
For each chunk, the function needs to know if the last character of the For each chunk, the function needs to know if the last character of the
previous chunk could be part of an end-of-line marker or not. This is the previous chunk could be part of an end-of-line marker or not. This is the
@ -296,7 +296,7 @@ context the function receives besides the chunk. An updated version of
the context is returned after each new chunk. the context is returned after each new chunk.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the <tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
ASCII value of the last character of the previous chunk, if it was a ASCII value of the last character of the previous chunk, if it was a
candidate for line break, or 0 otherwise. candidate for line break, or 0 otherwise.
@ -304,22 +304,22 @@ candidate for line break, or 0 otherwise.
chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF. chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
</p> </p>
<pre class=example> <pre class="example">
-- translates the end-of-line marker to UNIX -- translates the end-of-line marker to UNIX
unix = mime.eol(0, dos, "\n") unix = mime.eol(0, dos, "\n")
</pre> </pre>
<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="qp"> <p class="name" id="qp">
A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b> A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to perform Quoted-Printable encoding. Low-level filter to perform Quoted-Printable encoding.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is the encoded version of the largest prefix of <tt>A</tt> is the encoded version of the largest prefix of
<tt>C..D</tt> <tt>C..D</tt>
that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
@ -330,28 +330,28 @@ Throughout encoding, occurrences of CRLF are replaced by the
<tt>marker</tt>, which itself defaults to CRLF. <tt>marker</tt>, which itself defaults to CRLF.
</p> </p>
<p class=note> <p class="note">
Note: The simplest use of this function is to encode a string into it's Note: The simplest use of this function is to encode a string into it's
Quoted-Printable transfer content encoding. Quoted-Printable transfer content encoding.
Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value. Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
</p> </p>
<pre class=example> <pre class="example">
print((mime.qp("maçã"))) print((mime.qp("ma<EFBFBD><EFBFBD>")))
--&gt; ma=E7=E3= --&gt; ma=E7=E3=
</pre> </pre>
<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="qpwrp"> <p class="name" id="qpwrp">
A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b> A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to break Quoted-Printable text into lines. Low-level filter to break Quoted-Printable text into lines.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
<tt>length</tt> bytes (defaults to 76). <tt>length</tt> bytes (defaults to 76).
'<tt>n</tt>' should tell how many bytes are left for the first '<tt>n</tt>' should tell how many bytes are left for the first
@ -359,7 +359,7 @@ line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
left in the last line of <tt>A</tt>. left in the last line of <tt>A</tt>.
</p> </p>
<p class=note> <p class="note">
Note: Besides breaking text into lines, this function makes sure the line Note: Besides breaking text into lines, this function makes sure the line
breaks don't fall in the middle of an escaped character combination. Also, breaks don't fall in the middle of an escaped character combination. Also,
this function only breaks lines that are bigger than <tt>length</tt> bytes. this function only breaks lines that are bigger than <tt>length</tt> bytes.
@ -367,15 +367,15 @@ this function only breaks lines that are bigger than <tt>length</tt> bytes.
<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="unb64"> <p class="name" id="unb64">
A, B = mime.<b>unb64(</b>C [, D]<b>)</b> A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to perform Base64 decoding. Low-level filter to perform Base64 decoding.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is the decoded version of the largest prefix of <tt>A</tt> is the decoded version of the largest prefix of
<tt>C..D</tt> <tt>C..D</tt>
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
@ -384,29 +384,29 @@ If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
and <tt>B</tt> returns whatever couldn't be decoded. and <tt>B</tt> returns whatever couldn't be decoded.
</p> </p>
<p class=note> <p class="note">
Note: The simplest use of this function is to decode a string from it's Note: The simplest use of this function is to decode a string from it's
Base64 transfer content encoding. Base64 transfer content encoding.
Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
</p> </p>
<pre class=example> <pre class="example">
print((mime.unb64("ZGllZ286cGFzc3dvcmQ="))) print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
--&gt; diego:password --&gt; diego:password
</pre> </pre>
<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="unqp"> <p class="name" id="unqp">
A, B = mime.<b>unqp(</b>C [, D]<b>)</b> A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to remove the Quoted-Printable transfer content encoding Low-level filter to remove the Quoted-Printable transfer content encoding
from data. from data.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is the decoded version of the largest prefix of <tt>A</tt> is the decoded version of the largest prefix of
<tt>C..D</tt> <tt>C..D</tt>
that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
@ -415,29 +415,29 @@ If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
the encoding of the remaining bytes of <tt>C</tt>. the encoding of the remaining bytes of <tt>C</tt>.
</p> </p>
<p class=note> <p class="note">
Note: The simplest use of this function is to decode a string from it's Note: The simplest use of this function is to decode a string from it's
Quoted-Printable transfer content encoding. Quoted-Printable transfer content encoding.
Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
</p> </p>
<pre class=example> <pre class="example">
print((mime.qp("ma=E7=E3="))) print((mime.qp("ma=E7=E3=")))
--&gt; maçã --&gt; ma<EFBFBD><EFBFBD>
</pre> </pre>
<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="wrp"> <p class="name" id="wrp">
A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b> A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Low-level filter to break text into lines with CRLF marker. Low-level filter to break text into lines with CRLF marker.
Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form. Text is assumed to be in the <a href="#normalize"><tt>normalize</tt></a> form.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
<tt>length</tt> bytes (defaults to 76). <tt>length</tt> bytes (defaults to 76).
'<tt>n</tt>' should tell how many bytes are left for the first '<tt>n</tt>' should tell how many bytes are left for the first
@ -445,7 +445,7 @@ line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
left in the last line of <tt>A</tt>. left in the last line of <tt>A</tt>.
</p> </p>
<p class=note> <p class="note">
Note: This function only breaks lines that are bigger than Note: This function only breaks lines that are bigger than
<tt>length</tt> bytes. The resulting line length does not include the CRLF <tt>length</tt> bytes. The resulting line length does not include the CRLF
marker. marker.
@ -454,10 +454,10 @@ marker.
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

0
doc/reference.css → docs/reference.css
View File

14
doc/reference.html → docs/reference.html
View File

@ -14,17 +14,17 @@ Support, Manual">
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -238,10 +238,10 @@ Support, Manual">
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

101
doc/smtp.html → docs/smtp.html
View File

@ -14,17 +14,17 @@ Library, Support">
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -37,7 +37,7 @@ Library, Support">
<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=smtp>SMTP</h2> <h2 id="smtp">SMTP</h2>
<p> The <tt>smtp</tt> namespace provides functionality to send e-mail <p> The <tt>smtp</tt> namespace provides functionality to send e-mail
messages. The high-level API consists of two functions: one to messages. The high-level API consists of two functions: one to
@ -54,11 +54,11 @@ href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>,
which governs the Internet Message Format. which governs the Internet Message Format.
Multipart messages (those that contain attachments) are part Multipart messages (those that contain attachments) are part
of the MIME standard, but described mainly of the MIME standard, but described mainly
in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a> in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>.</p>
<p> In the description below, good understanding of <a <p> In the description below, good understanding of <a
href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
sources and sinks</a> and the <a href=mime.html>MIME</a> module is sources and sinks</a> and the <a href="mime.html">MIME</a> module is
assumed. In fact, the SMTP module was the main reason for their assumed. In fact, the SMTP module was the main reason for their
creation. </p> creation. </p>
@ -66,7 +66,7 @@ creation. </p>
To obtain the <tt>smtp</tt> namespace, run: To obtain the <tt>smtp</tt> namespace, run:
</p> </p>
<pre class=example> <pre class="example">
-- loads the SMTP module and everything it requires -- loads the SMTP module and everything it requires
local smtp = require("socket.smtp") local smtp = require("socket.smtp")
</pre> </pre>
@ -92,11 +92,11 @@ headers = {<br>
<p> <p>
Field names are case insensitive (as specified by the standard) and all Field names are case insensitive (as specified by the standard) and all
functions work with lowercase field names (but see functions work with lowercase field names (but see
<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). <a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
Field values are left unmodified. Field values are left unmodified.
</p> </p>
<p class=note> <p class="note">
Note: MIME headers are independent of order. Therefore, there is no problem Note: MIME headers are independent of order. Therefore, there is no problem
in representing them in a Lua table. in representing them in a Lua table.
</p> </p>
@ -107,25 +107,25 @@ the SMTP module:
</p> </p>
<ul> <ul>
<li> <tt>DOMAIN</tt>: domain used to greet the server; <li> <tt>DOMAIN</tt>: domain used to greet the server;</li>
<li> <tt>PORT</tt>: default port used for the connection; <li> <tt>PORT</tt>: default port used for the connection;</li>
<li> <tt>SERVER</tt>: default server used for the connection; <li> <tt>SERVER</tt>: default server used for the connection;</li>
<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations; <li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;</li>
<li> <tt>ZONE</tt>: default time zone. <li> <tt>ZONE</tt>: default time zone.</li>
</ul> </ul>
<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=message> <p class="name" id="message">
smtp.<b>message(</b>mesgt<b>)</b> smtp.<b>message(</b>mesgt<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns a <em>simple</em> 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). <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
</p> </p>
<p class=parameters> <p class="parameters">
The only parameter of the function is a table describing the message. The only parameter of the function is a table describing the message.
<tt>Mesgt</tt> has the following form (notice the recursive structure): <tt>Mesgt</tt> has the following form (notice the recursive structure):
</p> </p>
@ -151,7 +151,7 @@ multipart-mesgt = {<br>
</table> </table>
</blockquote> </blockquote>
<p class=parameters> <p class="parameters">
For a simple message, all that is needed is a set of <tt>headers</tt> 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 and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
or as a <em>simple</em> or as a <em>simple</em>
@ -161,7 +161,7 @@ recursively defines each part as an independent message, plus an optional
<tt>preamble</tt> and <tt>epilogue</tt>. <tt>preamble</tt> and <tt>epilogue</tt>.
</p> </p>
<p class=return> <p class="return">
The function returns a <em>simple</em> The function returns a <em>simple</em>
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
source that produces the source that produces the
@ -170,7 +170,7 @@ Hopefully, the following
example will make things clear. When in doubt, refer to the appropriate RFC example will make things clear. When in doubt, refer to the appropriate RFC
as listed in the introduction. </p> as listed in the introduction. </p>
<pre class=example> <pre class="example">
-- load the smtp support and its friends -- load the smtp support and its friends
local smtp = require("socket.smtp") local smtp = require("socket.smtp")
local mime = require("mime") local mime = require("mime")
@ -234,7 +234,7 @@ r, e = smtp.send{
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=send> <p class="name" id="send">
smtp.<b>send{</b><br> smtp.<b>send{</b><br>
&nbsp;&nbsp;from = <i>string</i>,<br> &nbsp;&nbsp;from = <i>string</i>,<br>
&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br> &nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
@ -249,16 +249,16 @@ smtp.<b>send{</b><br>
<b>}</b> <b>}</b>
</p> </p>
<p class=description> <p class="description">
Sends a message to a recipient list. Since sending messages is not as Sends a message to a recipient list. Since sending messages is not as
simple as downloading an URL from a FTP or HTTP server, this function simple as downloading an URL from a FTP or HTTP server, this function
doesn't have a simple interface. However, see the doesn't have a simple interface. However, see the
<a href=#message><tt>message</tt></a> source factory for <a href="#message"><tt>message</tt></a> source factory for
a very powerful way to define the message contents. a very powerful way to define the message contents.
</p> </p>
<p class=parameters> <p class="parameters">
The sender is given by the e-mail address in the <tt>from</tt> field. The sender is given by the e-mail address in the <tt>from</tt> field.
<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail <tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
address, or a string address, or a string
@ -270,32 +270,32 @@ The contents of the message are given by a <em>simple</em>
<ul> <ul>
<li> <tt>user</tt>, <tt>password</tt>: User and password for <li> <tt>user</tt>, <tt>password</tt>: User and password for
authentication. The function will attempt LOGIN and PLAIN authentication authentication. The function will attempt LOGIN and PLAIN authentication
methods if supported by the server (both are unsafe); methods if supported by the server (both are unsafe);</li>
<li> <tt>server</tt>: Server to connect to. Defaults to "localhost"; <li> <tt>server</tt>: Server to connect to. Defaults to "localhost";</li>
<li> <tt>port</tt>: Port to connect to. Defaults to 25; <li> <tt>port</tt>: Port to connect to. Defaults to 25;</li>
<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the <li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
local machine host name; local machine host name;</li>
<li> <tt>step</tt>: <li> <tt>step</tt>:
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
pump step function used to pass data from the pump step function used to pass data from the
source to the server. Defaults to the LTN12 <tt>pump.step</tt> function; source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
<li><tt>create</tt>: An optional function to be used instead of <li><tt>create</tt>: An optional function to be used instead of
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
</ul> </ul>
<p class=return> <p class="return">
If successful, the function returns 1. Otherwise, the function returns If successful, the function returns 1. Otherwise, the function returns
<b><tt>nil</tt></b> followed by an error message. <b><tt>nil</tt></b> followed by an error message.
</p> </p>
<p class=note> <p class="note">
Note: SMTP servers can be very picky with the format of e-mail Note: SMTP servers can be very picky with the format of e-mail
addresses. To be safe, use only addresses of the form addresses. To be safe, use only addresses of the form
"<tt>&lt;fulano@example.com&gt;</tt>" in the <tt>from</tt> and "<tt>&lt;fulano@example.com&gt;</tt>" in the <tt>from</tt> and
<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail <tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail
addresses can take whatever form you like. </p> addresses can take whatever form you like. </p>
<p class=note> <p class="note">
Big note: There is a good deal of misconception with the use of the Big note: There is a good deal of misconception with the use of the
destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
@ -303,7 +303,7 @@ and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
exact opposite of what you expect. exact opposite of what you expect.
</p> </p>
<p class=note> <p class="note">
Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the
message. Each recipient of an SMTP mail message receives a copy of the message. Each recipient of an SMTP mail message receives a copy of the
message body along with the headers, and nothing more. The headers message body along with the headers, and nothing more. The headers
@ -313,7 +313,7 @@ message body along with the headers, and nothing more. The headers
part of the message and will not be sent to anyone. part of the message and will not be sent to anyone.
</p> </p>
<p class=note> <p class="note">
<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>
has two <em>important and short</em> sections, "3.6.3. Destination address has two <em>important and short</em> sections, "3.6.3. Destination address
fields" and "5. Security considerations", explaining the proper fields" and "5. Security considerations", explaining the proper
@ -322,16 +322,17 @@ use of these headers. Here is a summary of what it says:
<ul> <ul>
<li> <tt>To</tt>: contains the address(es) of the primary recipient(s) <li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
of the message; of the message;</li>
<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of <li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
making a copy on a typewriter using carbon paper) contains the making a copy on a typewriter using carbon paper) contains the
addresses of others who are to receive the message, though the addresses of others who are to receive the message, though the
content of the message may not be directed at them; content of the message may not be directed at them;</li>
<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon <li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message. Copy") contains addresses of recipients of the message whose addresses are not
to be revealed to other recipients of the message.</li>
</ul> </ul>
<p class=note> <p class="note">
The LuaSocket <tt>send</tt> function does not care or interpret the The LuaSocket <tt>send</tt> function does not care or interpret the
headers you send, but it gives you full control over what is sent and headers you send, but it gives you full control over what is sent and
to whom it is sent: to whom it is sent:
@ -339,27 +340,27 @@ to whom it is sent:
<ul> <ul>
<li> If someone is to receive the message, the e-mail address <em>has</em> <li> If someone is to receive the message, the e-mail address <em>has</em>
to be in the recipient list. This is the only parameter that controls who to be in the recipient list. This is the only parameter that controls who
gets a copy of the message; gets a copy of the message;</li>
<li> If there are multiple recipients, none of them will automatically <li> If there are multiple recipients, none of them will automatically
know that someone else got that message. That is, the default behavior is know that someone else got that message. That is, the default behavior is
similar to the <tt>Bcc</tt> field of popular e-mail clients; similar to the <tt>Bcc</tt> field of popular e-mail clients;</li>
<li> It is up to you to add the <tt>To</tt> header with the list of primary <li> It is up to you to add the <tt>To</tt> header with the list of primary
recipients so that other recipients can see it; recipients so that other recipients can see it;</li>
<li> It is also up to you to add the <tt>Cc</tt> header with the <li> It is also up to you to add the <tt>Cc</tt> header with the
list of additional recipients so that everyone else sees it; list of additional recipients so that everyone else sees it;</li>
<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is <li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
empty. Otherwise, everyone receiving the message will see it and that is empty. Otherwise, everyone receiving the message will see it and that is
exactly what you <em>don't</em> want to happen! exactly what you <em>don't</em> want to happen!</li>
</ul> </ul>
<p class=note> <p class="note">
I hope this clarifies the issue. Otherwise, please refer to I hope this clarifies the issue. Otherwise, please refer to
<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> <a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>
and and
<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>.
</p> </p>
<pre class=example> <pre class="example">
-- load the smtp support -- load the smtp support
local smtp = require("socket.smtp") local smtp = require("socket.smtp")
@ -395,10 +396,10 @@ r, e = smtp.send{
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

180
doc/socket.html → docs/socket.html
View File

@ -13,17 +13,17 @@
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="https://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -36,7 +36,7 @@
<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<h2 id=socket>The socket namespace</h2> <h2 id="socket">The socket namespace</h2>
<p> <p>
The <tt>socket</tt> namespace contains the core functionality of LuaSocket. The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
@ -46,14 +46,14 @@ The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
To obtain the <tt>socket</tt> namespace, run: To obtain the <tt>socket</tt> namespace, run:
</p> </p>
<pre class=example> <pre class="example">
-- loads the socket module -- loads the socket module
local socket = require("socket") local socket = require("socket")
</pre> </pre>
<!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="headers.canonic"> <p class="name" id="headers.canonic">
socket.headers.<b>canonic</b></p> socket.headers.<b>canonic</b></p>
<p> The <tt>socket.headers.canonic</tt> table <p> The <tt>socket.headers.canonic</tt> table
@ -69,7 +69,7 @@ You can obtain the <tt>headers</tt> namespace if case run-time
modifications are required by running: modifications are required by running:
</p> </p>
<pre class=example> <pre class="example">
-- loads the headers module -- loads the headers module
local headers = require("headers") local headers = require("headers")
</pre> </pre>
@ -77,30 +77,30 @@ local headers = require("headers")
<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=bind> <p class="name" id="bind">
socket.<b>bind(</b>address, port [, backlog]<b>)</b> socket.<b>bind(</b>address, port [, backlog]<b>)</b>
</p> </p>
<p class=description> <p class="description">
This function is a shortcut that creates and returns a TCP server object 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 bound to a local <tt>address</tt> and <tt>port</tt>, ready to
accept client connections. Optionally, accept client connections. Optionally,
user can also specify the <tt>backlog</tt> argument to the user can also specify the <tt>backlog</tt> argument to the
<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32). <a href="tcp.html#listen"><tt>listen</tt></a> method (defaults to 32).
</p> </p>
<p class=note> <p class="note">
Note: The server object returned will have the option "<tt>reuseaddr</tt>" Note: The server object returned will have the option "<tt>reuseaddr</tt>"
set to <tt><b>true</b></tt>. set to <tt><b>true</b></tt>.
</p> </p>
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=connect> <p class="name" id="connect">
socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
</p> </p>
<p class=description> <p class="description">
This function is a shortcut that creates and returns a TCP client object This function is a shortcut that creates and returns a TCP client object
connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally,
the user can also specify the local address and port to bind the user can also specify the local address and port to bind
@ -114,40 +114,40 @@ of connect are defined as simple helper functions that restrict the
<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=debug> <p class="name" id="debug">
socket.<b>_DEBUG</b> socket.<b>_DEBUG</b>
</p> </p>
<p class=description> <p class="description">
This constant is set to <tt><b>true</b></tt> if the library was compiled This constant is set to <tt><b>true</b></tt> if the library was compiled
with debug support. with debug support.
</p> </p>
<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=debug> <p class="name" id="datagramsize">
socket.<b>_DATAGRAMSIZE</b> socket.<b>_DATAGRAMSIZE</b>
</p> </p>
<p class=description> <p class="description">
Default datagram size used by calls to Default datagram size used by calls to
<a href="udp.html#receive"<tt>receive</tt></a> and <a href="udp.html#receive"><tt>receive</tt></a> and
<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. <a href="udp.html#receivefrom"><tt>receivefrom</tt></a>.
(Unless changed in compile time, the value is 8192.) (Unless changed in compile time, the value is 8192.)
</p> </p>
<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=gettime> <p class="name" id="gettime">
socket.<b>gettime()</b> socket.<b>gettime()</b>
</p> </p>
<p class=description> <p class="description">
Returns the UNIX time in seconds. You should subtract the values returned by this function Returns the UNIX time in seconds. You should subtract the values returned by this function
to get meaningful values. to get meaningful values.
</p> </p>
<pre class=example> <pre class="example">
t = socket.gettime() t = socket.gettime()
-- do stuff -- do stuff
print(socket.gettime() - t .. " seconds elapsed") print(socket.gettime() - t .. " seconds elapsed")
@ -155,32 +155,32 @@ print(socket.gettime() - t .. " seconds elapsed")
<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=newtry> <p class="name" id="newtry">
socket.<b>newtry(</b>finalizer<b>)</b> socket.<b>newtry(</b>finalizer<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns a <em>clean</em> Creates and returns a <em>clean</em>
<a href="#try"><tt>try</tt></a> <a href="#try"><tt>try</tt></a>
function that allows for cleanup before the exception function that allows for cleanup before the exception
is raised. is raised.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Finalizer</tt> is a function that will be called before <tt>Finalizer</tt> is a function that will be called before
<tt>try</tt> throws the exception. <tt>try</tt> throws the exception.
</p> </p>
<p class=return> <p class="return">
The function returns your customized <tt>try</tt> function. The function returns your customized <tt>try</tt> function.
</p> </p>
<p class=note> <p class="note">
Note: This idea saved a <em>lot</em> of work with the Note: This idea saved a <em>lot</em> of work with the
implementation of protocols in LuaSocket: implementation of protocols in LuaSocket:
</p> </p>
<pre class=example> <pre class="example">
foo = socket.protect(function() foo = socket.protect(function()
-- connect somewhere -- connect somewhere
local c = socket.try(socket.connect("somewhere", 42)) local c = socket.try(socket.connect("somewhere", 42))
@ -198,40 +198,40 @@ end)
<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=protect> <p class="name" id="protect">
socket.<b>protect(</b>func<b>)</b> socket.<b>protect(</b>func<b>)</b>
</p> </p>
<p class=description> <p class="description">
Converts a function that throws exceptions into a safe function. This 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> 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 and <a href="#newtry"><tt>newtry</tt></a> functions. It does not catch normal
Lua errors. Lua errors.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Func</tt> is a function that calls <tt>Func</tt> is a function that calls
<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) <a href="#try"><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
to throw exceptions. to throw exceptions.
</p> </p>
<p class=return> <p class="return">
Returns an equivalent function that instead of throwing exceptions in case of 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> a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt>
followed by an error message. followed by an error message.
</p> </p>
<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=select> <p class="name" id="select">
socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Waits for a number of sockets to change status. Waits for a number of sockets to change status.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Recvt</tt> is an array with the sockets to test for characters <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 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 see if it is OK to immediately write on them. <tt>Timeout</tt> is the
@ -242,7 +242,7 @@ 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. non-numeric indices) in the arrays will be silently ignored.
</p> </p>
<p class=return> The function returns a list with the sockets ready for <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. reading, a list with the sockets ready for writing and an error message.
The error message is "<tt>timeout</tt>" if a timeout The error message is "<tt>timeout</tt>" if a timeout
condition was met, "<tt>select failed</tt>" if the call condition was met, "<tt>select failed</tt>" if the call
@ -253,213 +253,215 @@ themselves, to simplify the test if a specific socket has
changed status. changed status.
</p> </p>
<p class=note> <p class="note">
<b>Note:</b> <tt>select</tt> can monitor a limited number <b>Note:</b> <tt>select</tt> can monitor a limited number
of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This of sockets, as defined by the constant <a href="#setsize">
<tt>socket._SETSIZE</tt></a>. This
number may be as high as 1024 or as low as 64 by default, 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 depending on the system. It is usually possible to change this
at compile time. Invoking <tt>select</tt> with a larger at compile time. Invoking <tt>select</tt> with a larger
number of sockets will raise an error. number of sockets will raise an error.
</p> </p>
<p class=note> <p class="note">
<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
on non-blocking TCP sockets. The function may return a socket as on non-blocking TCP sockets. The function may return a socket as
writable even though the socket is <em>not</em> ready for sending. writable even though the socket is <em>not</em> ready for sending.
</p> </p>
<p class=note> <p class="note">
<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 <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
<a href=tcp.html#accept><tt>accept</tt></a> will return immediately. <a href="tcp.html#accept"><tt>accept</tt></a> will return immediately.
Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a> Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a>
method or <tt>accept</tt> might block forever. method or <tt>accept</tt> might block forever.
</p> </p>
<p class=note> <p class="note">
<b>Yet another note</b>: If you close a socket and pass <b>Yet another note</b>: If you close a socket and pass
it to <tt>select</tt>, it will be ignored. it to <tt>select</tt>, it will be ignored.
</p> </p>
<p class=note> <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. <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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=setsize> <p class="name" id="setsize">
socket.<b>_SETSIZE</b> socket.<b>_SETSIZE</b>
</p> </p>
<p class=description> <p class="description">
The maximum number of sockets that the <a The maximum number of sockets that the <a
href=#select><tt>select</tt></a> function can handle. href="#select"><tt>select</tt></a> function can handle.
</p> </p>
<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=sink> <p class="name" id="sink">
socket.<b>sink(</b>mode, socket<b>)</b> socket.<b>sink(</b>mode, socket<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates an Creates an
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
sink from a stream socket object. sink from a stream socket object.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Mode</tt> defines the behavior of the sink. The following <tt>Mode</tt> defines the behavior of the sink. The following
options are available: options are available:
</p> </p>
<ul> <ul>
<li> <tt>"http-chunked"</tt>: sends data through socket after applying the <li> <tt>"http-chunked"</tt>: sends data through socket after applying the
<em>chunked transfer coding</em>, closing the socket when done; <em>chunked transfer coding</em>, closing the socket when done;</li>
<li> <tt>"close-when-done"</tt>: sends all received data through the <li> <tt>"close-when-done"</tt>: sends all received data through the
socket, closing the socket when done; socket, closing the socket when done;</li>
<li> <tt>"keep-open"</tt>: sends all received data through the <li> <tt>"keep-open"</tt>: sends all received data through the
socket, leaving it open when done. socket, leaving it open when done.</li>
</ul> </ul>
<p> <p>
<tt>Socket</tt> is the stream socket object used to send the data. <tt>Socket</tt> is the stream socket object used to send the data.
</p> </p>
<p class=return> <p class="return">
The function returns a sink with the appropriate behavior. The function returns a sink with the appropriate behavior.
</p> </p>
<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=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> socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Drops a number of arguments and returns the remaining. Drops a number of arguments and returns the remaining.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to <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. <tt>ret<sub>N</sub></tt> are the arguments.
</p> </p>
<p class=return> <p class="return">
The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
</p> </p>
<p class=note> <p class="note">
Note: This function is useful to avoid creation of dummy variables: Note: This function is useful to avoid creation of dummy variables:
</p> </p>
<pre class=example> <pre class="example">
-- get the status code and separator from SMTP server reply -- get the status code and separator from SMTP server reply
local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
</pre> </pre>
<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=sleep> <p class="name" id="sleep">
socket.<b>sleep(</b>time<b>)</b> socket.<b>sleep(</b>time<b>)</b>
</p> </p>
<p class=description> <p class="description">
Freezes the program execution during a given amount of time. Freezes the program execution during a given amount of time.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Time</tt> is the number of seconds to sleep for. If <tt>Time</tt> is the number of seconds to sleep for. If
<tt>time</tt> is negative, the function returns immediately. <tt>time</tt> is negative, the function returns immediately.
</p> </p>
<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=source> <p class="name" id="source">
socket.<b>source(</b>mode, socket [, length]<b>)</b> socket.<b>source(</b>mode, socket [, length]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Creates an Creates an
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
source from a stream socket object. source from a stream socket object.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Mode</tt> defines the behavior of the source. The following <tt>Mode</tt> defines the behavior of the source. The following
options are available: options are available:
</p> </p>
<ul> <ul>
<li> <tt>"http-chunked"</tt>: receives data from socket and removes the <li> <tt>"http-chunked"</tt>: receives data from socket and removes the
<em>chunked transfer coding</em> before returning the data; <em>chunked transfer coding</em> before returning the data;</li>
<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
socket. This mode requires the extra argument <tt>length</tt>; socket. This mode requires the extra argument <tt>length</tt>;</li>
<li> <tt>"until-closed"</tt>: receives data from a socket until the other <li> <tt>"until-closed"</tt>: receives data from a socket until the other
side closes the connection. side closes the connection.</li>
</ul> </ul>
<p> <p>
<tt>Socket</tt> is the stream socket object used to receive the data. <tt>Socket</tt> is the stream socket object used to receive the data.
</p> </p>
<p class=return> <p class="return">
The function returns a source with the appropriate behavior. The function returns a source with the appropriate behavior.
</p> </p>
<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=socketinvalid> <p class="name" id="socketinvalid">
socket.<b>_SOCKETINVALID</b> socket.<b>_SOCKETINVALID</b>
</p> </p>
<p class=description> <p class="description">
The OS value for an invalid socket. The OS value for an invalid socket. This can be used with <a href="tcp.html#getfd">
<tt>tcp:getfd</tt></a> and <a href="tcp.html#setfd"><tt>tcp:setfd</tt></a> methods.
</p> </p>
<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=try> <p class="name" id="try">
socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using 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 <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. by a <a href="#protect"><tt>protect</tt></a>ed function only.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
arguments, but are usually the return values of a function call arguments, but are usually the return values of a function call
nested with <tt>try</tt>. nested with <tt>try</tt>.
</p> </p>
<p class=return> <p class="return">
The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. <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 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 in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to
distinguish exceptions from runtime errors. distinguish exceptions from runtime errors.
</p> </p>
<pre class=example> <pre class="example">
-- connects or throws an exception with the appropriate error message -- connects or throws an exception with the appropriate error message
c = socket.try(socket.connect("localhost", 80)) c = socket.try(socket.connect("localhost", 80))
</pre> </pre>
<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id=version> <p class="name" id="version">
socket.<b>_VERSION</b> socket.<b>_VERSION</b>
</p> </p>
<p class=description> <p class="description">
This constant has a string describing the current LuaSocket version. This constant has a string describing the current LuaSocket version.
</p> </p>
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

333
doc/tcp.html → docs/tcp.html
View File

@ -13,17 +13,17 @@
<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -40,42 +40,43 @@
<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="accept"> <p class="name" id="accept">
server:<b>accept()</b> server:<b>accept()</b>
</p> </p>
<p class=description> <p class="description">
Waits for a remote connection on the server Waits for a remote connection on the server
object and returns a client object representing that connection. object and returns a client object representing that connection.
</p> </p>
<p class=return> <p class="return">
If a connection is successfully initiated, a client object is returned. If a connection is successfully initiated, a client object is returned.
If a timeout condition is met, the method returns <b><tt>nil</tt></b> If a timeout condition is met, the method returns <b><tt>nil</tt></b>
followed by the error string '<tt>timeout</tt>'. Other errors are followed by the error string '<tt>timeout</tt>'. Other errors are
reported by <b><tt>nil</tt></b> followed by a message describing the error. reported by <b><tt>nil</tt></b> followed by a message describing the error.
</p> </p>
<p class=note> <p class="note">
Note: calling <a href=socket.html#select><tt>socket.select</tt></a> Note: calling <a href="socket.html#select"><tt>socket.select</tt></a>
with a server object in with a server object in
the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does
<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a <em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt> href="#settimeout"><tt>settimeout</tt></a> method or <tt>accept</tt>
might block until <em>another</em> client shows up. might block until <em>another</em> client shows up.
</p> </p>
<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="bind"> <p class="name" id="bind">
master:<b>bind(</b>address, port<b>)</b> master:<b>bind(</b>address, port<b>)</b>
</p> </p>
<p class=description> <p class="description">
Binds a master object to <tt>address</tt> and <tt>port</tt> on the Binds a master object to <tt>address</tt> and <tt>port</tt> on the
local host. local host.
</p>
<p class=parameters> <p class="parameters">
<tt>Address</tt> can be an IP address or a host name. <tt>Address</tt> can be an IP address or a host name.
<tt>Port</tt> must be an integer number in the range [0..64K). <tt>Port</tt> must be an integer number in the range [0..64K).
If <tt>address</tt> If <tt>address</tt>
@ -86,25 +87,25 @@ If <tt>port</tt> is 0, the system automatically
chooses an ephemeral port. chooses an ephemeral port.
</p> </p>
<p class=return> <p class="return">
In case of success, the method returns 1. In case of error, the In case of success, the method returns 1. In case of error, the
method returns <b><tt>nil</tt></b> followed by an error message. method returns <b><tt>nil</tt></b> followed by an error message.
</p> </p>
<p class=note> <p class="note">
Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a> Note: The function <a href="socket.html#bind"><tt>socket.bind</tt></a>
is available and is a shortcut for the creation of server sockets. is available and is a shortcut for the creation of server sockets.
</p> </p>
<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="close"> <p class="name" id="close">
master:<b>close()</b><br> master:<b>close()</b><br>
client:<b>close()</b><br> client:<b>close()</b><br>
server:<b>close()</b> server:<b>close()</b>
</p> </p>
<p class=description> <p class="description">
Closes a TCP object. The internal socket used by the object is closed Closes a TCP object. The internal socket used by the object is closed
and the local address to which the object was and the local address to which the object was
bound is made available to other applications. No further operations bound is made available to other applications. No further operations
@ -112,7 +113,7 @@ bound is made available to other applications. No further operations
a closed socket. a closed socket.
</p> </p>
<p class=note> <p class="note">
Note: It is important to close all used sockets once they are not Note: It is important to close all used sockets once they are not
needed, since, in many systems, each socket uses a file descriptor, needed, since, in many systems, each socket uses a file descriptor,
which are limited system resources. Garbage-collected objects are which are limited system resources. Garbage-collected objects are
@ -121,53 +122,53 @@ automatically closed before destruction, though.
<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="connect"> <p class="name" id="connect">
master:<b>connect(</b>address, port<b>)</b> master:<b>connect(</b>address, port<b>)</b>
</p> </p>
<p class=description> <p class="description">
Attempts to connect a master object to a remote host, transforming it into a Attempts to connect a master object to a remote host, transforming it into a
client object. client object.
Client objects support methods Client objects support methods
<a href=#send><tt>send</tt></a>, <a href="#send"><tt>send</tt></a>,
<a href=#receive><tt>receive</tt></a>, <a href="#receive"><tt>receive</tt></a>,
<a href=#getsockname><tt>getsockname</tt></a>, <a href="#getsockname"><tt>getsockname</tt></a>,
<a href=#getpeername><tt>getpeername</tt></a>, <a href="#getpeername"><tt>getpeername</tt></a>,
<a href=#settimeout><tt>settimeout</tt></a>, <a href="#settimeout"><tt>settimeout</tt></a>,
and <a href=#close><tt>close</tt></a>. and <a href="#close"><tt>close</tt></a>.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Address</tt> can be an IP address or a host name. <tt>Address</tt> can be an IP address or a host name.
<tt>Port</tt> must be an integer number in the range [1..64K). <tt>Port</tt> must be an integer number in the range [1..64K).
</p> </p>
<p class=return> <p class="return">
In case of error, the method returns <b><tt>nil</tt></b> followed by a string In case of error, the method returns <b><tt>nil</tt></b> followed by a string
describing the error. In case of success, the method returns 1. describing the error. In case of success, the method returns 1.
</p> </p>
<p class=note> <p class="note">
Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a> Note: The function <a href="socket.html#connect"><tt>socket.connect</tt></a>
is available and is a shortcut for the creation of client sockets. is available and is a shortcut for the creation of client sockets.
</p> </p>
<p class=note> <p class="note">
Note: Starting with LuaSocket 2.0, Note: Starting with LuaSocket 2.0,
the <a href=#settimeout><tt>settimeout</tt></a> the <a href="#settimeout"><tt>settimeout</tt></a>
method affects the behavior of <tt>connect</tt>, causing it to return method affects the behavior of <tt>connect</tt>, causing it to return
with an error in case of a timeout. If that happens, you can still call <a with an error in case of a timeout. If that happens, you can still call <a
href=socket.html#select><tt>socket.select</tt></a> with the socket in the href="socket.html#select"><tt>socket.select</tt></a> with the socket in the
<tt>sendt</tt> table. The socket will be writable when the connection is <tt>sendt</tt> table. The socket will be writable when the connection is
established. established.
</p> </p>
<p class=note> <p class="note">
Note: Starting with LuaSocket 3.0, the host name resolution Note: Starting with LuaSocket 3.0, the host name resolution
depends on whether the socket was created by depends on whether the socket was created by
<a href=#socket.tcp><tt>socket.tcp</tt></a>, <a href="#socket.tcp"><tt>socket.tcp</tt></a>,
<a href=#socket.tcp4><tt>socket.tcp4</tt></a> or <a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or
<a href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from <a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from
the appropriate family (or both) are tried in the order the appropriate family (or both) are tried in the order
returned by the resolver until the returned by the resolver until the
first success or until the last failure. If the timeout was first success or until the last failure. If the timeout was
@ -176,42 +177,44 @@ set to zero, only the first address is tried.
<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="dirty"> <p class="name" id="dirty">
master:<b>dirty()</b><br> master:<b>dirty()</b><br>
client:<b>dirty()</b><br> client:<b>dirty()</b><br>
server:<b>dirty()</b> server:<b>dirty()</b>
</p> </p>
<p class=description> <p class="description">
Check the read buffer status. Check the read buffer status.
</p> </p>
<p class=return> <p class="return">
Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
</p> </p>
<p class=note> <p class="note">
Note: <b>This is an internal method, use at your own risk.</b> Note: <b>This is an internal method, use at your own risk.</b>
</p> </p>
<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="getfd"> <p class="name" id="getfd">
master:<b>getfd()</b><br> master:<b>getfd()</b><br>
client:<b>getfd()</b><br> client:<b>getfd()</b><br>
server:<b>getfd()</b> server:<b>getfd()</b>
</p> </p>
<p class=description> <p class="description">
Returns the underling socket descriptor or handle associated to the object. Returns the underling socket descriptor or handle associated to the object.
</p> </p>
<p class=return> <p class="return">
The descriptor or handle. In case the object has been closed, the return will be -1. The descriptor or handle. In case the object has been closed, the return value
will be -1. For an invalid socket it will be <a href="socket.html#socketinvalid">
<tt>_SOCKETINVALID</tt></a>.
</p> </p>
<p class=note> <p class="note">
Note: <b>This is an internal method. Unlikely to be Note: <b>This is an internal method. Unlikely to be
portable. Use at your own risk. </b> portable. Use at your own risk. </b>
</p> </p>
@ -219,28 +222,27 @@ portable. Use at your own risk. </b>
<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="getoption"> <p class="name" id="getoption">
client:<b>getoption(</b>option)</b><br> client:<b>getoption(option)</b><br>
server:<b>getoption(</b>option)</b> server:<b>getoption(option)</b>
</p> </p>
<p class=description> <p class="description">
Gets options for the TCP object. Gets options for the TCP object.
See <a href=#setoption><tt>setoption</tt></a> for description of the See <a href="#setoption"><tt>setoption</tt></a> for description of the
option names and values. option names and values.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Option</tt> is a string with the option name. <tt>Option</tt> is a string with the option name.</p>
<ul> <ul>
<li> '<tt>keepalive</tt>'</li>
<li> '<tt>keepalive</tt>' <li> '<tt>linger</tt>'</li>
<li> '<tt>linger</tt>' <li> '<tt>reuseaddr</tt>'</li>
<li> '<tt>reuseaddr</tt>' <li> '<tt>tcp-nodelay</tt>'</li>
<li> '<tt>tcp-nodelay</tt>'
</ul> </ul>
<p class=return> <p class="return">
The method returns the option <tt>value</tt> in case of success, or The method returns the option <tt>value</tt> in case of success, or
<b><tt>nil</tt></b> followed by an error message otherwise. <b><tt>nil</tt></b> followed by an error message otherwise.
</p> </p>
@ -248,38 +250,38 @@ The method returns the option <tt>value</tt> in case of success, or
<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="getpeername"> <p class="name" id="getpeername">
client:<b>getpeername()</b> client:<b>getpeername()</b>
</p> </p>
<p class=description> <p class="description">
Returns information about the remote side of a connected client object. Returns information about the remote side of a connected client object.
</p> </p>
<p class=return> <p class="return">
Returns a string with the IP address of the peer, the Returns a string with the IP address of the peer, the
port number that peer is using for the connection, port number that peer is using for the connection,
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 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>. In case of error, the method returns <b><tt>nil</tt></b>.
</p> </p>
<p class=note> <p class="note">
Note: It makes no sense to call this method on server objects. Note: It makes no sense to call this method on server objects.
</p> </p>
<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="getsockname"> <p class="name" id="getsockname">
master:<b>getsockname()</b><br> master:<b>getsockname()</b><br>
client:<b>getsockname()</b><br> client:<b>getsockname()</b><br>
server:<b>getsockname()</b> server:<b>getsockname()</b>
</p> </p>
<p class=description> <p class="description">
Returns the local address information associated to the object. Returns the local address information associated to the object.
</p> </p>
<p class=return> <p class="return">
The method returns a string with local IP address, a number with The method returns a string with local IP address, a number with
the local port, the local port,
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@ -288,31 +290,31 @@ In case of error, the method returns <b><tt>nil</tt></b>.
<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="getstats"> <p class="name" id="getstats">
master:<b>getstats()</b><br> master:<b>getstats()</b><br>
client:<b>getstats()</b><br> client:<b>getstats()</b><br>
server:<b>getstats()</b><br> server:<b>getstats()</b><br>
</p> </p>
<p class=description> <p class="description">
Returns accounting information on the socket, useful for throttling Returns accounting information on the socket, useful for throttling
of bandwidth. of bandwidth.
</p> </p>
<p class=return> <p class="return">
The method returns the number of bytes received, the number of bytes sent, 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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="gettimeout"> <p class="name" id="gettimeout">
master:<b>gettimeout()</b><br> master:<b>gettimeout()</b><br>
client:<b>gettimeout()</b><br> client:<b>gettimeout()</b><br>
server:<b>gettimeout()</b> server:<b>gettimeout()</b>
</p> </p>
<p class=description> <p class="description">
Returns the current block timeout followed by the curent Returns the current block timeout followed by the curent
total timeout. total timeout.
</p> </p>
@ -320,65 +322,65 @@ total timeout.
<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="listen"> <p class="name" id="listen">
master:<b>listen(</b>backlog<b>)</b> master:<b>listen(</b>backlog<b>)</b>
</p> </p>
<p class=description> <p class="description">
Specifies the socket is willing to receive connections, transforming the Specifies the socket is willing to receive connections, transforming the
object into a server object. Server objects support the object into a server object. Server objects support the
<a href=#accept><tt>accept</tt></a>, <a href="#accept"><tt>accept</tt></a>,
<a href=#getsockname><tt>getsockname</tt></a>, <a href="#getsockname"><tt>getsockname</tt></a>,
<a href=#setoption><tt>setoption</tt></a>, <a href="#setoption"><tt>setoption</tt></a>,
<a href=#settimeout><tt>settimeout</tt></a>, <a href="#settimeout"><tt>settimeout</tt></a>,
and <a href=#close><tt>close</tt></a> methods. and <a href="#close"><tt>close</tt></a> methods.
</p> </p>
<p class=parameters> <p class="parameters">
The parameter <tt>backlog</tt> specifies the number of client The parameter <tt>backlog</tt> specifies the number of client
connections that can connections that can
be queued waiting for service. If the queue is full and another client be queued waiting for service. If the queue is full and another client
attempts connection, the connection is refused. attempts connection, the connection is refused.
</p> </p>
<p class=return> <p class="return">
In case of success, the method returns 1. In case of error, the In case of success, the method returns 1. In case of error, the
method returns <b><tt>nil</tt></b> followed by an error message. method returns <b><tt>nil</tt></b> followed by an error message.
</p> </p>
<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="receive"> <p class="name" id="receive">
client:<b>receive(</b>[pattern [, prefix]]<b>)</b> client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Reads data from a client object, according to the specified <em>read Reads data from a client object, according to the specified <em>read
pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Pattern</tt> can be any of the following: <tt>Pattern</tt> can be any of the following:
</p> </p>
<ul> <ul>
<li> '<tt>*a</tt>': reads from the socket until the connection is <li> '<tt>*a</tt>': reads from the socket until the connection is
closed. No end-of-line translation is performed; closed. No end-of-line translation is performed;</li>
<li> '<tt>*l</tt>': reads a line of text from the socket. The line is <li> '<tt>*l</tt>': reads a line of text from the socket. The line is
terminated by a LF character (ASCII&nbsp;10), optionally preceded by a terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
CR character (ASCII&nbsp;13). The CR and LF characters are not included in CR character (ASCII&nbsp;13). The CR and LF characters are not included in
the returned line. In fact, <em>all</em> CR characters are the returned line. In fact, <em>all</em> CR characters are
ignored by the pattern. This is the default pattern; ignored by the pattern. This is the default pattern;</li>
<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> <li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
of bytes from the socket. of bytes from the socket.</li>
</ul> </ul>
<p class=parameters> <p class="parameters">
<tt>Prefix</tt> is an optional string to be concatenated to the beginning <tt>Prefix</tt> is an optional string to be concatenated to the beginning
of any received data before return. of any received data before return.
</p> </p>
<p class=return> <p class="return">
If successful, the method returns the received pattern. In case of error, If successful, the method returns the received pattern. In case of error,
the method returns <tt><b>nil</b></tt> followed by an error the method returns <tt><b>nil</b></tt> followed by an error
message, followed by a (possibly empty) string containing message, followed by a (possibly empty) string containing
@ -388,7 +390,7 @@ closed before the transmission was completed or the string
'<tt>timeout</tt>' in case there was a timeout during the operation. '<tt>timeout</tt>' in case there was a timeout during the operation.
</p> </p>
<p class=note> <p class="note">
<b>Important note</b>: This function was changed <em>severely</em>. It used <b>Important note</b>: This function was changed <em>severely</em>. It used
to support multiple patterns (but I have never seen this feature used) and to support multiple patterns (but I have never seen this feature used) and
now it doesn't anymore. Partial results used to be returned in the same now it doesn't anymore. Partial results used to be returned in the same
@ -399,22 +401,22 @@ too.
<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="send"> <p class="name" id="send">
client:<b>send(</b>data [, i [, j]]<b>)</b> client:<b>send(</b>data [, i [, j]]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Sends <tt>data</tt> through client object. Sends <tt>data</tt> through client object.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Data</tt> is the string to be sent. The optional arguments <tt>Data</tt> is the string to be sent. The optional arguments
<tt>i</tt> and <tt>j</tt> work exactly like the standard <tt>i</tt> and <tt>j</tt> work exactly like the standard
<tt>string.sub</tt> Lua function to allow the selection of a <tt>string.sub</tt> Lua function to allow the selection of a
substring to be sent. substring to be sent.
</p> </p>
<p class=return> <p class="return">
If successful, the method returns the index of the last byte If successful, the method returns the index of the last byte
within <tt>[i, j]</tt> that has been sent. Notice that, if within <tt>[i, j]</tt> that has been sent. Notice that, if
<tt>i</tt> is 1 or absent, this is effectively the total <tt>i</tt> is 1 or absent, this is effectively the total
@ -428,7 +430,7 @@ was completed or the string '<tt>timeout</tt>' in case
there was a timeout during the operation. there was a timeout during the operation.
</p> </p>
<p class=note> <p class="note">
Note: Output is <em>not</em> buffered. For small strings, Note: Output is <em>not</em> buffered. For small strings,
it is always better to concatenate them in Lua it is always better to concatenate them in Lua
(with the '<tt>..</tt>' operator) and send the result in one call (with the '<tt>..</tt>' operator) and send the result in one call
@ -437,27 +439,27 @@ instead of calling the method several times.
<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="setoption"> <p class="name" id="setoption">
client:<b>setoption(</b>option [, value]<b>)</b><br> client:<b>setoption(</b>option [, value]<b>)</b><br>
server:<b>setoption(</b>option [, value]<b>)</b> server:<b>setoption(</b>option [, value]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Sets options for the TCP object. Options are only needed by low-level or Sets options for the TCP object. Options are only needed by low-level or
time-critical applications. You should only modify an option if you time-critical applications. You should only modify an option if you
are sure you need it. are sure you need it.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Option</tt> is a string with the option name, and <tt>value</tt> <tt>Option</tt> is a string with the option name, and <tt>value</tt>
depends on the option being set: depends on the option being set:</p>
<ul> <ul>
<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables <li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
the periodic transmission of messages on a connected socket. Should the the periodic transmission of messages on a connected socket. Should the
connected party fail to respond to these messages, the connection is connected party fail to respond to these messages, the connection is
considered broken and processes using the socket are notified; considered broken and processes using the socket are notified;</li>
<li> '<tt>linger</tt>': Controls the action taken when unsent data are <li> '<tt>linger</tt>': Controls the action taken when unsent data are
queued on a socket and a close is performed. The value is a table with a queued on a socket and a close is performed. The value is a table with a
@ -468,79 +470,79 @@ it is able to transmit the data or until '<tt>timeout</tt>' has passed. If
'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will '<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will
process the close in a manner that allows the process to continue as process the close in a manner that allows the process to continue as
quickly as possible. I do not advise you to set this to anything other than quickly as possible. I do not advise you to set this to anything other than
zero; zero;</li>
<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules <li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
used in validating addresses supplied in a call to used in validating addresses supplied in a call to
<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses; <a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li>
<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
disables the Nagle's algorithm for the connection; disables the Nagle's algorithm for the connection;</li>
<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!! <li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li>
<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!! <li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li>
<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!! <li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li>
<li> '<tt>ipv6-v6only</tt>': <li> '<tt>ipv6-v6only</tt>':
Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to
sending and receiving only IPv6 packets. sending and receiving only IPv6 packets.</li>
</ul> </ul>
<p class=return> <p class="return">
The method returns 1 in case of success, or <b><tt>nil</tt></b> The method returns 1 in case of success, or <b><tt>nil</tt></b>
followed by an error message otherwise. followed by an error message otherwise.
</p> </p>
<p class=note> <p class="note">
Note: The descriptions above come from the man pages. Note: The descriptions above come from the man pages.
</p> </p>
<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="setstats"> <p class="name" id="setstats">
master:<b>setstats(</b>received, sent, age<b>)</b><br> master:<b>setstats(</b>received, sent, age<b>)</b><br>
client:<b>setstats(</b>received, sent, age<b>)</b><br> client:<b>setstats(</b>received, sent, age<b>)</b><br>
server:<b>setstats(</b>received, sent, age<b>)</b><br> server:<b>setstats(</b>received, sent, age<b>)</b><br>
</p> </p>
<p class=description> <p class="description">
Resets accounting information on the socket, useful for throttling Resets accounting information on the socket, useful for throttling
of bandwidth. of bandwidth.
</p> </p>
<p class=parameters> <p class="parameters">
<tt>Received</tt> is a number with the new number of bytes received. <tt>Received</tt> is a number with the new number of bytes received.
<tt>Sent</tt> is a number with the new number of bytes sent. <tt>Sent</tt> is a number with the new number of bytes sent.
<tt>Age</tt> is the new age in seconds. <tt>Age</tt> is the new age in seconds.
</p> </p>
<p class=return> <p class="return">
The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
</p> </p>
<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="settimeout"> <p class="name" id="settimeout">
master:<b>settimeout(</b>value [, mode]<b>)</b><br> master:<b>settimeout(</b>value [, mode]<b>)</b><br>
client:<b>settimeout(</b>value [, mode]<b>)</b><br> client:<b>settimeout(</b>value [, mode]<b>)</b><br>
server:<b>settimeout(</b>value [, mode]<b>)</b> server:<b>settimeout(</b>value [, mode]<b>)</b>
</p> </p>
<p class=description> <p class="description">
Changes the timeout values for the object. By default, Changes the timeout values for the object. By default,
all I/O operations are blocking. That is, any call to the methods all I/O operations are blocking. That is, any call to the methods
<a href=#send><tt>send</tt></a>, <a href="#send"><tt>send</tt></a>,
<a href=#receive><tt>receive</tt></a>, and <a href="#receive"><tt>receive</tt></a>, and
<a href=#accept><tt>accept</tt></a> <a href="#accept"><tt>accept</tt></a>
will block indefinitely, until the operation completes. The will block indefinitely, until the operation completes. The
<tt>settimeout</tt> method defines a limit on the amount of time the <tt>settimeout</tt> method defines a limit on the amount of time the
I/O methods can block. When a timeout is set and the specified amount of I/O methods can block. When a timeout is set and the specified amount of
time has elapsed, the affected methods give up and fail with an error code. time has elapsed, the affected methods give up and fail with an error code.
</p> </p>
<p class=parameters> <p class="parameters">
The amount of time to wait is specified as the The amount of time to wait is specified as the
<tt>value</tt> parameter, in seconds. There are two timeout modes and <tt>value</tt> parameter, in seconds. There are two timeout modes and
both can be used together for fine tuning: both can be used together for fine tuning:
@ -557,12 +559,12 @@ the amount of time LuaSocket can block a Lua script before returning from
a call.</li> a call.</li>
</ul> </ul>
<p class=parameters> <p class="parameters">
The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block
indefinitely. Negative timeout values have the same effect. indefinitely. Negative timeout values have the same effect.
</p> </p>
<p class=note> <p class="note">
Note: although timeout values have millisecond precision in LuaSocket, Note: although timeout values have millisecond precision in LuaSocket,
large blocks can cause I/O functions not to respect timeout values due large blocks can cause I/O functions not to respect timeout values due
to the time the library takes to transfer blocks to and from the OS to the time the library takes to transfer blocks to and from the OS
@ -571,7 +573,7 @@ and perform automatic name resolution might be blocked by the resolver for
longer than the specified timeout value. longer than the specified timeout value.
</p> </p>
<p class=note> <p class="note">
Note: The old <tt>timeout</tt> method is deprecated. The name has been Note: The old <tt>timeout</tt> method is deprecated. The name has been
changed for sake of uniformity, since all other method names already changed for sake of uniformity, since all other method names already
contained verbs making their imperative nature obvious. contained verbs making their imperative nature obvious.
@ -579,123 +581,126 @@ contained verbs making their imperative nature obvious.
<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="shutdown"> <p class="name" id="shutdown">
client:<b>shutdown(</b>mode<b>)</b><br> client:<b>shutdown(</b>mode<b>)</b><br>
</p> </p>
<p class=description> <p class="description">
Shuts down part of a full-duplex connection. Shuts down part of a full-duplex connection.
</p> </p>
<p class=parameters> <p class="parameters">
Mode tells which way of the connection should be shut down and can Mode tells which way of the connection should be shut down and can
take the value: take the value:
<ul> <ul>
<li>"<tt>both</tt>": disallow further sends and receives on the object. <li>"<tt>both</tt>": disallow further sends and receives on the object.
This is the default mode; This is the default mode;</li>
<li>"<tt>send</tt>": disallow further sends on the object; <li>"<tt>send</tt>": disallow further sends on the object;</li>
<li>"<tt>receive</tt>": disallow further receives on the object. <li>"<tt>receive</tt>": disallow further receives on the object.</li>
</ul> </ul>
</p>
<p class=return> <p class="return">
This function returns 1. This function returns 1.
</p> </p>
<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="setfd"> <p class="name" id="setfd">
master:<b>setfd(</b>fd<b>)</b><br> master:<b>setfd(</b>fd<b>)</b><br>
client:<b>setfd(</b>fd<b>)</b><br> client:<b>setfd(</b>fd<b>)</b><br>
server:<b>setfd(</b>fd<b>)</b> server:<b>setfd(</b>fd<b>)</b>
</p> </p>
<p class=description> <p class="description">
Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made. Sets the underling socket descriptor or handle associated to the object. The current one
is simply replaced, not closed, and no other change to the object state is made.
To set it as invalid use <a href="socket.html#socketinvalid"><tt>_SOCKETINVALID</tt></a>.
</p> </p>
<p class=return> <p class="return">
No return value. No return value.
</p> </p>
<p class=note> <p class="note">
Note: <b>This is an internal method. Unlikely to be Note: <b>This is an internal method. Unlikely to be
portable. Use at your own risk. </b> portable. Use at your own risk. </b>
</p> </p>
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="socket.tcp"> <p class="name" id="socket.tcp">
socket.<b>tcp()</b> socket.<b>tcp()</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns an TCP master object. A master object can Creates and returns an TCP master object. A master object can
be transformed into a server object with the method be transformed into a server object with the method
<a href=#listen><tt>listen</tt></a> (after a call to <a <a href="#listen"><tt>listen</tt></a> (after a call to <a
href=#bind><tt>bind</tt></a>) or into a client object with href="#bind"><tt>bind</tt></a>) or into a client object with
the method <a href=#connect><tt>connect</tt></a>. The only other the method <a href="#connect"><tt>connect</tt></a>. The only other
method supported by a master object is the method supported by a master object is the
<a href=#close><tt>close</tt></a> method.</p> <a href="#close"><tt>close</tt></a> method.</p>
<p class=return> <p class="return">
In case of success, a new master object is returned. In case of error, 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. <b><tt>nil</tt></b> is returned, followed by an error message.
</p> </p>
<p class=note> <p class="note">
Note: The choice between IPv4 and IPv6 happens during a call to Note: The choice between IPv4 and IPv6 happens during a call to
<a href=#bind><tt>bind</tt></a> or <a <a href="#bind"><tt>bind</tt></a> or <a
href=#bind><tt>connect</tt></a>, depending on the address href="#bind"><tt>connect</tt></a>, depending on the address
family obtained from the resolver. family obtained from the resolver.
</p> </p>
<p class=note> <p class="note">
Note: Before the choice between IPv4 and IPv6 happens, Note: Before the choice between IPv4 and IPv6 happens,
the internal socket object is invalid and therefore <a the internal socket object is invalid and therefore <a
href=#setoption><tt>setoption</tt></a> will fail. href="#setoption"><tt>setoption</tt></a> will fail.
</p> </p>
<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="socket.tcp4"> <p class="name" id="socket.tcp4">
socket.<b>tcp4()</b> socket.<b>tcp4()</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns an IPv4 TCP master object. A master object can Creates and returns an IPv4 TCP master object. A master object can
be transformed into a server object with the method be transformed into a server object with the method
<a href=#listen><tt>listen</tt></a> (after a call to <a <a href="#listen"><tt>listen</tt></a> (after a call to <a
href=#bind><tt>bind</tt></a>) or into a client object with href="#bind"><tt>bind</tt></a>) or into a client object with
the method <a href=#connect><tt>connect</tt></a>. The only other the method <a href="#connect"><tt>connect</tt></a>. The only other
method supported by a master object is the method supported by a master object is the
<a href=#close><tt>close</tt></a> method.</p> <a href="#close"><tt>close</tt></a> method.</p>
<p class=return> <p class="return">
In case of success, a new master object is returned. In case of error, 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. <b><tt>nil</tt></b> is returned, followed by an error message.
</p> </p>
<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="socket.tcp6"> <p class="name" id="socket.tcp6">
socket.<b>tcp6()</b> socket.<b>tcp6()</b>
</p> </p>
<p class=description> <p class="description">
Creates and returns an IPv6 TCP master object. A master object can Creates and returns an IPv6 TCP master object. A master object can
be transformed into a server object with the method be transformed into a server object with the method
<a href=#listen><tt>listen</tt></a> (after a call to <a <a href="#listen"><tt>listen</tt></a> (after a call to <a
href=#bind><tt>bind</tt></a>) or into a client object with href="#bind"><tt>bind</tt></a>) or into a client object with
the method <a href=#connect><tt>connect</tt></a>. The only other the method <a href="#connect"><tt>connect</tt></a>. The only other
method supported by a master object is the method supported by a master object is the
<a href=#close><tt>close</tt></a> method.</p> <a href="#close"><tt>close</tt></a> method.</p>
<p class=return> <p class="return">
In case of success, a new master object is returned. In case of error, 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. <b><tt>nil</tt></b> is returned, followed by an error message.
</p> </p>
<p class=note> <p class="note">
Note: The TCP object returned will have the option 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>
@ -704,10 +709,10 @@ Note: The TCP object returned will have the option
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#down">download</a> &middot; <a href="index.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

94
doc/udp.html → docs/udp.html
View File

@ -13,17 +13,17 @@
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=header> <div class="header">
<hr> <hr>
<center> <center>
<table summary="LuaSocket logo"> <table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org"> <tr><td align="center"><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
</a></td></tr> </a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language <tr><td align="center" valign="top">Network support for the Lua language
</td></tr> </td></tr>
</table> </table>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;
@ -71,26 +71,26 @@ unconnected:<b>getoption()</b>
<p class="description"> <p class="description">
Gets an option value from the UDP object. Gets an option value from the UDP object.
See <a href=#setoption><tt>setoption</tt></a> for See <a href="#setoption"><tt>setoption</tt></a> for
description of the option names and values. description of the option names and values.
</p> </p>
<p class="parameters"><tt>Option</tt> is a string with the option name. <p class="parameters"><tt>Option</tt> is a string with the option name.
<ul> <ul>
<li> '<tt>dontroute</tt>' <li> '<tt>dontroute</tt>'</li>
<li> '<tt>broadcast</tt>' <li> '<tt>broadcast</tt>'</li>
<li> '<tt>reuseaddr</tt>' <li> '<tt>reuseaddr</tt>'</li>
<li> '<tt>reuseport</tt>' <li> '<tt>reuseport</tt>'</li>
<li> '<tt>ip-multicast-loop</tt>' <li> '<tt>ip-multicast-loop</tt>'</li>
<li> '<tt>ipv6-v6only</tt>' <li> '<tt>ipv6-v6only</tt>'</li>
<li> '<tt>ip-multicast-if</tt>' <li> '<tt>ip-multicast-if</tt>'</li>
<li> '<tt>ip-multicast-ttl</tt>' <li> '<tt>ip-multicast-ttl</tt>'</li>
<li> '<tt>ip-add-membership</tt>' <li> '<tt>ip-add-membership</tt>'</li>
<li> '<tt>ip-drop-membership</tt>' <li> '<tt>ip-drop-membership</tt>'</li>
</ul> </ul>
</p> </p>
<p class=return> <p class="return">
The method returns the option <tt>value</tt> in case of The method returns the option <tt>value</tt> in case of
success, or success, or
<b><tt>nil</tt></b> followed by an error message otherwise. <b><tt>nil</tt></b> followed by an error message otherwise.
@ -108,7 +108,7 @@ associated with a connected UDP object.
</p> </p>
<p class=return> <p class="return">
Returns a string with the IP address of the peer, the Returns a string with the IP address of the peer, the
port number that peer is using for the connection, port number that peer is using for the connection,
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@ -131,7 +131,7 @@ Returns the local address information associated to the object.
</p> </p>
<p class=return> <p class="return">
The method returns a string with local IP address, a number with The method returns a string with local IP address, a number with
the local port, the local port,
and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@ -148,12 +148,12 @@ wild-card address).
<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class=name id="gettimeout"> <p class="name" id="gettimeout">
connected:<b>settimeout(</b>value<b>)</b><br> connected:<b>settimeout(</b>value<b>)</b><br>
unconnected:<b>settimeout(</b>value<b>)</b> unconnected:<b>settimeout(</b>value<b>)</b>
</p> </p>
<p class=description> <p class="description">
Returns the current timeout value. Returns the current timeout value.
</p> </p>
@ -180,8 +180,8 @@ the excess bytes are discarded. If there are less then
<tt>size</tt> bytes available in the current datagram, the <tt>size</tt> bytes available in the current datagram, the
available bytes are returned. available bytes are returned.
If <tt>size</tt> is omitted, the If <tt>size</tt> is omitted, the
compile-time constant <a compile-time constant <a href="socket.html#datagramsize">
href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used <tt>socket._DATAGRAMSIZE</tt></a> is used
(it defaults to 8192 bytes). Larger sizes will cause a (it defaults to 8192 bytes). Larger sizes will cause a
temporary buffer to be allocated for the operation. temporary buffer to be allocated for the operation.
</p> </p>
@ -286,45 +286,45 @@ name, and <tt>value</tt> depends on the option being set:
<ul> <ul>
<li> '<tt>dontroute</tt>': Indicates that outgoing <li> '<tt>dontroute</tt>': Indicates that outgoing
messages should bypass the standard routing facilities. messages should bypass the standard routing facilities.
Receives a boolean value; Receives a boolean value;</li>
<li> '<tt>broadcast</tt>': Requests permission to send <li> '<tt>broadcast</tt>': Requests permission to send
broadcast datagrams on the socket. broadcast datagrams on the socket.
Receives a boolean value; Receives a boolean value;</li>
<li> '<tt>reuseaddr</tt>': Indicates that the rules used in <li> '<tt>reuseaddr</tt>': Indicates that the rules used in
validating addresses supplied in a <tt>bind()</tt> call validating addresses supplied in a <tt>bind()</tt> call
should allow reuse of local addresses. should allow reuse of local addresses.
Receives a boolean value; Receives a boolean value;</li>
<li> '<tt>reuseport</tt>': Allows completely duplicate <li> '<tt>reuseport</tt>': Allows completely duplicate
bindings by multiple processes if they all set bindings by multiple processes if they all set
'<tt>reuseport</tt>' before binding the port. '<tt>reuseport</tt>' before binding the port.
Receives a boolean value; Receives a boolean value;</li>
<li> '<tt>ip-multicast-loop</tt>': <li> '<tt>ip-multicast-loop</tt>':
Specifies whether or not a copy of an outgoing multicast Specifies whether or not a copy of an outgoing multicast
datagram is delivered to the sending host as long as it is a datagram is delivered to the sending host as long as it is a
member of the multicast group. member of the multicast group.
Receives a boolean value; Receives a boolean value;</li>
<li> '<tt>ipv6-v6only</tt>': <li> '<tt>ipv6-v6only</tt>':
Specifies whether to restrict <tt>inet6</tt> sockets to Specifies whether to restrict <tt>inet6</tt> sockets to
sending and receiving only IPv6 packets. sending and receiving only IPv6 packets.
Receive a boolean value; Receive a boolean value;</li>
<li> '<tt>ip-multicast-if</tt>': <li> '<tt>ip-multicast-if</tt>':
Sets the interface over which outgoing multicast datagrams Sets the interface over which outgoing multicast datagrams
are sent. are sent.
Receives an IP address; Receives an IP address;</li>
<li> '<tt>ip-multicast-ttl</tt>': <li> '<tt>ip-multicast-ttl</tt>':
Sets the Time To Live in the IP header for outgoing Sets the Time To Live in the IP header for outgoing
multicast datagrams. multicast datagrams.
Receives a number; Receives a number;</li>
<li> '<tt>ip-add-membership</tt>': <li> '<tt>ip-add-membership</tt>':
Joins the multicast group specified. Joins the multicast group specified.
Receives a table with fields Receives a table with fields
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an <tt>multiaddr</tt> and <tt>interface</tt>, each containing an
IP address; IP address;</li>
<li> '<tt>ip-drop-membership</tt>': Leaves the multicast <li> '<tt>ip-drop-membership</tt>': Leaves the multicast
group specified. group specified.
Receives a table with fields Receives a table with fields
<tt>multiaddr</tt> and <tt>interface</tt>, each containing an <tt>multiaddr</tt> and <tt>interface</tt>, each containing an
IP address. IP address.</li>
</ul> </ul>
<p class="return"> <p class="return">
@ -332,7 +332,7 @@ The method returns 1 in case of success, or
<b><tt>nil</tt></b> followed by an error message otherwise. <b><tt>nil</tt></b> followed by an error message otherwise.
</p> </p>
<p class=note> <p class="note">
Note: The descriptions above come from the man pages. Note: The descriptions above come from the man pages.
</p> </p>
@ -381,11 +381,11 @@ is recommended when the same peer is used for several transmissions
and can result in up to 30% performance gains. and can result in up to 30% performance gains.
</p> </p>
<p class=note> <p class="note">
Note: Starting with LuaSocket 3.0, the host name resolution Note: Starting with LuaSocket 3.0, the host name resolution
depends on whether the socket was created by <a depends on whether the socket was created by <a
href=#socket.udp><tt>socket.udp</tt></a> or <a href="#socket.udp"><tt>socket.udp</tt></a> or <a
href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from href="#socket.udp6"><tt>socket.udp6</tt></a>. Addresses from
the appropriate family are tried in succession until the the appropriate family are tried in succession until the
first success or until the last failure. first success or until the last failure.
</p> </p>
@ -492,23 +492,23 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
an error message. an error message.
</p> </p>
<p class=note> <p class="note">
Note: The choice between IPv4 and IPv6 happens during a call to Note: The choice between IPv4 and IPv6 happens during a call to
<a href=#sendto><tt>sendto</tt></a>, <a <a href="#sendto"><tt>sendto</tt></a>, <a
href=#setpeername><tt>setpeername</tt></a>, or <a href="#setpeername"><tt>setpeername</tt></a>, or <a
href=#setsockname><tt>sockname</tt></a>, depending on the address href="#setsockname"><tt>sockname</tt></a>, depending on the address
family obtained from the resolver. family obtained from the resolver.
</p> </p>
<p class=note> <p class="note">
Note: Before the choice between IPv4 and IPv6 happens, Note: Before the choice between IPv4 and IPv6 happens,
the internal socket object is invalid and therefore <a the internal socket object is invalid and therefore <a
href=#setoption><tt>setoption</tt></a> will fail. href="#setoption"><tt>setoption</tt></a> will fail.
</p> </p>
<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<p class="name" id="socket.udp"> <p class="name" id="socket.udp4">
socket.<b>udp4()</b> socket.<b>udp4()</b>
</p> </p>
@ -564,7 +564,7 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
an error message. an error message.
</p> </p>
<p class=note> <p class="note">
Note: The TCP object returned will have the option 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>
@ -573,10 +573,10 @@ Note: The TCP object returned will have the option
<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<div class=footer> <div class="footer">
<hr> <hr>
<center> <center>
<p class=bar> <p class="bar">
<a href="index.html">home</a> &middot; <a href="index.html">home</a> &middot;
<a href="index.html#download">download</a> &middot; <a href="index.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot; <a href="installation.html">installation</a> &middot;

0
doc/url.html → docs/url.html
View File

2
luasocket-scm-3.rockspec
View File

@ -127,7 +127,7 @@ build = {
mingw32 = make_plat("mingw32") mingw32 = make_plat("mingw32")
}, },
copy_directories = { copy_directories = {
"doc" "docs"
, "samples" , "samples"
, "etc" , "etc"
, "test" } , "test" }

6
makefile
View File

@ -33,6 +33,9 @@ install-both:
$(MAKE) clean $(MAKE) clean
@cd src; $(MAKE) $(PLAT) LUAV=5.3 @cd src; $(MAKE) $(PLAT) LUAV=5.3
@cd src; $(MAKE) install LUAV=5.3 @cd src; $(MAKE) install LUAV=5.3
$(MAKE) clean
@cd src; $(MAKE) $(PLAT) LUAV=5.4
@cd src; $(MAKE) install LUAV=5.4
install-both-unix: install-both-unix:
$(MAKE) clean $(MAKE) clean
@ -44,6 +47,9 @@ install-both-unix:
$(MAKE) clean $(MAKE) clean
@cd src; $(MAKE) $(PLAT) LUAV=5.3 @cd src; $(MAKE) $(PLAT) LUAV=5.3
@cd src; $(MAKE) install-unix LUAV=5.3 @cd src; $(MAKE) install-unix LUAV=5.3
$(MAKE) clean
@cd src; $(MAKE) $(PLAT) LUAV=5.4
@cd src; $(MAKE) install-unix LUAV=5.4
.PHONY: test .PHONY: test

38
makefile.dist
View File

@ -92,23 +92,23 @@ MAKE = \
socket.vcxproj \ socket.vcxproj \
mime.vcxproj mime.vcxproj
DOC = \ DOCS = \
doc/dns.html \ docs/dns.html \
doc/ftp.html \ docs/ftp.html \
doc/index.html \ docs/index.html \
doc/http.html \ docs/http.html \
doc/installation.html \ docs/installation.html \
doc/introduction.html \ docs/introduction.html \
doc/ltn12.html \ docs/ltn12.html \
doc/luasocket.png \ docs/luasocket.png \
doc/mime.html \ docs/mime.html \
doc/reference.css \ docs/reference.css \
doc/reference.html \ docs/reference.html \
doc/smtp.html \ docs/smtp.html \
doc/socket.html \ docs/socket.html \
doc/tcp.html \ docs/tcp.html \
doc/udp.html \ docs/udp.html \
doc/url.html docs/url.html
dist: dist:
mkdir -p $(DIST) mkdir -p $(DIST)
@ -123,8 +123,8 @@ dist:
mkdir -p $(DIST)/src mkdir -p $(DIST)/src
cp -vf $(SRC) $(DIST)/src cp -vf $(SRC) $(DIST)/src
mkdir -p $(DIST)/doc mkdir -p $(DIST)/docs
cp -vf $(DOC) $(DIST)/doc cp -vf $(DOCS) $(DIST)/docs
mkdir -p $(DIST)/samples mkdir -p $(DIST)/samples
cp -vf $(SAMPLES) $(DIST)/samples cp -vf $(SAMPLES) $(DIST)/samples

1
mime.vcxproj
View File

@ -20,6 +20,7 @@
</ItemGroup> </ItemGroup>
<ItemGroup> <ItemGroup>
<ClCompile Include="src\mime.c" /> <ClCompile Include="src\mime.c" />
<ClCompile Include="src\compat.c" />
</ItemGroup> </ItemGroup>
<PropertyGroup Label="Globals"> <PropertyGroup Label="Globals">
<ProjectGuid>{128E8BD0-174A-48F0-8771-92B1E8D18713}</ProjectGuid> <ProjectGuid>{128E8BD0-174A-48F0-8771-92B1E8D18713}</ProjectGuid>

1
socket.vcxproj
View File

@ -21,6 +21,7 @@
<ItemGroup> <ItemGroup>
<ClCompile Include="src\auxiliar.c" /> <ClCompile Include="src\auxiliar.c" />
<ClCompile Include="src\buffer.c" /> <ClCompile Include="src\buffer.c" />
<ClCompile Include="src\compat.c" />
<ClCompile Include="src\except.c" /> <ClCompile Include="src\except.c" />
<ClCompile Include="src\inet.c" /> <ClCompile Include="src\inet.c" />
<ClCompile Include="src\io.c" /> <ClCompile Include="src\io.c" />

7
src/http.lua
View File

@ -283,6 +283,13 @@ local function adjustrequest(reqt)
nreqt.uri = reqt.uri or adjusturi(nreqt) nreqt.uri = reqt.uri or adjusturi(nreqt)
-- adjust headers in request -- adjust headers in request
nreqt.headers = adjustheaders(nreqt) nreqt.headers = adjustheaders(nreqt)
if nreqt.source
and not nreqt.headers["content-length"]
and not nreqt.headers["transfer-encoding"]
then
nreqt.headers["transfer-encoding"] = "chunked"
end
-- ajust host and port if there is a proxy -- ajust host and port if there is a proxy
nreqt.host, nreqt.port = adjustproxy(nreqt) nreqt.host, nreqt.port = adjustproxy(nreqt)
return nreqt return nreqt

6
src/ltn12.lua
View File

@ -11,6 +11,8 @@ local string = require("string")
local table = require("table") local table = require("table")
local unpack = unpack or table.unpack local unpack = unpack or table.unpack
local base = _G local base = _G
local select = select
local _M = {} local _M = {}
if module then -- heuristic for exporting a global package table if module then -- heuristic for exporting a global package table
ltn12 = _M -- luacheck: ignore ltn12 = _M -- luacheck: ignore
@ -22,8 +24,6 @@ _M.source = source
_M.sink = sink _M.sink = sink
_M.pump = pump _M.pump = pump
local unpack = unpack or table.unpack
-- 2048 seems to be better in windows... -- 2048 seems to be better in windows...
_M.BLOCKSIZE = 2048 _M.BLOCKSIZE = 2048
_M._VERSION = "LTN12 1.0.3" _M._VERSION = "LTN12 1.0.3"
@ -45,7 +45,7 @@ end
-- (thanks to Wim Couwenberg) -- (thanks to Wim Couwenberg)
function filter.chain(...) function filter.chain(...)
local arg = {...} local arg = {...}
local n = base.select('#',...) local n = select('#',...)
local top, index = 1, 1 local top, index = 1, 1
local retry = "" local retry = ""
return function(chunk) return function(chunk)

2
src/makefile
View File

@ -16,7 +16,7 @@
# platform to build for # platform to build for
PLAT?=linux PLAT?=linux
# LUAV: 5.1 5.2 # LUAV: 5.1 5.2 5.3 5.4
# lua version to build against # lua version to build against
LUAV?=5.1 LUAV?=5.1