aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThijs Schreijer <thijs@thijsschreijer.nl>2022-03-22 19:21:58 +0100
committerGitHub <noreply@github.com>2022-03-22 21:21:58 +0300
commitf97dc8489d58aef2d038288f9a8bc69f907e17bb (patch)
tree3ac503f8ed1cc44b1c16528ed80347b0a5590cc7
parentd3434c01983de3ec40e4535f856081ad138fa198 (diff)
downloadluasocket-f97dc8489d58aef2d038288f9a8bc69f907e17bb.tar.gz
luasocket-f97dc8489d58aef2d038288f9a8bc69f907e17bb.tar.bz2
luasocket-f97dc8489d58aef2d038288f9a8bc69f907e17bb.zip
fix(docs) fix html linter issues in the docs (#358)
Diffstat
-rw-r--r--doc/dns.html78
-rw-r--r--doc/ftp.html122
-rw-r--r--doc/http.html142
-rw-r--r--doc/index.html140
-rw-r--r--doc/ltn12.html200
-rw-r--r--doc/mime.html302
-rw-r--r--doc/reference.html22
-rw-r--r--doc/smtp.html191
-rw-r--r--doc/socket.html256
-rw-r--r--doc/tcp.html325
-rw-r--r--doc/udp.html94
11 files changed, 938 insertions, 934 deletions
diff --git a/doc/dns.html b/doc/dns.html
index c4a0472..56ce3ba 100644
--- a/doc/dns.html
+++ b/doc/dns.html
@@ -1,4 +1,4 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
@@ -13,22 +13,22 @@
13 13
14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,14 +36,14 @@
36 36
37<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id=dns>DNS</h2> 39<h2 id="dns">DNS</h2>
40 40
41<p> 41<p>
42IPv4 name resolution functions 42IPv4 name resolution functions
43<a href=#toip><tt>dns.toip</tt></a> 43<a href="#toip"><tt>dns.toip</tt></a>
44and 44and
45<a href=#tohostname><tt>dns.tohostname</tt></a> 45<a href="#tohostname"><tt>dns.tohostname</tt></a>
46return <em>all</em> information obtained from 46return <em>all</em> information obtained from
47the resolver in a table of the form: 47the resolver in a table of the form:
48</p> 48</p>
49 49
@@ -60,10 +60,10 @@ Note that the <tt>alias</tt> list can be empty.
60</p> 60</p>
61 61
62<p> 62<p>
63The more general name resolution function 63The more general name resolution function
64<a href=#getaddrinfo><tt>dns.getaddrinfo</tt></a>, which 64<a href="#getaddrinfo"><tt>dns.getaddrinfo</tt></a>, which
65supports both IPv6 and IPv4, 65supports both IPv6 and IPv4,
66returns <em>all</em> information obtained from 66returns <em>all</em> information obtained from
67the resolver in a table of the form: 67the resolver in a table of the form:
68</p> 68</p>
69 69
@@ -88,82 +88,82 @@ addresses, and <tt>"inet6"</tt> for IPv6 addresses.
88 88
89<!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 89<!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
90 90
91<p class=name id=getaddrinfo> 91<p class="name" id="getaddrinfo">
92socket.dns.<b>getaddrinfo(</b>address<b>)</b> 92socket.dns.<b>getaddrinfo(</b>address<b>)</b>
93</p> 93</p>
94 94
95<p class=description> 95<p class="description">
96Converts from host name to address. 96Converts from host name to address.
97</p> 97</p>
98 98
99<p class=parameters> 99<p class="parameters">
100<tt>Address</tt> can be an IPv4 or IPv6 address or host name. 100<tt>Address</tt> can be an IPv4 or IPv6 address or host name.
101</p> 101</p>
102 102
103<p class=return> 103<p class="return">
104The function returns a table with all information returned by 104The function returns a table with all information returned by
105the resolver. In case of error, the function returns <b><tt>nil</tt></b> 105the resolver. In case of error, the function returns <b><tt>nil</tt></b>
106followed by an error message. 106followed by an error message.
107</p> 107</p>
108 108
109<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 109<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110 110
111<p class=name id=gethostname> 111<p class="name" id="gethostname">
112socket.dns.<b>gethostname()</b> 112socket.dns.<b>gethostname()</b>
113</p> 113</p>
114 114
115<p class=description> 115<p class="description">
116Returns the standard host name for the machine as a string. 116Returns the standard host name for the machine as a string.
117</p> 117</p>
118 118
119<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 119<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
120 120
121<p class=name id=tohostname> 121<p class="name" id="tohostname">
122socket.dns.<b>tohostname(</b>address<b>)</b> 122socket.dns.<b>tohostname(</b>address<b>)</b>
123</p> 123</p>
124 124
125<p class=description> 125<p class="description">
126Converts from IPv4 address to host name. 126Converts from IPv4 address to host name.
127</p> 127</p>
128 128
129<p class=parameters> 129<p class="parameters">
130<tt>Address</tt> can be an IP address or host name. 130<tt>Address</tt> can be an IP address or host name.
131</p> 131</p>
132 132
133<p class=return> 133<p class="return">
134The function returns a string with the canonic host name of the given 134The function returns a string with the canonic host name of the given
135<tt>address</tt>, followed by a table with all information returned by 135<tt>address</tt>, followed by a table with all information returned by
136the resolver. In case of error, the function returns <b><tt>nil</tt></b> 136the resolver. In case of error, the function returns <b><tt>nil</tt></b>
137followed by an error message. 137followed by an error message.
138</p> 138</p>
139 139
140<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 140<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
141 141
142<p class=name id=toip> 142<p class="name" id="toip">
143socket.dns.<b>toip(</b>address<b>)</b> 143socket.dns.<b>toip(</b>address<b>)</b>
144</p> 144</p>
145 145
146<p class=description> 146<p class="description">
147Converts from host name to IPv4 address. 147Converts from host name to IPv4 address.
148</p> 148</p>
149 149
150<p class=parameters> 150<p class="parameters">
151<tt>Address</tt> can be an IP address or host name. 151<tt>Address</tt> can be an IP address or host name.
152</p> 152</p>
153 153
154<p class=return> 154<p class="return">
155Returns a string with the first IP address found for <tt>address</tt>, 155Returns a string with the first IP address found for <tt>address</tt>,
156followed by a table with all information returned by the resolver. 156followed by a table with all information returned by the resolver.
157In case of error, the function returns <b><tt>nil</tt></b> followed by an error 157In case of error, the function returns <b><tt>nil</tt></b> followed by an error
158message. 158message.
159</p> 159</p>
160 160
161<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 161<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
162 162
163<div class=footer> 163<div class="footer">
164<hr> 164<hr>
165<center> 165<center>
166<p class=bar> 166<p class="bar">
167<a href="index.html">home</a> &middot; 167<a href="index.html">home</a> &middot;
168<a href="index.html#down">download</a> &middot; 168<a href="index.html#down">download</a> &middot;
169<a href="installation.html">installation</a> &middot; 169<a href="installation.html">installation</a> &middot;
diff --git a/doc/ftp.html b/doc/ftp.html
index 091c88f..7f7da2e 100644
--- a/doc/ftp.html
+++ b/doc/ftp.html
@@ -1,5 +1,5 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
@@ -13,22 +13,22 @@
13 13
14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,7 +36,7 @@
36 36
37<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id=ftp>FTP</h2> 39<h2 id="ftp">FTP</h2>
40 40
41<p> 41<p>
42FTP (File Transfer Protocol) is a protocol used to transfer files 42FTP (File Transfer Protocol) is a protocol used to transfer files
@@ -50,28 +50,28 @@ High level functions are provided supporting the most common operations.
50These high level functions are implemented on top of a lower level 50These high level functions are implemented on top of a lower level
51interface. Using the low-level interface, users can easily create their 51interface. Using the low-level interface, users can easily create their
52own functions to access <em>any</em> operation supported by the FTP 52own functions to access <em>any</em> operation supported by the FTP
53protocol. For that, check the implementation. 53protocol. For that, check the implementation.
54</p> 54</p>
55 55
56<p> 56<p>
57To really benefit from this module, a good understanding of 57To really benefit from this module, a good understanding of
58<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> 58<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
59LTN012, Filters sources and sinks</a> is necessary. 59LTN012, Filters sources and sinks</a> is necessary.
60</p> 60</p>
61 61
62<p> 62<p>
63To obtain the <tt>ftp</tt> namespace, run: 63To obtain the <tt>ftp</tt> namespace, run:
64</p> 64</p>
65 65
66<pre class=example> 66<pre class="example">
67-- loads the FTP module and any libraries it requires 67-- loads the FTP module and any libraries it requires
68local ftp = require("socket.ftp") 68local ftp = require("socket.ftp")
69</pre> 69</pre>
70 70
71<p> 71<p>
72URLs MUST conform to 72URLs MUST conform to
73<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, 73<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
74that is, an URL is a string in the form: 74that is, an URL is a string in the form:
75</p> 75</p>
76 76
77<blockquote> 77<blockquote>
@@ -81,19 +81,19 @@ that is, an URL is a string in the form:
81 81
82<p> 82<p>
83The following constants in the namespace can be set to control the default behavior of 83The following constants in the namespace can be set to control the default behavior of
84the FTP module: 84the FTP module:
85</p> 85</p>
86 86
87<ul> 87<ul>
88<li> <tt>PASSWORD</tt>: default anonymous password. 88<li> <tt>PASSWORD</tt>: default anonymous password.</li>
89<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; 89<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
90<li> <tt>USER</tt>: default anonymous user; 90<li> <tt>USER</tt>: default anonymous user;</li>
91</ul> 91</ul>
92 92
93 93
94<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 94<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
95 95
96<p class=name id=get> 96<p class="name" id="get">
97ftp.<b>get(</b>url<b>)</b><br> 97ftp.<b>get(</b>url<b>)</b><br>
98ftp.<b>get{</b><br> 98ftp.<b>get{</b><br>
99&nbsp;&nbsp;host = <i>string</i>,<br> 99&nbsp;&nbsp;host = <i>string</i>,<br>
@@ -109,19 +109,19 @@ ftp.<b>get{</b><br>
109<b>}</b> 109<b>}</b>
110</p> 110</p>
111 111
112<p class=description> 112<p class="description">
113The <tt>get</tt> function has two forms. The simple form has fixed 113The <tt>get</tt> function has two forms. The simple form has fixed
114functionality: it downloads the contents of a URL and returns it as a 114functionality: it downloads the contents of a URL and returns it as a
115string. The generic form allows a <em>lot</em> more control, as explained 115string. The generic form allows a <em>lot</em> more control, as explained
116below. 116below.
117</p> 117</p>
118 118
119<p class=parameters> 119<p class="parameters">
120If the argument of the <tt>get</tt> function is a table, the function 120If the argument of the <tt>get</tt> function is a table, the function
121expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of 121expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of
122<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes 122<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
123precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is 123precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is
124the <em>simple</em> 124the <em>simple</em>
125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
126sink that will receive the downloaded data. <tt>Argument</tt> or 126sink that will receive the downloaded data. <tt>Argument</tt> or
127<tt>path</tt> give the target path to the resource in the server. The 127<tt>path</tt> give the target path to the resource in the server. The
@@ -129,28 +129,28 @@ optional arguments are the following:
129</p> 129</p>
130<ul> 130<ul>
131<li><tt>user</tt>, <tt>password</tt>: User name and password used for 131<li><tt>user</tt>, <tt>password</tt>: User name and password used for
132authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; 132authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
133<li><tt>command</tt>: The FTP command used to obtain data. Defaults to 133<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
134"<tt>retr</tt>", but see example below; 134"<tt>retr</tt>", but see example below;</li>
135<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; 135<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
136<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or 136<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
137"<tt>a</tt>". Defaults to whatever is the server default; 137"<tt>a</tt>". Defaults to whatever is the server default;</li>
138<li><tt>step</tt>: 138<li><tt>step</tt>:
139<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 139<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
140pump step function used to pass data from the 140pump step function used to pass data from the
141server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; 141server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
142<li><tt>create</tt>: An optional function to be used instead of 142<li><tt>create</tt>: An optional function to be used instead of
143<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 143<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
144</ul> 144</ul>
145 145
146<p class=return> 146<p class="return">
147If successful, the simple version returns the URL contents as a 147If successful, the simple version returns the URL contents as a
148string, and the generic function returns 1. In case of error, both 148string, and the generic function returns 1. In case of error, both
149functions return <b><tt>nil</tt></b> and an error message describing the 149functions return <b><tt>nil</tt></b> and an error message describing the
150error. 150error.
151</p> 151</p>
152 152
153<pre class=example> 153<pre class="example">
154-- load the ftp support 154-- load the ftp support
155local ftp = require("socket.ftp") 155local ftp = require("socket.ftp")
156 156
@@ -159,7 +159,7 @@ local ftp = require("socket.ftp")
159f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") 159f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
160</pre> 160</pre>
161 161
162<pre class=example> 162<pre class="example">
163-- load needed modules 163-- load needed modules
164local ftp = require("socket.ftp") 164local ftp = require("socket.ftp")
165local ltn12 = require("ltn12") 165local ltn12 = require("ltn12")
@@ -178,7 +178,7 @@ end
178 178
179<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 179<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
180 180
181<p class=name id=put> 181<p class="name" id="put">
182ftp.<b>put(</b>url, content<b>)</b><br> 182ftp.<b>put(</b>url, content<b>)</b><br>
183ftp.<b>put{</b><br> 183ftp.<b>put{</b><br>
184&nbsp;&nbsp;host = <i>string</i>,<br> 184&nbsp;&nbsp;host = <i>string</i>,<br>
@@ -194,57 +194,57 @@ ftp.<b>put{</b><br>
194<b>}</b> 194<b>}</b>
195</p> 195</p>
196 196
197<p class=description> 197<p class="description">
198The <tt>put</tt> function has two forms. The simple form has fixed 198The <tt>put</tt> function has two forms. The simple form has fixed
199functionality: it uploads a string of content into a URL. The generic form 199functionality: it uploads a string of content into a URL. The generic form
200allows a <em>lot</em> more control, as explained below. 200allows a <em>lot</em> more control, as explained below.
201</p> 201</p>
202 202
203<p class=parameters> 203<p class="parameters">
204If the argument of the <tt>put</tt> function is a table, the function 204If the argument of the <tt>put</tt> function is a table, the function
205expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of 205expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of
206<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes 206<tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes
207precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is 207precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is
208the <em>simple</em> 208the <em>simple</em>
209<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 209<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
210source that will provide the contents to be uploaded. 210source that will provide the contents to be uploaded.
211<tt>Argument</tt> or 211<tt>Argument</tt> or
212<tt>path</tt> give the target path to the resource in the server. The 212<tt>path</tt> give the target path to the resource in the server. The
213optional arguments are the following: 213optional arguments are the following:
214</p> 214</p>
215<ul> 215<ul>
216<li><tt>user</tt>, <tt>password</tt>: User name and password used for 216<li><tt>user</tt>, <tt>password</tt>: User name and password used for
217authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; 217authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li>
218<li><tt>command</tt>: The FTP command used to send data. Defaults to 218<li><tt>command</tt>: The FTP command used to send data. Defaults to
219"<tt>stor</tt>", but see example below; 219"<tt>stor</tt>", but see example below;</li>
220<li><tt>port</tt>: The port to used for the control connection. Defaults to 21; 220<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li>
221<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or 221<li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or
222"<tt>a</tt>". Defaults to whatever is the server default; 222"<tt>a</tt>". Defaults to whatever is the server default;</li>
223<li><tt>step</tt>: 223<li><tt>step</tt>:
224<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 224<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
225pump step function used to pass data from the 225pump step function used to pass data from the
226server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; 226server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
227<li><tt>create</tt>: An optional function to be used instead of 227<li><tt>create</tt>: An optional function to be used instead of
228<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 228<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
229</ul> 229</ul>
230 230
231<p class=return> 231<p class="return">
232Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error 232Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
233message describing the reason for failure. 233message describing the reason for failure.
234</p> 234</p>
235 235
236<pre class=example> 236<pre class="example">
237-- load the ftp support 237-- load the ftp support
238local ftp = require("socket.ftp") 238local ftp = require("socket.ftp")
239 239
240-- Log as user "fulano" on server "ftp.example.com", 240-- Log as user "fulano" on server "ftp.example.com",
241-- using password "silva", and store a file "README" with contents 241-- using password "silva", and store a file "README" with contents
242-- "wrong password, of course" 242-- "wrong password, of course"
243f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", 243f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
244 "wrong password, of course") 244 "wrong password, of course")
245</pre> 245</pre>
246 246
247<pre class=example> 247<pre class="example">
248-- load the ftp support 248-- load the ftp support
249local ftp = require("socket.ftp") 249local ftp = require("socket.ftp")
250local ltn12 = require("ltn12") 250local ltn12 = require("ltn12")
@@ -253,7 +253,7 @@ local ltn12 = require("ltn12")
253-- using password "silva", and append to the remote file "LOG", sending the 253-- using password "silva", and append to the remote file "LOG", sending the
254-- contents of the local file "LOCAL-LOG" 254-- contents of the local file "LOCAL-LOG"
255f, e = ftp.put{ 255f, e = ftp.put{
256 host = "ftp.example.com", 256 host = "ftp.example.com",
257 user = "fulano", 257 user = "fulano",
258 password = "silva", 258 password = "silva",
259 command = "appe", 259 command = "appe",
@@ -265,15 +265,15 @@ f, e = ftp.put{
265 265
266<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 266<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
267 267
268<div class=footer> 268<div class="footer">
269<hr> 269<hr>
270<center> 270<center>
271<p class=bar> 271<p class="bar">
272<a href="index.html">home</a> &middot; 272<a href="index.html">home</a> &middot;
273<a href="index.html#download">download</a> &middot; 273<a href="index.html#download">download</a> &middot;
274<a href="installation.html">installation</a> &middot; 274<a href="installation.html">installation</a> &middot;
275<a href="introduction.html">introduction</a> &middot; 275<a href="introduction.html">introduction</a> &middot;
276<a href="reference.html">reference</a> 276<a href="reference.html">reference</a>
277</p> 277</p>
278<p> 278<p>
279<small> 279<small>
diff --git a/doc/http.html b/doc/http.html
index 78f785a..52b8a30 100644
--- a/doc/http.html
+++ b/doc/http.html
@@ -1,10 +1,10 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
6<meta name="description" content="LuaSocket: HTTP support"> 6<meta name="description" content="LuaSocket: HTTP support">
7<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> 7<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support">
8<title>LuaSocket: HTTP support</title> 8<title>LuaSocket: HTTP support</title>
9<link rel="stylesheet" href="reference.css" type="text/css"> 9<link rel="stylesheet" href="reference.css" type="text/css">
10</head> 10</head>
@@ -13,22 +13,22 @@
13 13
14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="introduction.html">introduction</a> &middot; 29<a href="introduction.html">introduction</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,12 +36,12 @@
36 36
37<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id="http">HTTP</h2> 39<h2 id="http">HTTP</h2>
40 40
41<p> 41<p>
42HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange 42HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange
43information between web-browsers and servers. The <tt>http</tt> 43information between web-browsers and servers. The <tt>http</tt>
44namespace offers full support for the client side of the HTTP 44namespace offers full support for the client side of the HTTP
45protocol (i.e., 45protocol (i.e.,
46the facilities that would be used by a web-browser implementation). The 46the facilities that would be used by a web-browser implementation). The
47implementation conforms to the HTTP/1.1 standard, 47implementation conforms to the HTTP/1.1 standard,
@@ -50,16 +50,16 @@ implementation conforms to the HTTP/1.1 standard,
50 50
51<p> 51<p>
52The module exports functions that provide HTTP functionality in different 52The module exports functions that provide HTTP functionality in different
53levels of abstraction. From the simple 53levels of abstraction. From the simple
54string oriented requests, through generic 54string oriented requests, through generic
55<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code. 55<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code.
56</p> 56</p>
57 57
58<p> 58<p>
59To obtain the <tt>http</tt> namespace, run: 59To obtain the <tt>http</tt> namespace, run:
60</p> 60</p>
61 61
62<pre class=example> 62<pre class="example">
63-- loads the HTTP module and any libraries it requires 63-- loads the HTTP module and any libraries it requires
64local http = require("socket.http") 64local http = require("socket.http")
65</pre> 65</pre>
@@ -67,12 +67,12 @@ local http = require("socket.http")
67<p> 67<p>
68URLs must conform to 68URLs must conform to
69<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, 69<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
70that is, an URL is a string in the form: 70that is, an URL is a string in the form:
71</p> 71</p>
72 72
73<blockquote> 73<blockquote>
74<pre> 74<pre>
75[http://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;] 75[http://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;]
76</pre> 76</pre>
77</blockquote> 77</blockquote>
78 78
@@ -97,34 +97,34 @@ headers = {<br>
97<p> 97<p>
98Field names are case insensitive (as specified by the standard) and all 98Field names are case insensitive (as specified by the standard) and all
99functions work with lowercase field names (but see 99functions work with lowercase field names (but see
100<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). 100<a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
101Field values are left unmodified. 101Field values are left unmodified.
102</p> 102</p>
103 103
104<p class=note> 104<p class="note">
105Note: MIME headers are independent of order. Therefore, there is no problem 105Note: MIME headers are independent of order. Therefore, there is no problem
106in representing them in a Lua table. 106in representing them in a Lua table.
107</p> 107</p>
108 108
109<p> 109<p>
110The following constants can be set to control the default behavior of 110The following constants can be set to control the default behavior of
111the HTTP module: 111the HTTP module:
112</p> 112</p>
113 113
114<ul> 114<ul>
115<li> <tt>PROXY</tt>: default proxy used for connections; 115<li> <tt>PROXY</tt>: default proxy used for connections;</li>
116<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; 116<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
117<li> <tt>USERAGENT</tt>: default user agent reported to server. 117<li> <tt>USERAGENT</tt>: default user agent reported to server.</li>
118</ul> 118</ul>
119 119
120<p class=note id="post"> 120<p class="note">
121Note: These constants are global. Changing them will also 121Note: These constants are global. Changing them will also
122change the behavior other code that might be using LuaSocket. 122change the behavior other code that might be using LuaSocket.
123</p> 123</p>
124 124
125<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 125<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
126 126
127<p class=name id="request"> 127<p class="name" id="request">
128http.<b>request(</b>url [, body]<b>)</b><br> 128http.<b>request(</b>url [, body]<b>)</b><br>
129http.<b>request{</b><br> 129http.<b>request{</b><br>
130&nbsp;&nbsp;url = <i>string</i>,<br> 130&nbsp;&nbsp;url = <i>string</i>,<br>
@@ -140,26 +140,26 @@ http.<b>request{</b><br>
140<b>}</b> 140<b>}</b>
141</p> 141</p>
142 142
143<p class=description> 143<p class="description">
144The request function has two forms. The simple form downloads 144The request function has two forms. The simple form downloads
145a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based 145a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based
146on strings. The generic form performs any HTTP method and is 146on strings. The generic form performs any HTTP method and is
147<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based. 147<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based.
148</p> 148</p>
149 149
150<p class=parameters> 150<p class="parameters">
151If the first argument of the <tt>request</tt> function is a string, it 151If the first argument of the <tt>request</tt> function is a string, it
152should be an <tt>url</tt>. In that case, if a <tt>body</tt> 152should be an <tt>url</tt>. In that case, if a <tt>body</tt>
153is provided as a string, the function will perform a <tt>POST</tt> method 153is provided as a string, the function will perform a <tt>POST</tt> method
154in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the 154in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the
155<tt>url</tt> 155<tt>url</tt>
156</p> 156</p>
157 157
158<p class=parameters> 158<p class="parameters">
159If the first argument is instead a table, the most important fields are 159If the first argument is instead a table, the most important fields are
160the <tt>url</tt> and the <em>simple</em> 160the <tt>url</tt> and the <em>simple</em>
161<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 161<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
162<tt>sink</tt> that will receive the downloaded content. 162<tt>sink</tt> that will receive the downloaded content.
163Any part of the <tt>url</tt> can be overridden by including 163Any part of the <tt>url</tt> can be overridden by including
164the appropriate field in the request table. 164the appropriate field in the request table.
165If authentication information is provided, the function 165If authentication information is provided, the function
@@ -169,49 +169,51 @@ function discards the downloaded data. The optional parameters are the
169following: 169following:
170</p> 170</p>
171<ul> 171<ul>
172<li><tt>method</tt>: The HTTP request method. Defaults to "GET"; 172<li><tt>method</tt>: The HTTP request method. Defaults to "GET";</li>
173<li><tt>headers</tt>: Any additional HTTP headers to send with the request; 173<li><tt>headers</tt>: Any additional HTTP headers to send with the request;</li>
174<li><tt>source</tt>: <em>simple</em> 174<li><tt>source</tt>: <em>simple</em>
175<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 175<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
176source to provide the request body. If there 176source to provide the request body. If there
177is a body, you need to provide an appropriate "<tt>content-length</tt>" 177is a body, you need to provide an appropriate "<tt>content-length</tt>"
178request header field, or the function will attempt to send the body as 178request header field, or the function will attempt to send the body as
179"<tt>chunked</tt>" (something few servers support). Defaults to the empty source; 179"<tt>chunked</tt>" (something few servers support). Defaults to the empty source;</li>
180<li><tt>step</tt>: 180<li><tt>step</tt>:
181<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 181<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
182pump step function used to move data. 182pump step function used to move data.
183Defaults to the LTN12 <tt>pump.step</tt> function. 183Defaults to the LTN12 <tt>pump.step</tt> function.</li>
184<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; 184<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;</li>
185<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the 185<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
186function from automatically following 301 or 302 server redirect messages; 186function from automatically following 301 or 302 server redirect messages;</li>
187<li><tt>create</tt>: An optional function to be used instead of 187<li><tt>create</tt>: An optional function to be used instead of
188<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 188<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
189<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). 189<li><tt>maxredirects</tt>: An optional number specifying the maximum number of
190 redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean
191 <tt>false</tt> value means no maximum (unlimited).</li>
190</ul> 192</ul>
191 193
192<p class=return> 194<p class="return">
193In case of failure, the function returns <tt><b>nil</b></tt> followed by an 195In case of failure, the function returns <tt><b>nil</b></tt> followed by an
194error message. If successful, the simple form returns the response 196error message. If successful, the simple form returns the response
195body as a string, followed by the response status code, the response 197body as a string, followed by the response status code, the response
196headers and the response status line. The generic function returns the same 198headers and the response status line. The generic function returns the same
197information, except the first return value is just the number 1 (the body 199information, except the first return value is just the number 1 (the body
198goes to the <tt>sink</tt>). 200goes to the <tt>sink</tt>).
199</p> 201</p>
200 202
201<p class=return> 203<p class="return">
202Even when the server fails to provide the contents of the requested URL (URL not found, for example), 204Even when the server fails to provide the contents of the requested URL (URL not found, for example),
203it usually returns a message body (a web page informing the 205it usually returns a message body (a web page informing the
204URL was not found or some other useless page). To make sure the 206URL was not found or some other useless page). To make sure the
205operation was successful, check the returned status <tt>code</tt>. For 207operation was successful, check the returned status <tt>code</tt>. For
206a list of the possible values and their meanings, refer to <a 208a list of the possible values and their meanings, refer to <a
207href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. 209href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
208</p> 210</p>
209 211
210<p class=description> 212<p class="description">
211Here are a few examples with the simple interface: 213Here are a few examples with the simple interface:
212</p> 214</p>
213 215
214<pre class=example> 216<pre class="example">
215-- load the http module 217-- load the http module
216local io = require("io") 218local io = require("io")
217local http = require("socket.http") 219local http = require("socket.http")
@@ -219,15 +221,15 @@ local ltn12 = require("ltn12")
219 221
220-- connect to server "www.cs.princeton.edu" and retrieves this manual 222-- connect to server "www.cs.princeton.edu" and retrieves this manual
221-- file from "~diego/professional/luasocket/http.html" and print it to stdout 223-- file from "~diego/professional/luasocket/http.html" and print it to stdout
222http.request{ 224http.request{
223 url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", 225 url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html",
224 sink = ltn12.sink.file(io.stdout) 226 sink = ltn12.sink.file(io.stdout)
225} 227}
226 228
227-- connect to server "www.example.com" and tries to retrieve 229-- connect to server "www.example.com" and tries to retrieve
228-- "/private/index.html". Fails because authentication is needed. 230-- "/private/index.html". Fails because authentication is needed.
229b, c, h = http.request("http://www.example.com/private/index.html") 231b, c, h = http.request("http://www.example.com/private/index.html")
230-- b returns some useless page telling about the denied access, 232-- b returns some useless page telling about the denied access,
231-- h returns authentication information 233-- h returns authentication information
232-- and c returns with value 401 (Authentication Required) 234-- and c returns with value 401 (Authentication Required)
233 235
@@ -237,11 +239,11 @@ r, e = http.request("http://wrong.host/")
237-- r is nil, and e returns with value "host not found" 239-- r is nil, and e returns with value "host not found"
238</pre> 240</pre>
239 241
240<p class=description> 242<p class="description">
241And here is an example using the generic interface: 243And here is an example using the generic interface:
242</p> 244</p>
243 245
244<pre class=example> 246<pre class="example">
245-- load the http module 247-- load the http module
246http = require("socket.http") 248http = require("socket.http")
247 249
@@ -263,7 +265,7 @@ r, c, h = http.request {
263-- } 265-- }
264</pre> 266</pre>
265 267
266<p class=note id="post"> 268<p class="note" id="post">
267Note: When sending a POST request, simple interface adds a 269Note: When sending a POST request, simple interface adds a
268"<tt>Content-type: application/x-www-form-urlencoded</tt>" 270"<tt>Content-type: application/x-www-form-urlencoded</tt>"
269header to the request. This is the type used by 271header to the request. This is the type used by
@@ -271,21 +273,21 @@ HTML forms. If you need another type, use the generic
271interface. 273interface.
272</p> 274</p>
273 275
274<p class=note id="authentication"> 276<p class="note" id="authentication">
275Note: Some URLs are protected by their 277Note: Some URLs are protected by their
276servers from anonymous download. For those URLs, the server must receive 278servers from anonymous download. For those URLs, the server must receive
277some sort of authentication along with the request or it will deny 279some sort of authentication along with the request or it will deny
278download and return status "401&nbsp;Authentication Required". 280download and return status "401&nbsp;Authentication Required".
279</p> 281</p>
280 282
281<p class=note> 283<p class="note">
282The HTTP/1.1 standard defines two authentication methods: the Basic 284The HTTP/1.1 standard defines two authentication methods: the Basic
283Authentication Scheme and the Digest Authentication Scheme, both 285Authentication Scheme and the Digest Authentication Scheme, both
284explained in detail in 286explained in detail in
285<a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>. 287<a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>.
286</p> 288</p>
287 289
288<p class=note>The Basic Authentication Scheme sends 290<p class="note">The Basic Authentication Scheme sends
289<tt>&lt;user&gt;</tt> and 291<tt>&lt;user&gt;</tt> and
290<tt>&lt;password&gt;</tt> unencrypted to the server and is therefore 292<tt>&lt;password&gt;</tt> unencrypted to the server and is therefore
291considered unsafe. Unfortunately, by the time of this implementation, 293considered unsafe. Unfortunately, by the time of this implementation,
@@ -294,7 +296,7 @@ Therefore, this is the method used by the toolkit whenever
294authentication is required. 296authentication is required.
295</p> 297</p>
296 298
297<pre class=example> 299<pre class="example">
298-- load required modules 300-- load required modules
299http = require("socket.http") 301http = require("socket.http")
300mime = require("mime") 302mime = require("mime")
@@ -314,15 +316,15 @@ r, c = http.request {
314 316
315<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 317<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
316 318
317<div class=footer> 319<div class="footer">
318<hr> 320<hr>
319<center> 321<center>
320<p class=bar> 322<p class="bar">
321<a href="index.html">home</a> &middot; 323<a href="index.html">home</a> &middot;
322<a href="index.html#download">download</a> &middot; 324<a href="index.html#download">download</a> &middot;
323<a href="installation.html">installation</a> &middot; 325<a href="installation.html">installation</a> &middot;
324<a href="introduction.html">introduction</a> &middot; 326<a href="introduction.html">introduction</a> &middot;
325<a href="reference.html">reference</a> 327<a href="reference.html">reference</a>
326</p> 328</p>
327<p> 329<p>
328<small> 330<small>
diff --git a/doc/index.html b/doc/index.html
index 7d81b41..e92b4d4 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -1,4 +1,4 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
@@ -13,22 +13,22 @@
13 13
14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,13 +36,13 @@
36 36
37<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id=whatis>What is LuaSocket?</h2> 39<h2 id="whatis">What is LuaSocket?</h2>
40 40
41<p> 41<p>
42LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library 42LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
43that is composed by two parts: a C core that provides support for the TCP 43that is composed by two parts: a C core that provides support for the TCP
44and UDP transport layers, and a set of Lua modules that add support for 44and UDP transport layers, and a set of Lua modules that add support for
45functionality commonly needed by applications that deal with the Internet. 45functionality commonly needed by applications that deal with the Internet.
46</p> 46</p>
47 47
48<p> 48<p>
@@ -52,43 +52,43 @@ properly initialized by the interpreter in use. The code has been tested
52and runs well on several Windows and UNIX platforms. </p> 52and runs well on several Windows and UNIX platforms. </p>
53 53
54<p> 54<p>
55Among the support modules, the most commonly used implement the 55Among the support modules, the most commonly used implement the
56<a href=smtp.html>SMTP</a> 56<a href="smtp.html">SMTP</a>
57(sending e-mails), 57(sending e-mails),
58<a href=http.html>HTTP</a> 58<a href="http.html">HTTP</a>
59(WWW access) and 59(WWW access) and
60<a href=ftp.html>FTP</a> 60<a href="ftp.html">FTP</a>
61(uploading and downloading files) client 61(uploading and downloading files) client
62protocols. These provide a very natural and generic interface to the 62protocols. These provide a very natural and generic interface to the
63functionality defined by each protocol. 63functionality defined by each protocol.
64In addition, you will find that the 64In addition, you will find that the
65<a href=mime.html>MIME</a> (common encodings), 65<a href="mime.html">MIME</a> (common encodings),
66<a href=url.html>URL</a> 66<a href="url.html">URL</a>
67(anything you could possible want to do with one) and 67(anything you could possible want to do with one) and
68<a href=ltn12.html>LTN12</a> 68<a href="ltn12.html">LTN12</a>
69(filters, sinks, sources and pumps) modules can be very handy. 69(filters, sinks, sources and pumps) modules can be very handy.
70</p> 70</p>
71 71
72<p> 72<p>
73The library is available under the same 73The library is available under the same
74<a href="http://www.lua.org/copyright.html"> 74<a href="http://www.lua.org/copyright.html">
75terms and conditions</a> as the Lua language, the MIT license. The idea is 75terms and conditions</a> as the Lua language, the MIT license. The idea is
76that if you can use Lua in a project, you should also be able to use 76that if you can use Lua in a project, you should also be able to use
77LuaSocket. 77LuaSocket.
78</p> 78</p>
79 79
80<p> 80<p>
81Copyright &copy; 1999-2013 Diego Nehab. All rights reserved. <br> 81Copyright &copy; 1999-2013 Diego Nehab. All rights reserved. <br>
82Author: <A href="http://www.impa.br/~diego">Diego Nehab</a> 82Author: <a href="http://www.impa.br/~diego">Diego Nehab</a>
83</p> 83</p>
84 84
85<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 85<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
86 86
87<h2 id=download>Download</h2> 87<h2 id="download">Download</h2>
88 88
89<p> 89<p>
90LuaSocket version 3.0-rc1 is now available for download! 90LuaSocket version 3.0-rc1 is now available for download!
91It is compatible with Lua&nbsp;5.1 and 5.2, and has 91It is compatible with Lua&nbsp;5.1 and 5.2, and has
92been tested on Windows&nbsp;XP, Linux, and Mac OS X. Chances 92been tested on Windows&nbsp;XP, Linux, and Mac OS X. Chances
93are it works well on most UNIX distributions and Windows flavors. 93are it works well on most UNIX distributions and Windows flavors.
94</p> 94</p>
@@ -96,19 +96,19 @@ are it works well on most UNIX distributions and Windows flavors.
96<p> 96<p>
97The current version of the library can be found at 97The current version of the library can be found at
98the <a href="https://github.com/diegonehab/luasocket">LuaSocket 98the <a href="https://github.com/diegonehab/luasocket">LuaSocket
99project page</a> on GitHub. Besides the full C and Lua source code 99project page</a> on GitHub. Besides the full C and Lua source code
100for the library, the distribution contains several examples, 100for the library, the distribution contains several examples,
101this user's manual and basic test procedures. 101this user's manual and basic test procedures.
102</p> 102</p>
103 103
104<p> Take a look at the <a 104<p> Take a look at the <a
105href=installation.html>installation</a> section of the 105href="installation.html">installation</a> section of the
106manual to find out how to properly install the library. 106manual to find out how to properly install the library.
107</p> 107</p>
108 108
109<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 109<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110 110
111<h2 id=thanks>Special thanks</h2> 111<h2 id="thanks">Special thanks</h2>
112 112
113<p> 113<p>
114This marks the first release of LuaSocket that 114This marks the first release of LuaSocket that
@@ -118,85 +118,85 @@ convinced me it was time for a release including IPv6 and
118Lua 5.2 support. It was more work than we anticipated. 118Lua 5.2 support. It was more work than we anticipated.
119Special thanks to Sam Roberts, Florian Zeitz, and Paul 119Special thanks to Sam Roberts, Florian Zeitz, and Paul
120Aurich, Liam Devine, Alexey Melnichuk, and everybody else 120Aurich, Liam Devine, Alexey Melnichuk, and everybody else
121that has helped bring this library back to life. 121that has helped bring this library back to life.
122</p> 122</p>
123 123
124<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 124<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
125 125
126<h2 id=new>What's New</h2> 126<h2 id="new">What's New</h2>
127 127
128<p> 128<p>
129Main changes for LuaSocket&nbsp;3.0-rc1 are IPv6 support 129Main changes for LuaSocket&nbsp;3.0-rc1 are IPv6 support
130and Lua&nbsp;5.2 compatibility. 130and Lua&nbsp;5.2 compatibility.
131</p> 131</p>
132 132
133<ul> 133<ul>
134<li> Added: Compatible with Lua&nbsp;5.2 134<li> Added: Compatible with Lua&nbsp;5.2</li>
135<ul> 135<ul>
136<li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>, 136<li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>,
137package tables will <em>not</em> be exported as globals! 137package tables will <em>not</em> be exported as globals!</li>
138</ul> 138</ul>
139<li> Added: IPv6 support; 139<li> Added: IPv6 support;</li>
140<ul> 140<ul>
141<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses; 141<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;</li>
142<li> <tt>Getpeername</tt> and <tt>getsockname</tt> support 142<li> <tt>Getpeername</tt> and <tt>getsockname</tt> support
143IPv6 addresses, and return the socket family as a third value; 143IPv6 addresses, and return the socket family as a third value;</li>
144<li> URL module updated to support IPv6 host names; 144<li> URL module updated to support IPv6 host names;</li>
145<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions; 145<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;</li>
146<li> New <tt>socket.dns.getaddrinfo</tt> and 146<li> New <tt>socket.dns.getaddrinfo</tt> and
147 <tt>socket.dns.getnameinfo</tt> functions; 147 <tt>socket.dns.getnameinfo</tt> functions;</li>
148</ul> 148</ul>
149<li> Added: <tt>getoption</tt> method; 149<li> Added: <tt>getoption</tt> method;</li>
150<li> Fixed: <tt>url.unescape</tt> was returning additional values; 150<li> Fixed: <tt>url.unescape</tt> was returning additional values;</li>
151<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>, 151<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>,
152 <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could 152 <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could
153 mistaking their own stack slots for functions arguments; 153 mistaking their own stack slots for functions arguments;</li>
154<li> Fixed: Receiving zero-length datagram is now possible; 154<li> Fixed: Receiving zero-length datagram is now possible;</li>
155<li> Improved: Hidden all internal library symbols; 155<li> Improved: Hidden all internal library symbols;</li>
156<li> Improved: Better error messages; 156<li> Improved: Better error messages;</li>
157<li> Improved: Better documentation of socket options. 157<li> Improved: Better documentation of socket options.</li>
158<li> Fixed: manual sample of HTTP authentication now uses correct 158<li> Fixed: manual sample of HTTP authentication now uses correct
159 "authorization" header (Alexandre Ittner); 159 "authorization" header (Alexandre Ittner);</li>
160<li> Fixed: failure on bind() was destroying the socket (Sam Roberts); 160<li> Fixed: failure on bind() was destroying the socket (Sam Roberts);</li>
161<li> Fixed: receive() returns immediatelly if prefix can satisfy 161<li> Fixed: receive() returns immediatelly if prefix can satisfy
162 bytes requested (M Joonas Pihlaja); 162 bytes requested (M Joonas Pihlaja);</li>
163<li> Fixed: multicast didn't work on Windows, or anywhere 163<li> Fixed: multicast didn't work on Windows, or anywhere
164 else for that matter (Herbert Leuwer, Adrian Sietsma); 164 else for that matter (Herbert Leuwer, Adrian Sietsma);</li>
165<li> Fixed: select() now reports an error when called with more 165<li> Fixed: select() now reports an error when called with more
166 sockets than FD_SETSIZE (Lorenzo Leonini); 166 sockets than FD_SETSIZE (Lorenzo Leonini);</li>
167<li> Fixed: manual links to home.html changed to index.html 167<li> Fixed: manual links to home.html changed to index.html
168(Robert Hahn); 168(Robert Hahn);</li>
169<li> Fixed: mime.unb64() would return an empty string on results that started 169<li> Fixed: mime.unb64() would return an empty string on results that started
170 with a null character (Robert Raschke); 170 with a null character (Robert Raschke);</li>
171<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray); 171<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);</li>
172<li> Fixed: calling sleep() with negative numbers could 172<li> Fixed: calling sleep() with negative numbers could
173 block forever, wasting CPU. Now it returns immediately (MPB); 173 block forever, wasting CPU. Now it returns immediately (MPB);</li>
174<li> Improved: FTP commands are now sent in upper case to 174<li> Improved: FTP commands are now sent in upper case to
175 help buggy servers (Anders Eurenius); 175 help buggy servers (Anders Eurenius);</li>
176<li> Improved: known headers now sent in canonic 176<li> Improved: known headers now sent in canonic
177 capitalization to help buggy servers (Joseph Stewart); 177 capitalization to help buggy servers (Joseph Stewart);</li>
178<li> Improved: Clarified tcp:receive() in the manual (MPB); 178<li> Improved: Clarified tcp:receive() in the manual (MPB);</li>
179<li> Improved: Decent makefiles (LHF). 179<li> Improved: Decent makefiles (LHF).</li>
180<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei). 180<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).</li>
181</ul> 181</ul>
182 182
183<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 183<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
184 184
185<h2 id=old>Old Versions</h2> 185<h2 id="old">Old Versions</h2>
186 186
187<p> 187<p>
188All previous versions of the LuaSocket library can be downloaded <a 188All previous versions of the LuaSocket library can be downloaded <a
189href="http://www.impa.br/~diego/software/luasocket/old"> 189href="http://www.impa.br/~diego/software/luasocket/old">
190here</a>. Although these versions are no longer supported, they are 190here</a>. Although these versions are no longer supported, they are
191still available for those that have compatibility issues. 191still available for those that have compatibility issues.
192</p> 192</p>
193 193
194<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 194<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
195 195
196<div class=footer> 196<div class="footer">
197<hr> 197<hr>
198<center> 198<center>
199<p class=bar> 199<p class="bar">
200<a href="index.html#download">download</a> &middot; 200<a href="index.html#download">download</a> &middot;
201<a href="installation.html">installation</a> &middot; 201<a href="installation.html">installation</a> &middot;
202<a href="introduction.html">introduction</a> &middot; 202<a href="introduction.html">introduction</a> &middot;
diff --git a/doc/ltn12.html b/doc/ltn12.html
index ee2502f..fe3e3a0 100644
--- a/doc/ltn12.html
+++ b/doc/ltn12.html
@@ -1,4 +1,4 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
@@ -14,22 +14,22 @@ Pump, Support, Library">
14 14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16 16
17<div class=header> 17<div class="header">
18<hr> 18<hr>
19<center> 19<center>
20<table summary="LuaSocket logo"> 20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org"> 21<tr><td align="center"><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 22<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
23</a></td></tr> 23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language 24<tr><td align="center" valign="top">Network support for the Lua language
25</td></tr> 25</td></tr>
26</table> 26</table>
27<p class=bar> 27<p class="bar">
28<a href="index.html">home</a> &middot; 28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot; 29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot; 30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot; 31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a> 32<a href="reference.html">reference</a>
33</p> 33</p>
34</center> 34</center>
35<hr> 35<hr>
@@ -37,7 +37,7 @@ Pump, Support, Library">
37 37
38<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 38<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39 39
40<h2 id=ltn12>LTN12</h2> 40<h2 id="ltn12">LTN12</h2>
41 41
42<p> The <tt>ltn12</tt> namespace implements the ideas described in 42<p> The <tt>ltn12</tt> namespace implements the ideas described in
43<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> 43<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
@@ -46,11 +46,11 @@ functions. Please refer to the LTN for a deeper explanation of the
46functionality provided by this module. 46functionality provided by this module.
47</p> 47</p>
48 48
49<p> 49<p>
50To obtain the <tt>ltn12</tt> namespace, run: 50To obtain the <tt>ltn12</tt> namespace, run:
51</p> 51</p>
52 52
53<pre class=example> 53<pre class="example">
54-- loads the LTN21 module 54-- loads the LTN21 module
55local ltn12 = require("ltn12") 55local ltn12 = require("ltn12")
56</pre> 56</pre>
@@ -61,32 +61,32 @@ local ltn12 = require("ltn12")
61 61
62<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 62<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
63 63
64<p class=name id="filter.chain"> 64<p class="name" id="filter.chain">
65ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> 65ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
66[, ... filter<sub>N</sub>]<b>)</b> 66[, ... filter<sub>N</sub>]<b>)</b>
67</p> 67</p>
68 68
69<p class=description> 69<p class="description">
70Returns a filter that passes all data it receives through each of a 70Returns a filter that passes all data it receives through each of a
71series of given filters. 71series of given filters.
72</p> 72</p>
73 73
74<p class=parameters> 74<p class="parameters">
75<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple 75<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
76filters. 76filters.
77</p> 77</p>
78 78
79<p class=return> 79<p class="return">
80The function returns the chained filter. 80The function returns the chained filter.
81</p> 81</p>
82 82
83<p class=note> 83<p class="note">
84The nesting of filters can be arbitrary. For instance, the useless filter 84The nesting of filters can be arbitrary. For instance, the useless filter
85below doesn't do anything but return the data that was passed to it, 85below doesn't do anything but return the data that was passed to it,
86unaltered. 86unaltered.
87</p> 87</p>
88 88
89<pre class=example> 89<pre class="example">
90-- load required modules 90-- load required modules
91local ltn12 = require("ltn12") 91local ltn12 = require("ltn12")
92local mime = require("mime") 92local mime = require("mime")
@@ -102,26 +102,26 @@ id = ltn12.filter.chain(
102 102
103<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 103<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
104 104
105<p class=name id="filter.cycle"> 105<p class="name" id="filter.cycle">
106ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b> 106ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
107</p> 107</p>
108 108
109<p class=description> 109<p class="description">
110Returns a high-level filter that cycles though a low-level filter by 110Returns a high-level filter that cycles though a low-level filter by
111passing it each chunk and updating a context between calls. 111passing it each chunk and updating a context between calls.
112</p> 112</p>
113 113
114<p class=parameters> 114<p class="parameters">
115<tt>Low</tt> is the low-level filter to be cycled, 115<tt>Low</tt> is the low-level filter to be cycled,
116<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra 116<tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra
117argument the low-level filter might take. 117argument the low-level filter might take.
118</p> 118</p>
119 119
120<p class=return> 120<p class="return">
121The function returns the high-level filter. 121The function returns the high-level filter.
122</p> 122</p>
123 123
124<pre class=example> 124<pre class="example">
125-- load the ltn12 module 125-- load the ltn12 module
126local ltn12 = require("ltn12") 126local ltn12 = require("ltn12")
127 127
@@ -137,15 +137,15 @@ end
137 137
138<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 138<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139 139
140<p class=name id="pump.all"> 140<p class="name" id="pump.all">
141ltn12.pump.<b>all(</b>source, sink<b>)</b> 141ltn12.pump.<b>all(</b>source, sink<b>)</b>
142</p> 142</p>
143 143
144<p class=description> 144<p class="description">
145Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. 145Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
146</p> 146</p>
147 147
148<p class=return> 148<p class="return">
149If successful, the function returns a value that evaluates to 149If successful, the function returns a value that evaluates to
150<b><tt>true</tt></b>. In case 150<b><tt>true</tt></b>. In case
151of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. 151of 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
153 153
154<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 154<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
155 155
156<p class=name id="pump.step"> 156<p class="name" id="pump.step">
157ltn12.pump.<b>step(</b>source, sink<b>)</b> 157ltn12.pump.<b>step(</b>source, sink<b>)</b>
158</p> 158</p>
159 159
160<p class=description> 160<p class="description">
161Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. 161Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
162</p> 162</p>
163 163
164<p class=return> 164<p class="return">
165If successful, the function returns a value that evaluates to 165If successful, the function returns a value that evaluates to
166<b><tt>true</tt></b>. In case 166<b><tt>true</tt></b>. In case
167of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. 167of 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
173 173
174<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 174<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
175 175
176<p class=name id="sink.chain"> 176<p class="name" id="sink.chain">
177ltn12.sink.<b>chain(</b>filter, sink<b>)</b> 177ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
178</p> 178</p>
179 179
180<p class=description> 180<p class="description">
181Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>. 181Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>.
182</p> 182</p>
183 183
184<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 184<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
185 185
186<p class=name id="sink.error"> 186<p class="name" id="sink.error">
187ltn12.sink.<b>error(</b>message<b>)</b> 187ltn12.sink.<b>error(</b>message<b>)</b>
188</p> 188</p>
189 189
190<p class=description> 190<p class="description">
191Creates and returns a sink that aborts transmission with the error 191Creates and returns a sink that aborts transmission with the error
192<tt>message</tt>. 192<tt>message</tt>.
193</p> 193</p>
194 194
195<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 195<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
196 196
197<p class=name id="sink.file"> 197<p class="name" id="sink.file">
198ltn12.sink.<b>file(</b>handle, message<b>)</b> 198ltn12.sink.<b>file(</b>handle, message<b>)</b>
199</p> 199</p>
200 200
201<p class=description> 201<p class="description">
202Creates a sink that sends data to a file. 202Creates a sink that sends data to a file.
203</p> 203</p>
204 204
205<p class=parameters> 205<p class="parameters">
206<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, 206<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
207<tt>message</tt> should give the reason for failure. 207<tt>message</tt> should give the reason for failure.
208</p> 208</p>
209 209
210<p class=return> 210<p class="return">
211The function returns a sink that sends all data to the given <tt>handle</tt> 211The function returns a sink that sends all data to the given <tt>handle</tt>
212and closes the file when done, or a sink that aborts the transmission with 212and closes the file when done, or a sink that aborts the transmission with
213the error <tt>message</tt> 213the error <tt>message</tt>
214</p> 214</p>
215 215
216<p class=note> 216<p class="note">
217In the following example, notice how the prototype is designed to 217In the following example, notice how the prototype is designed to
218fit nicely with the <tt>io.open</tt> function. 218fit nicely with the <tt>io.open</tt> function.
219</p> 219</p>
220 220
221<pre class=example> 221<pre class="example">
222-- load the ltn12 module 222-- load the ltn12 module
223local ltn12 = require("ltn12") 223local ltn12 = require("ltn12")
224 224
@@ -231,45 +231,45 @@ ltn12.pump.all(
231 231
232<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 232<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
233 233
234<p class=name id="sink.null"> 234<p class="name" id="sink.null">
235ltn12.sink.<b>null()</b> 235ltn12.sink.<b>null()</b>
236</p> 236</p>
237 237
238<p class=description> 238<p class="description">
239Returns a sink that ignores all data it receives. 239Returns a sink that ignores all data it receives.
240</p> 240</p>
241 241
242<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 242<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
243 243
244<p class=name id="sink.simplify"> 244<p class="name" id="sink.simplify">
245ltn12.sink.<b>simplify(</b>sink<b>)</b> 245ltn12.sink.<b>simplify(</b>sink<b>)</b>
246</p> 246</p>
247 247
248<p class=description> 248<p class="description">
249Creates and returns a simple sink given a fancy <tt>sink</tt>. 249Creates and returns a simple sink given a fancy <tt>sink</tt>.
250</p> 250</p>
251 251
252<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 252<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253 253
254<p class=name id="sink.table"> 254<p class="name" id="sink.table">
255ltn12.sink.<b>table(</b>[table]<b>)</b> 255ltn12.sink.<b>table(</b>[table]<b>)</b>
256</p> 256</p>
257 257
258<p class=description> 258<p class="description">
259Creates a sink that stores all chunks in a table. The chunks can later be 259Creates a sink that stores all chunks in a table. The chunks can later be
260efficiently concatenated into a single string. 260efficiently concatenated into a single string.
261</p> 261</p>
262 262
263<p class=parameters> 263<p class="parameters">
264<tt>Table</tt> is used to hold the chunks. If 264<tt>Table</tt> is used to hold the chunks. If
265<tt><b>nil</b></tt>, the function creates its own table. 265<tt><b>nil</b></tt>, the function creates its own table.
266</p> 266</p>
267 267
268<p class=return> 268<p class="return">
269The function returns the sink and the table used to store the chunks. 269The function returns the sink and the table used to store the chunks.
270</p> 270</p>
271 271
272<pre class=example> 272<pre class="example">
273-- load needed modules 273-- load needed modules
274local http = require("socket.http") 274local http = require("socket.http")
275local ltn12 = require("ltn12") 275local ltn12 = require("ltn12")
@@ -291,89 +291,89 @@ end
291 291
292<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 292<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
293 293
294<p class=name id="source.cat"> 294<p class="name" id="source.cat">
295ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ..., 295ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
296source<sub>N</sub>]<b>)</b> 296source<sub>N</sub>]<b>)</b>
297</p> 297</p>
298 298
299<p class=description> 299<p class="description">
300Creates a new source that produces the concatenation of the data produced 300Creates a new source that produces the concatenation of the data produced
301by a number of sources. 301by a number of sources.
302</p> 302</p>
303 303
304<p class=parameters> 304<p class="parameters">
305<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original 305<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
306sources. 306sources.
307</p> 307</p>
308 308
309<p class=return> 309<p class="return">
310The function returns the new source. 310The function returns the new source.
311</p> 311</p>
312 312
313<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 313<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
314 314
315<p class=name id="source.chain"> 315<p class="name" id="source.chain">
316ltn12.source.<b>chain(</b>source, filter<b>)</b> 316ltn12.source.<b>chain(</b>source, filter<b>)</b>
317</p> 317</p>
318 318
319<p class=description> 319<p class="description">
320Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> 320Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
321before returning it. 321before returning it.
322</p> 322</p>
323 323
324<p class=return> 324<p class="return">
325The function returns the new source. 325The function returns the new source.
326</p> 326</p>
327 327
328<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 328<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
329 329
330<p class=name id="source.empty"> 330<p class="name" id="source.empty">
331ltn12.source.<b>empty()</b> 331ltn12.source.<b>empty()</b>
332</p> 332</p>
333 333
334<p class=description> 334<p class="description">
335Creates and returns an empty source. 335Creates and returns an empty source.
336</p> 336</p>
337 337
338<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 338<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339 339
340<p class=name id="source.error"> 340<p class="name" id="source.error">
341ltn12.source.<b>error(</b>message<b>)</b> 341ltn12.source.<b>error(</b>message<b>)</b>
342</p> 342</p>
343 343
344<p class=description> 344<p class="description">
345Creates and returns a source that aborts transmission with the error 345Creates and returns a source that aborts transmission with the error
346<tt>message</tt>. 346<tt>message</tt>.
347</p> 347</p>
348 348
349<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 349<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
350 350
351<p class=name id="source.file"> 351<p class="name" id="source.file">
352ltn12.source.<b>file(</b>handle, message<b>)</b> 352ltn12.source.<b>file(</b>handle, message<b>)</b>
353</p> 353</p>
354 354
355<p class=description> 355<p class="description">
356Creates a source that produces the contents of a file. 356Creates a source that produces the contents of a file.
357</p> 357</p>
358 358
359<p class=parameters> 359<p class="parameters">
360<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, 360<tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>,
361<tt>message</tt> should give the reason for failure. 361<tt>message</tt> should give the reason for failure.
362</p> 362</p>
363 363
364<p class=return> 364<p class="return">
365The function returns a source that reads chunks of data from 365The function returns a source that reads chunks of data from
366given <tt>handle</tt> and returns it to the user, 366given <tt>handle</tt> and returns it to the user,
367closing the file when done, or a source that aborts the transmission with 367closing the file when done, or a source that aborts the transmission with
368the error <tt>message</tt> 368the error <tt>message</tt>
369</p> 369</p>
370 370
371<p class=note> 371<p class="note">
372In the following example, notice how the prototype is designed to 372In the following example, notice how the prototype is designed to
373fit nicely with the <tt>io.open</tt> function. 373fit nicely with the <tt>io.open</tt> function.
374</p> 374</p>
375 375
376<pre class=example> 376<pre class="example">
377-- load the ltn12 module 377-- load the ltn12 module
378local ltn12 = require("ltn12") 378local ltn12 = require("ltn12")
379 379
@@ -386,41 +386,41 @@ ltn12.pump.all(
386 386
387<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 387<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
388 388
389<p class=name id="source.simplify"> 389<p class="name" id="source.simplify">
390ltn12.source.<b>simplify(</b>source<b>)</b> 390ltn12.source.<b>simplify(</b>source<b>)</b>
391</p> 391</p>
392 392
393<p class=description> 393<p class="description">
394Creates and returns a simple source given a fancy <tt>source</tt>. 394Creates and returns a simple source given a fancy <tt>source</tt>.
395</p> 395</p>
396 396
397<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 397<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398 398
399<p class=name id="source.string"> 399<p class="name" id="source.string">
400ltn12.source.<b>string(</b>string<b>)</b> 400ltn12.source.<b>string(</b>string<b>)</b>
401</p> 401</p>
402 402
403<p class=description> 403<p class="description">
404Creates and returns a source that produces the contents of a 404Creates and returns a source that produces the contents of a
405<tt>string</tt>, chunk by chunk. 405<tt>string</tt>, chunk by chunk.
406</p> 406</p>
407 407
408<!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 408<!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
409 409
410<p class=name id="source.table"> 410<p class="name" id="source.table">
411ltn12.source.<b>table(</b>table<b>)</b> 411ltn12.source.<b>table(</b>table<b>)</b>
412</p> 412</p>
413 413
414<p class=description> 414<p class="description">
415Creates 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. 415Creates 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.
416</p> 416</p>
417 417
418<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 418<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
419 419
420<div class=footer> 420<div class="footer">
421<hr> 421<hr>
422<center> 422<center>
423<p class=bar> 423<p class="bar">
424<a href="index.html">home</a> &middot; 424<a href="index.html">home</a> &middot;
425<a href="index.html#down">download</a> &middot; 425<a href="index.html#down">download</a> &middot;
426<a href="installation.html">installation</a> &middot; 426<a href="installation.html">installation</a> &middot;
diff --git a/doc/mime.html b/doc/mime.html
index 8cb3507..ff4d8e8 100644
--- a/doc/mime.html
+++ b/doc/mime.html
@@ -1,10 +1,10 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
6<meta name="description" content="LuaSocket: MIME support"> 6<meta name="description" content="LuaSocket: MIME support">
7<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support"> 7<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support">
8<title>LuaSocket: MIME module</title> 8<title>LuaSocket: MIME module</title>
9<link rel="stylesheet" href="reference.css" type="text/css"> 9<link rel="stylesheet" href="reference.css" type="text/css">
10</head> 10</head>
@@ -13,22 +13,22 @@
13 13
14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,14 +36,14 @@
36 36
37<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id=mime>MIME</h2> 39<h2 id="mime">MIME</h2>
40 40
41<p> 41<p>
42The <tt>mime</tt> namespace offers filters that apply and remove common 42The <tt>mime</tt> namespace offers filters that apply and remove common
43content transfer encodings, such as Base64 and Quoted-Printable. 43content transfer encodings, such as Base64 and Quoted-Printable.
44It also provides functions to break text into lines and change 44It also provides functions to break text into lines and change
45the end-of-line convention. 45the end-of-line convention.
46MIME is described mainly in 46MIME is described mainly in
47<a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>, 47<a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>,
48<a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>, 48<a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>,
49<a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>, 49<a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>,
@@ -52,17 +52,17 @@ MIME is described mainly in
52</p> 52</p>
53 53
54<p> 54<p>
55All functionality provided by the MIME module 55All functionality provided by the MIME module
56follows the ideas presented in 56follows the ideas presented in
57<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> 57<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
58LTN012, Filters sources and sinks</a>. 58LTN012, Filters sources and sinks</a>.
59</p> 59</p>
60 60
61<p> 61<p>
62To obtain the <tt>mime</tt> namespace, run: 62To obtain the <tt>mime</tt> namespace, run:
63</p> 63</p>
64 64
65<pre class=example> 65<pre class="example">
66-- loads the MIME module and everything it requires 66-- loads the MIME module and everything it requires
67local mime = require("mime") 67local mime = require("mime")
68</pre> 68</pre>
@@ -70,60 +70,60 @@ local mime = require("mime")
70 70
71<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 71<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
72 72
73<h3 id=high>High-level filters</h3> 73<h3 id="high">High-level filters</h3>
74 74
75 75
76<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 76<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
77 77
78<p class=name id="decode"> 78<p class="name" id="decode">
79mime.<b>decode(</b>"base64"<b>)</b><br> 79mime.<b>decode(</b>"base64"<b>)</b><br>
80mime.<b>decode(</b>"quoted-printable"<b>)</b> 80mime.<b>decode(</b>"quoted-printable"<b>)</b>
81</p> 81</p>
82 82
83<p class=description> 83<p class="description">
84Returns a filter that decodes data from a given transfer content 84Returns a filter that decodes data from a given transfer content
85encoding. 85encoding.
86</p> 86</p>
87 87
88<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 88<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
89 89
90<p class=name id="encode"> 90<p class="name" id="encode">
91mime.<b>encode(</b>"base64"<b>)</b><br> 91mime.<b>encode(</b>"base64"<b>)</b><br>
92mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b> 92mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
93</p> 93</p>
94 94
95<p class=description> 95<p class="description">
96Returns a filter that encodes data according to a given transfer content 96Returns a filter that encodes data according to a given transfer content
97encoding. 97encoding.
98</p> 98</p>
99 99
100<p class=parameters> 100<p class="parameters">
101In the Quoted-Printable case, the user can specify whether the data is 101In the Quoted-Printable case, the user can specify whether the data is
102textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or 102textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or
103"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>". 103"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
104</p> 104</p>
105 105
106<p class=note> 106<p class="note">
107Although both transfer content encodings specify a limit for the line 107Although both transfer content encodings specify a limit for the line
108length, the encoding filters do <em>not</em> break text into lines (for 108length, the encoding filters do <em>not</em> break text into lines (for
109added flexibility). 109added flexibility).
110Below is a filter that converts binary data to the Base64 transfer content 110Below is a filter that converts binary data to the Base64 transfer content
111encoding and breaks it into lines of the correct size. 111encoding and breaks it into lines of the correct size.
112</p> 112</p>
113 113
114<pre class=example> 114<pre class="example">
115base64 = ltn12.filter.chain( 115base64 = ltn12.filter.chain(
116 mime.encode("base64"), 116 mime.encode("base64"),
117 mime.wrap("base64") 117 mime.wrap("base64")
118) 118)
119</pre> 119</pre>
120 120
121<p class=note> 121<p class="note">
122Note: Text data <em>has</em> to be converted to canonic form 122Note: Text data <em>has</em> to be converted to canonic form
123<em>before</em> being encoded. 123<em>before</em> being encoded.
124</p> 124</p>
125 125
126<pre class=example> 126<pre class="example">
127base64 = ltn12.filter.chain( 127base64 = ltn12.filter.chain(
128 mime.normalize(), 128 mime.normalize(),
129 mime.encode("base64"), 129 mime.encode("base64"),
@@ -133,77 +133,77 @@ base64 = ltn12.filter.chain(
133 133
134<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 134<!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
135 135
136<p class=name id="normalize"> 136<p class="name" id="normalize">
137mime.<b>normalize(</b>[marker]<b>)</b> 137mime.<b>normalize(</b>[marker]<b>)</b>
138</p> 138</p>
139 139
140<p class=description> 140<p class="description">
141Converts most common end-of-line markers to a specific given marker. 141Converts most common end-of-line markers to a specific given marker.
142</p> 142</p>
143 143
144<p class=parameters> 144<p class="parameters">
145<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic 145<tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic
146end-of-line marker defined by the MIME standard. 146end-of-line marker defined by the MIME standard.
147</p> 147</p>
148 148
149<p class=return> 149<p class="return">
150The function returns a filter that performs the conversion. 150The function returns a filter that performs the conversion.
151</p> 151</p>
152 152
153<p class=note> 153<p class="note">
154Note: There is no perfect solution to this problem. Different end-of-line 154Note: There is no perfect solution to this problem. Different end-of-line
155markers are an evil that will probably plague developers forever. 155markers are an evil that will probably plague developers forever.
156This function, however, will work perfectly for text created with any of 156This function, however, will work perfectly for text created with any of
157the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), 157the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF),
158or the DOS (CRLF) conventions. Even if the data has mixed end-of-line 158or the DOS (CRLF) conventions. Even if the data has mixed end-of-line
159markers, the function will still work well, although it doesn't 159markers, the function will still work well, although it doesn't
160guarantee that the number of empty lines will be correct. 160guarantee that the number of empty lines will be correct.
161</p> 161</p>
162 162
163<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 163<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
164 164
165<p class=name id="stuff"> 165<p class="name" id="stuff">
166mime.<b>stuff()</b><br> 166mime.<b>stuff()</b><br>
167</p> 167</p>
168 168
169<p class=description> 169<p class="description">
170Creates and returns a filter that performs stuffing of SMTP messages. 170Creates and returns a filter that performs stuffing of SMTP messages.
171</p> 171</p>
172 172
173<p class=note> 173<p class="note">
174Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function 174Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
175uses this filter automatically. You don't need to chain it with your 175uses this filter automatically. You don't need to chain it with your
176source, or apply it to your message body. 176source, or apply it to your message body.
177</p> 177</p>
178 178
179<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 179<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
180 180
181<p class=name id="wrap"> 181<p class="name" id="wrap">
182mime.<b>wrap(</b>"text" [, length]<b>)</b><br> 182mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
183mime.<b>wrap(</b>"base64"<b>)</b><br> 183mime.<b>wrap(</b>"base64"<b>)</b><br>
184mime.<b>wrap(</b>"quoted-printable"<b>)</b> 184mime.<b>wrap(</b>"quoted-printable"<b>)</b>
185</p> 185</p>
186 186
187<p class=description> 187<p class="description">
188Returns a filter that breaks data into lines. 188Returns a filter that breaks data into lines.
189</p> 189</p>
190 190
191<p class=parameters> 191<p class="parameters">
192The "<tt>text</tt>" line-wrap filter simply breaks text into lines by 192The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
193inserting CRLF end-of-line markers at appropriate positions. 193inserting CRLF end-of-line markers at appropriate positions.
194<tt>Length</tt> defaults 76. 194<tt>Length</tt> defaults 76.
195The "<tt>base64</tt>" line-wrap filter works just like the default 195The "<tt>base64</tt>" line-wrap filter works just like the default
196"<tt>text</tt>" line-wrap filter with default length. 196"<tt>text</tt>" line-wrap filter with default length.
197The function can also wrap "<tt>quoted-printable</tt>" lines, taking care 197The function can also wrap "<tt>quoted-printable</tt>" lines, taking care
198not to break lines in the middle of an escaped character. In that case, the 198not to break lines in the middle of an escaped character. In that case, the
199line length is fixed at 76. 199line length is fixed at 76.
200</p> 200</p>
201 201
202<p class=note> 202<p class="note">
203For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following: 203For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
204</p> 204</p>
205 205
206<pre class=example> 206<pre class="example">
207qp = ltn12.filter.chain( 207qp = ltn12.filter.chain(
208 mime.normalize(), 208 mime.normalize(),
209 mime.encode("quoted-printable"), 209 mime.encode("quoted-printable"),
@@ -211,155 +211,155 @@ qp = ltn12.filter.chain(
211) 211)
212</pre> 212</pre>
213 213
214<p class=note> 214<p class="note">
215Note: To break into lines with a different end-of-line convention, apply 215Note: To break into lines with a different end-of-line convention, apply
216a normalization filter after the line break filter. 216a normalization filter after the line break filter.
217</p> 217</p>
218 218
219<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 219<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
220 220
221<h3 id=low>Low-level filters</h3> 221<h3 id="low">Low-level filters</h3>
222 222
223<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 223<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
224 224
225<p class=name id="b64"> 225<p class="name" id="b64">
226A, B = mime.<b>b64(</b>C [, D]<b>)</b> 226A, B = mime.<b>b64(</b>C [, D]<b>)</b>
227</p> 227</p>
228 228
229<p class=description> 229<p class="description">
230Low-level filter to perform Base64 encoding. 230Low-level filter to perform Base64 encoding.
231</p> 231</p>
232 232
233<p class=description> 233<p class="description">
234<tt>A</tt> is the encoded version of the largest prefix of 234<tt>A</tt> is the encoded version of the largest prefix of
235<tt>C..D</tt> 235<tt>C..D</tt>
236that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of 236that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
237<tt>C..D</tt>, <em>before</em> encoding. 237<tt>C..D</tt>, <em>before</em> encoding.
238If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with 238If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
239the encoding of the remaining bytes of <tt>C</tt>. 239the encoding of the remaining bytes of <tt>C</tt>.
240</p> 240</p>
241 241
242<p class=note> 242<p class="note">
243Note: The simplest use of this function is to encode a string into it's 243Note: The simplest use of this function is to encode a string into it's
244Base64 transfer content encoding. Notice the extra parenthesis around the 244Base64 transfer content encoding. Notice the extra parenthesis around the
245call to <tt>mime.b64</tt>, to discard the second return value. 245call to <tt>mime.b64</tt>, to discard the second return value.
246</p> 246</p>
247 247
248<pre class=example> 248<pre class="example">
249print((mime.b64("diego:password"))) 249print((mime.b64("diego:password")))
250--&gt; ZGllZ286cGFzc3dvcmQ= 250--&gt; ZGllZ286cGFzc3dvcmQ=
251</pre> 251</pre>
252 252
253<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 253<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
254<p class=name id="dot"> 254<p class="name" id="dot">
255A, n = mime.<b>dot(</b>m [, B]<b>)</b> 255A, n = mime.<b>dot(</b>m [, B]<b>)</b>
256</p> 256</p>
257 257
258<p class=description> 258<p class="description">
259Low-level filter to perform SMTP stuffing and enable transmission of 259Low-level filter to perform SMTP stuffing and enable transmission of
260messages containing the sequence "CRLF.CRLF". 260messages containing the sequence "CRLF.CRLF".
261</p> 261</p>
262 262
263<p class=parameters> 263<p class="parameters">
264<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the 264<tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the
265number of characters from the sequence CRLF seen in the end of <tt>B</tt>. 265number of characters from the sequence CRLF seen in the end of <tt>B</tt>.
266'<tt>m</tt>' should tell the same, but for the previous chunk. 266'<tt>m</tt>' should tell the same, but for the previous chunk.
267</p> 267</p>
268 268
269<p class=note>Note: The message body is defined to begin with 269<p class="note">Note: The message body is defined to begin with
270an implicit CRLF. Therefore, to stuff a message correctly, the 270an implicit CRLF. Therefore, to stuff a message correctly, the
271first <tt>m</tt> should have the value 2. 271first <tt>m</tt> should have the value 2.
272</p> 272</p>
273 273
274<pre class=example> 274<pre class="example">
275print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n"))) 275print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
276--&gt; ..\nStuffing the message.\n..\n.. 276--&gt; ..\nStuffing the message.\n..\n..
277</pre> 277</pre>
278 278
279<p class=note> 279<p class="note">
280Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function 280Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function
281uses this filter automatically. You don't need to 281uses this filter automatically. You don't need to
282apply it again. 282apply it again.
283</p> 283</p>
284 284
285<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 285<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
286 286
287<p class=name id="eol"> 287<p class="name" id="eol">
288A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b> 288A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
289</p> 289</p>
290 290
291<p class=description> 291<p class="description">
292Low-level filter to perform end-of-line marker translation. 292Low-level filter to perform end-of-line marker translation.
293For each chunk, the function needs to know if the last character of the 293For each chunk, the function needs to know if the last character of the
294previous chunk could be part of an end-of-line marker or not. This is the 294previous chunk could be part of an end-of-line marker or not. This is the
295context the function receives besides the chunk. An updated version of 295context the function receives besides the chunk. An updated version of
296the context is returned after each new chunk. 296the context is returned after each new chunk.
297</p> 297</p>
298 298
299<p class=parameters> 299<p class="parameters">
300<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the 300<tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the
301ASCII value of the last character of the previous chunk, if it was a 301ASCII value of the last character of the previous chunk, if it was a
302candidate for line break, or 0 otherwise. 302candidate for line break, or 0 otherwise.
303<tt>B</tt> is the same as <tt>C</tt>, but for the current 303<tt>B</tt> is the same as <tt>C</tt>, but for the current
304chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF. 304chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF.
305</p> 305</p>
306 306
307<pre class=example> 307<pre class="example">
308-- translates the end-of-line marker to UNIX 308-- translates the end-of-line marker to UNIX
309unix = mime.eol(0, dos, "\n") 309unix = mime.eol(0, dos, "\n")
310</pre> 310</pre>
311 311
312<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 312<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
313 313
314<p class=name id="qp"> 314<p class="name" id="qp">
315A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b> 315A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
316</p> 316</p>
317 317
318<p class=description> 318<p class="description">
319Low-level filter to perform Quoted-Printable encoding. 319Low-level filter to perform Quoted-Printable encoding.
320</p> 320</p>
321 321
322<p class=parameters> 322<p class="parameters">
323<tt>A</tt> is the encoded version of the largest prefix of 323<tt>A</tt> is the encoded version of the largest prefix of
324<tt>C..D</tt> 324<tt>C..D</tt>
325that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of 325that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
326<tt>C..D</tt>, <em>before</em> encoding. 326<tt>C..D</tt>, <em>before</em> encoding.
327If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with 327If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with
328the encoding of the remaining bytes of <tt>C</tt>. 328the encoding of the remaining bytes of <tt>C</tt>.
329Throughout encoding, occurrences of CRLF are replaced by the 329Throughout encoding, occurrences of CRLF are replaced by the
330<tt>marker</tt>, which itself defaults to CRLF. 330<tt>marker</tt>, which itself defaults to CRLF.
331</p> 331</p>
332 332
333<p class=note> 333<p class="note">
334Note: The simplest use of this function is to encode a string into it's 334Note: The simplest use of this function is to encode a string into it's
335Quoted-Printable transfer content encoding. 335Quoted-Printable transfer content encoding.
336Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value. 336Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
337</p> 337</p>
338 338
339<pre class=example> 339<pre class="example">
340print((mime.qp("maçã"))) 340print((mime.qp("ma��")))
341--&gt; ma=E7=E3= 341--&gt; ma=E7=E3=
342</pre> 342</pre>
343 343
344<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 344<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
345 345
346<p class=name id="qpwrp"> 346<p class="name" id="qpwrp">
347A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b> 347A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
348</p> 348</p>
349 349
350<p class=description> 350<p class="description">
351Low-level filter to break Quoted-Printable text into lines. 351Low-level filter to break Quoted-Printable text into lines.
352</p> 352</p>
353 353
354<p class=parameters> 354<p class="parameters">
355<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most 355<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
356<tt>length</tt> bytes (defaults to 76). 356<tt>length</tt> bytes (defaults to 76).
357'<tt>n</tt>' should tell how many bytes are left for the first 357'<tt>n</tt>' should tell how many bytes are left for the first
358line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes 358line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
359left in the last line of <tt>A</tt>. 359left in the last line of <tt>A</tt>.
360</p> 360</p>
361 361
362<p class=note> 362<p class="note">
363Note: Besides breaking text into lines, this function makes sure the line 363Note: Besides breaking text into lines, this function makes sure the line
364breaks don't fall in the middle of an escaped character combination. Also, 364breaks don't fall in the middle of an escaped character combination. Also,
365this function only breaks lines that are bigger than <tt>length</tt> bytes. 365this function only breaks lines that are bigger than <tt>length</tt> bytes.
@@ -367,86 +367,86 @@ this function only breaks lines that are bigger than <tt>length</tt> bytes.
367 367
368<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 368<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
369 369
370<p class=name id="unb64"> 370<p class="name" id="unb64">
371A, B = mime.<b>unb64(</b>C [, D]<b>)</b> 371A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
372</p> 372</p>
373 373
374<p class=description> 374<p class="description">
375Low-level filter to perform Base64 decoding. 375Low-level filter to perform Base64 decoding.
376</p> 376</p>
377 377
378<p class=parameters> 378<p class="parameters">
379<tt>A</tt> is the decoded version of the largest prefix of 379<tt>A</tt> is the decoded version of the largest prefix of
380<tt>C..D</tt> 380<tt>C..D</tt>
381that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of 381that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
382<tt>C..D</tt>, <em>before</em> decoding. 382<tt>C..D</tt>, <em>before</em> decoding.
383If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string 383If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string
384and <tt>B</tt> returns whatever couldn't be decoded. 384and <tt>B</tt> returns whatever couldn't be decoded.
385</p> 385</p>
386 386
387<p class=note> 387<p class="note">
388Note: The simplest use of this function is to decode a string from it's 388Note: The simplest use of this function is to decode a string from it's
389Base64 transfer content encoding. 389Base64 transfer content encoding.
390Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. 390Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
391</p> 391</p>
392 392
393<pre class=example> 393<pre class="example">
394print((mime.unb64("ZGllZ286cGFzc3dvcmQ="))) 394print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
395--&gt; diego:password 395--&gt; diego:password
396</pre> 396</pre>
397 397
398<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 398<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
399 399
400<p class=name id="unqp"> 400<p class="name" id="unqp">
401A, B = mime.<b>unqp(</b>C [, D]<b>)</b> 401A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
402</p> 402</p>
403 403
404<p class=description> 404<p class="description">
405Low-level filter to remove the Quoted-Printable transfer content encoding 405Low-level filter to remove the Quoted-Printable transfer content encoding
406from data. 406from data.
407</p> 407</p>
408 408
409<p class=parameters> 409<p class="parameters">
410<tt>A</tt> is the decoded version of the largest prefix of 410<tt>A</tt> is the decoded version of the largest prefix of
411<tt>C..D</tt> 411<tt>C..D</tt>
412that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of 412that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
413<tt>C..D</tt>, <em>before</em> decoding. 413<tt>C..D</tt>, <em>before</em> decoding.
414If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with 414If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with
415the encoding of the remaining bytes of <tt>C</tt>. 415the encoding of the remaining bytes of <tt>C</tt>.
416</p> 416</p>
417 417
418<p class=note> 418<p class="note">
419Note: The simplest use of this function is to decode a string from it's 419Note: The simplest use of this function is to decode a string from it's
420Quoted-Printable transfer content encoding. 420Quoted-Printable transfer content encoding.
421Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. 421Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
422</p> 422</p>
423 423
424<pre class=example> 424<pre class="example">
425print((mime.qp("ma=E7=E3="))) 425print((mime.qp("ma=E7=E3=")))
426--&gt; maçã 426--&gt; ma��
427</pre> 427</pre>
428 428
429<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 429<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
430 430
431<p class=name id="wrp"> 431<p class="name" id="wrp">
432A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b> 432A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
433</p> 433</p>
434 434
435<p class=description> 435<p class="description">
436Low-level filter to break text into lines with CRLF marker. 436Low-level filter to break text into lines with CRLF marker.
437Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form. 437Text is assumed to be in the <a href="#normalize"><tt>normalize</tt></a> form.
438</p> 438</p>
439 439
440<p class=parameters> 440<p class="parameters">
441<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most 441<tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most
442<tt>length</tt> bytes (defaults to 76). 442<tt>length</tt> bytes (defaults to 76).
443'<tt>n</tt>' should tell how many bytes are left for the first 443'<tt>n</tt>' should tell how many bytes are left for the first
444line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes 444line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes
445left in the last line of <tt>A</tt>. 445left in the last line of <tt>A</tt>.
446</p> 446</p>
447 447
448<p class=note> 448<p class="note">
449Note: This function only breaks lines that are bigger than 449Note: This function only breaks lines that are bigger than
450<tt>length</tt> bytes. The resulting line length does not include the CRLF 450<tt>length</tt> bytes. The resulting line length does not include the CRLF
451marker. 451marker.
452</p> 452</p>
@@ -454,10 +454,10 @@ marker.
454 454
455<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 455<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
456 456
457<div class=footer> 457<div class="footer">
458<hr> 458<hr>
459<center> 459<center>
460<p class=bar> 460<p class="bar">
461<a href="index.html">home</a> &middot; 461<a href="index.html">home</a> &middot;
462<a href="index.html#down">download</a> &middot; 462<a href="index.html#down">download</a> &middot;
463<a href="installation.html">installation</a> &middot; 463<a href="installation.html">installation</a> &middot;
diff --git a/doc/reference.html b/doc/reference.html
index 163a8a2..2bc5f78 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -1,11 +1,11 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
6<meta name="description" content="LuaSocket: Index to reference manual"> 6<meta name="description" content="LuaSocket: Index to reference manual">
7<meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library, 7<meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library,
8Support, Manual"> 8Support, Manual">
9<title>LuaSocket: Index to reference manual</title> 9<title>LuaSocket: Index to reference manual</title>
10<link rel="stylesheet" href="reference.css" type="text/css"> 10<link rel="stylesheet" href="reference.css" type="text/css">
11</head> 11</head>
@@ -14,22 +14,22 @@ Support, Manual">
14 14
15<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 15<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16 16
17<div class=header> 17<div class="header">
18<hr> 18<hr>
19<center> 19<center>
20<table summary="LuaSocket logo"> 20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org"> 21<tr><td align="center"><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 22<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
23</a></td></tr> 23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language 24<tr><td align="center" valign="top">Network support for the Lua language
25</td></tr> 25</td></tr>
26</table> 26</table>
27<p class=bar> 27<p class="bar">
28<a href="index.html">home</a> &middot; 28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot; 29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot; 30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot; 31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a> 32<a href="reference.html">reference</a>
33</p> 33</p>
34</center> 34</center>
35<hr> 35<hr>
@@ -92,7 +92,7 @@ Support, Manual">
92<a href="ltn12.html#sink.table">table</a>. 92<a href="ltn12.html#sink.table">table</a>.
93</blockquote> 93</blockquote>
94<blockquote> 94<blockquote>
95<a href="ltn12.html#source">source</a>: 95<a href="ltn12.html#source">source</a>:
96<a href="ltn12.html#source.cat">cat</a>, 96<a href="ltn12.html#source.cat">cat</a>,
97<a href="ltn12.html#source.chain">chain</a>, 97<a href="ltn12.html#source.chain">chain</a>,
98<a href="ltn12.html#source.empty">empty</a>, 98<a href="ltn12.html#source.empty">empty</a>,
@@ -238,10 +238,10 @@ Support, Manual">
238 238
239<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 239<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
240 240
241<div class=footer> 241<div class="footer">
242<hr> 242<hr>
243<center> 243<center>
244<p class=bar> 244<p class="bar">
245<a href="index.html">home</a> &middot; 245<a href="index.html">home</a> &middot;
246<a href="index.html#down">download</a> &middot; 246<a href="index.html#down">download</a> &middot;
247<a href="installation.html">installation</a> &middot; 247<a href="installation.html">installation</a> &middot;
diff --git a/doc/smtp.html b/doc/smtp.html
index 600ec37..787d0b1 100644
--- a/doc/smtp.html
+++ b/doc/smtp.html
@@ -1,11 +1,11 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
6<meta name="description" content="LuaSocket: SMTP support"> 6<meta name="description" content="LuaSocket: SMTP support">
7<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart, 7<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart,
8Library, Support"> 8Library, Support">
9<title>LuaSocket: SMTP support</title> 9<title>LuaSocket: SMTP support</title>
10<link rel="stylesheet" href="reference.css" type="text/css"> 10<link rel="stylesheet" href="reference.css" type="text/css">
11</head> 11</head>
@@ -14,22 +14,22 @@ Library, Support">
14 14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16 16
17<div class=header> 17<div class="header">
18<hr> 18<hr>
19<center> 19<center>
20<table summary="LuaSocket logo"> 20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org"> 21<tr><td align="center"><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 22<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
23</a></td></tr> 23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language 24<tr><td align="center" valign="top">Network support for the Lua language
25</td></tr> 25</td></tr>
26</table> 26</table>
27<p class=bar> 27<p class="bar">
28<a href="index.html">home</a> &middot; 28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot; 29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot; 30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot; 31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a> 32<a href="reference.html">reference</a>
33</p> 33</p>
34</center> 34</center>
35<hr> 35<hr>
@@ -37,14 +37,14 @@ Library, Support">
37 37
38<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 38<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39 39
40<h2 id=smtp>SMTP</h2> 40<h2 id="smtp">SMTP</h2>
41 41
42<p> The <tt>smtp</tt> namespace provides functionality to send e-mail 42<p> The <tt>smtp</tt> namespace provides functionality to send e-mail
43messages. The high-level API consists of two functions: one to 43messages. The high-level API consists of two functions: one to
44define an e-mail message, and another to actually send the message. 44define an e-mail message, and another to actually send the message.
45Although almost all users will find that these functions provide more than 45Although almost all users will find that these functions provide more than
46enough functionality, the underlying implementation allows for even more 46enough functionality, the underlying implementation allows for even more
47control (if you bother to read the code). 47control (if you bother to read the code).
48</p> 48</p>
49 49
50<p>The implementation conforms to the Simple Mail Transfer Protocol, 50<p>The implementation conforms to the Simple Mail Transfer Protocol,
@@ -54,19 +54,19 @@ href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>,
54which governs the Internet Message Format. 54which governs the Internet Message Format.
55Multipart messages (those that contain attachments) are part 55Multipart messages (those that contain attachments) are part
56of the MIME standard, but described mainly 56of the MIME standard, but described mainly
57in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a> 57in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>.</p>
58 58
59<p> In the description below, good understanding of <a 59<p> In the description below, good understanding of <a
60href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters 60href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
61sources and sinks</a> and the <a href=mime.html>MIME</a> module is 61sources and sinks</a> and the <a href="mime.html">MIME</a> module is
62assumed. In fact, the SMTP module was the main reason for their 62assumed. In fact, the SMTP module was the main reason for their
63creation. </p> 63creation. </p>
64 64
65<p> 65<p>
66To obtain the <tt>smtp</tt> namespace, run: 66To obtain the <tt>smtp</tt> namespace, run:
67</p> 67</p>
68 68
69<pre class=example> 69<pre class="example">
70-- loads the SMTP module and everything it requires 70-- loads the SMTP module and everything it requires
71local smtp = require("socket.smtp") 71local smtp = require("socket.smtp")
72</pre> 72</pre>
@@ -92,40 +92,40 @@ headers = {<br>
92<p> 92<p>
93Field names are case insensitive (as specified by the standard) and all 93Field names are case insensitive (as specified by the standard) and all
94functions work with lowercase field names (but see 94functions work with lowercase field names (but see
95<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). 95<a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>).
96Field values are left unmodified. 96Field values are left unmodified.
97</p> 97</p>
98 98
99<p class=note> 99<p class="note">
100Note: MIME headers are independent of order. Therefore, there is no problem 100Note: MIME headers are independent of order. Therefore, there is no problem
101in representing them in a Lua table. 101in representing them in a Lua table.
102</p> 102</p>
103 103
104<p> 104<p>
105The following constants can be set to control the default behavior of 105The following constants can be set to control the default behavior of
106the SMTP module: 106the SMTP module:
107</p> 107</p>
108 108
109<ul> 109<ul>
110<li> <tt>DOMAIN</tt>: domain used to greet the server; 110<li> <tt>DOMAIN</tt>: domain used to greet the server;</li>
111<li> <tt>PORT</tt>: default port used for the connection; 111<li> <tt>PORT</tt>: default port used for the connection;</li>
112<li> <tt>SERVER</tt>: default server used for the connection; 112<li> <tt>SERVER</tt>: default server used for the connection;</li>
113<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations; 113<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;</li>
114<li> <tt>ZONE</tt>: default time zone. 114<li> <tt>ZONE</tt>: default time zone.</li>
115</ul> 115</ul>
116 116
117<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 117<!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
118 118
119<p class=name id=message> 119<p class="name" id="message">
120smtp.<b>message(</b>mesgt<b>)</b> 120smtp.<b>message(</b>mesgt<b>)</b>
121</p> 121</p>
122 122
123<p class=description> 123<p class="description">
124Returns a <em>simple</em> 124Returns a <em>simple</em>
125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep). 125<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep).
126</p> 126</p>
127 127
128<p class=parameters> 128<p class="parameters">
129The only parameter of the function is a table describing the message. 129The only parameter of the function is a table describing the message.
130<tt>Mesgt</tt> has the following form (notice the recursive structure): 130<tt>Mesgt</tt> has the following form (notice the recursive structure):
131</p> 131</p>
@@ -135,7 +135,7 @@ The only parameter of the function is a table describing the message.
135<tr><td><tt> 135<tr><td><tt>
136mesgt = {<br> 136mesgt = {<br>
137&nbsp;&nbsp;headers = <i>header-table</i>,<br> 137&nbsp;&nbsp;headers = <i>header-table</i>,<br>
138&nbsp;&nbsp;body = <i>LTN12 source</i> or <i>string</i> or 138&nbsp;&nbsp;body = <i>LTN12 source</i> or <i>string</i> or
139<i>multipart-mesgt</i><br> 139<i>multipart-mesgt</i><br>
140}<br> 140}<br>
141&nbsp;<br> 141&nbsp;<br>
@@ -151,36 +151,36 @@ multipart-mesgt = {<br>
151</table> 151</table>
152</blockquote> 152</blockquote>
153 153
154<p class=parameters> 154<p class="parameters">
155For a simple message, all that is needed is a set of <tt>headers</tt> 155For a simple message, all that is needed is a set of <tt>headers</tt>
156and the <tt>body</tt>. The message <tt>body</tt> can be given as a string 156and the <tt>body</tt>. The message <tt>body</tt> can be given as a string
157or as a <em>simple</em> 157or as a <em>simple</em>
158<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 158<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
159source. For multipart messages, the body is a table that 159source. For multipart messages, the body is a table that
160recursively defines each part as an independent message, plus an optional 160recursively defines each part as an independent message, plus an optional
161<tt>preamble</tt> and <tt>epilogue</tt>. 161<tt>preamble</tt> and <tt>epilogue</tt>.
162</p> 162</p>
163 163
164<p class=return> 164<p class="return">
165The function returns a <em>simple</em> 165The function returns a <em>simple</em>
166<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 166<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
167source that produces the 167source that produces the
168message contents as defined by <tt>mesgt</tt>, chunk by chunk. 168message contents as defined by <tt>mesgt</tt>, chunk by chunk.
169Hopefully, the following 169Hopefully, the following
170example will make things clear. When in doubt, refer to the appropriate RFC 170example will make things clear. When in doubt, refer to the appropriate RFC
171as listed in the introduction. </p> 171as listed in the introduction. </p>
172 172
173<pre class=example> 173<pre class="example">
174-- load the smtp support and its friends 174-- load the smtp support and its friends
175local smtp = require("socket.smtp") 175local smtp = require("socket.smtp")
176local mime = require("mime") 176local mime = require("mime")
177local ltn12 = require("ltn12") 177local ltn12 = require("ltn12")
178 178
179-- creates a source to send a message with two parts. The first part is 179-- creates a source to send a message with two parts. The first part is
180-- plain text, the second part is a PNG image, encoded as base64. 180-- plain text, the second part is a PNG image, encoded as base64.
181source = smtp.message{ 181source = smtp.message{
182 headers = { 182 headers = {
183 -- Remember that headers are *ignored* by smtp.send. 183 -- Remember that headers are *ignored* by smtp.send.
184 from = "Sicrano de Oliveira &lt;sicrano@example.com&gt;", 184 from = "Sicrano de Oliveira &lt;sicrano@example.com&gt;",
185 to = "Fulano da Silva &lt;fulano@example.com&gt;", 185 to = "Fulano da Silva &lt;fulano@example.com&gt;",
186 subject = "Here is a message with attachments" 186 subject = "Here is a message with attachments"
@@ -191,20 +191,20 @@ source = smtp.message{
191 "Preamble will probably appear even in a MIME enabled client.", 191 "Preamble will probably appear even in a MIME enabled client.",
192 -- first part: no headers means plain text, us-ascii. 192 -- first part: no headers means plain text, us-ascii.
193 -- The mime.eol low-level filter normalizes end-of-line markers. 193 -- The mime.eol low-level filter normalizes end-of-line markers.
194 [1] = { 194 [1] = {
195 body = mime.eol(0, [[ 195 body = mime.eol(0, [[
196 Lines in a message body should always end with CRLF. 196 Lines in a message body should always end with CRLF.
197 The smtp module will *NOT* perform translation. However, the 197 The smtp module will *NOT* perform translation. However, the
198 send function *DOES* perform SMTP stuffing, whereas the message 198 send function *DOES* perform SMTP stuffing, whereas the message
199 function does *NOT*. 199 function does *NOT*.
200 ]]) 200 ]])
201 }, 201 },
202 -- second part: headers describe content to be a png image, 202 -- second part: headers describe content to be a png image,
203 -- sent under the base64 transfer content encoding. 203 -- sent under the base64 transfer content encoding.
204 -- notice that nothing happens until the message is actually sent. 204 -- notice that nothing happens until the message is actually sent.
205 -- small chunks are loaded into memory right before transmission and 205 -- small chunks are loaded into memory right before transmission and
206 -- translation happens on the fly. 206 -- translation happens on the fly.
207 [2] = { 207 [2] = {
208 headers = { 208 headers = {
209 ["content-type"] = 'image/png; name="image.png"', 209 ["content-type"] = 'image/png; name="image.png"',
210 ["content-disposition"] = 'attachment; filename="image.png"', 210 ["content-disposition"] = 'attachment; filename="image.png"',
@@ -234,7 +234,7 @@ r, e = smtp.send{
234 234
235<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 235<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
236 236
237<p class=name id=send> 237<p class="name" id="send">
238smtp.<b>send{</b><br> 238smtp.<b>send{</b><br>
239&nbsp;&nbsp;from = <i>string</i>,<br> 239&nbsp;&nbsp;from = <i>string</i>,<br>
240&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br> 240&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
@@ -249,53 +249,53 @@ smtp.<b>send{</b><br>
249<b>}</b> 249<b>}</b>
250</p> 250</p>
251 251
252<p class=description> 252<p class="description">
253Sends a message to a recipient list. Since sending messages is not as 253Sends a message to a recipient list. Since sending messages is not as
254simple as downloading an URL from a FTP or HTTP server, this function 254simple as downloading an URL from a FTP or HTTP server, this function
255doesn't have a simple interface. However, see the 255doesn't have a simple interface. However, see the
256<a href=#message><tt>message</tt></a> source factory for 256<a href="#message"><tt>message</tt></a> source factory for
257a very powerful way to define the message contents. 257a very powerful way to define the message contents.
258</p> 258</p>
259 259
260 260
261<p class=parameters> 261<p class="parameters">
262The sender is given by the e-mail address in the <tt>from</tt> field. 262The sender is given by the e-mail address in the <tt>from</tt> field.
263<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail 263<tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail
264address, or a string 264address, or a string
265in case there is just one recipient. 265in case there is just one recipient.
266The contents of the message are given by a <em>simple</em> 266The contents of the message are given by a <em>simple</em>
267<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 267<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
268<tt>source</tt>. Several arguments are optional: 268<tt>source</tt>. Several arguments are optional:
269</p> 269</p>
270<ul> 270<ul>
271<li> <tt>user</tt>, <tt>password</tt>: User and password for 271<li> <tt>user</tt>, <tt>password</tt>: User and password for
272authentication. The function will attempt LOGIN and PLAIN authentication 272authentication. The function will attempt LOGIN and PLAIN authentication
273methods if supported by the server (both are unsafe); 273methods if supported by the server (both are unsafe);</li>
274<li> <tt>server</tt>: Server to connect to. Defaults to "localhost"; 274<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";</li>
275<li> <tt>port</tt>: Port to connect to. Defaults to 25; 275<li> <tt>port</tt>: Port to connect to. Defaults to 25;</li>
276<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the 276<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
277local machine host name; 277local machine host name;</li>
278<li> <tt>step</tt>: 278<li> <tt>step</tt>:
279<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 279<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
280pump step function used to pass data from the 280pump step function used to pass data from the
281source to the server. Defaults to the LTN12 <tt>pump.step</tt> function; 281source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;</li>
282<li><tt>create</tt>: An optional function to be used instead of 282<li><tt>create</tt>: An optional function to be used instead of
283<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. 283<a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
284</ul> 284</ul>
285 285
286<p class=return> 286<p class="return">
287If successful, the function returns 1. Otherwise, the function returns 287If successful, the function returns 1. Otherwise, the function returns
288<b><tt>nil</tt></b> followed by an error message. 288<b><tt>nil</tt></b> followed by an error message.
289</p> 289</p>
290 290
291<p class=note> 291<p class="note">
292Note: SMTP servers can be very picky with the format of e-mail 292Note: SMTP servers can be very picky with the format of e-mail
293addresses. To be safe, use only addresses of the form 293addresses. To be safe, use only addresses of the form
294"<tt>&lt;fulano@example.com&gt;</tt>" in the <tt>from</tt> and 294"<tt>&lt;fulano@example.com&gt;</tt>" in the <tt>from</tt> and
295<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail 295<tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail
296addresses can take whatever form you like. </p> 296addresses can take whatever form you like. </p>
297 297
298<p class=note> 298<p class="note">
299Big note: There is a good deal of misconception with the use of the 299Big note: There is a good deal of misconception with the use of the
300destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', 300destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
301and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a 301and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
@@ -303,68 +303,69 @@ and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
303exact opposite of what you expect. 303exact opposite of what you expect.
304</p> 304</p>
305 305
306<p class=note> 306<p class="note">
307Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the 307Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the
308message. Each recipient of an SMTP mail message receives a copy of the 308message. Each recipient of an SMTP mail message receives a copy of the
309message body along with the headers, and nothing more. The headers 309message body along with the headers, and nothing more. The headers
310<em>are</em> part of the message and should be produced by the 310<em>are</em> part of the message and should be produced by the
311<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 311<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
312<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em> 312<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
313part of the message and will not be sent to anyone. 313part of the message and will not be sent to anyone.
314</p> 314</p>
315 315
316<p class=note> 316<p class="note">
317<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> 317<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>
318has two <em>important and short</em> sections, "3.6.3. Destination address 318has two <em>important and short</em> sections, "3.6.3. Destination address
319fields" and "5. Security considerations", explaining the proper 319fields" and "5. Security considerations", explaining the proper
320use of these headers. Here is a summary of what it says: 320use of these headers. Here is a summary of what it says:
321</p> 321</p>
322 322
323<ul> 323<ul>
324<li> <tt>To</tt>: contains the address(es) of the primary recipient(s) 324<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
325of the message; 325of the message;</li>
326<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of 326<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
327making a copy on a typewriter using carbon paper) contains the 327making a copy on a typewriter using carbon paper) contains the
328addresses of others who are to receive the message, though the 328addresses of others who are to receive the message, though the
329content of the message may not be directed at them; 329content of the message may not be directed at them;</li>
330<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon 330<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
331Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message. 331Copy") contains addresses of recipients of the message whose addresses are not
332</ul> 332to be revealed to other recipients of the message.</li>
333</ul>
333 334
334<p class=note> 335<p class="note">
335The LuaSocket <tt>send</tt> function does not care or interpret the 336The LuaSocket <tt>send</tt> function does not care or interpret the
336headers you send, but it gives you full control over what is sent and 337headers you send, but it gives you full control over what is sent and
337to whom it is sent: 338to whom it is sent:
338</p> 339</p>
339<ul> 340<ul>
340<li> If someone is to receive the message, the e-mail address <em>has</em> 341<li> If someone is to receive the message, the e-mail address <em>has</em>
341to be in the recipient list. This is the only parameter that controls who 342to be in the recipient list. This is the only parameter that controls who
342gets a copy of the message; 343gets a copy of the message;</li>
343<li> If there are multiple recipients, none of them will automatically 344<li> If there are multiple recipients, none of them will automatically
344know that someone else got that message. That is, the default behavior is 345know that someone else got that message. That is, the default behavior is
345similar to the <tt>Bcc</tt> field of popular e-mail clients; 346similar to the <tt>Bcc</tt> field of popular e-mail clients;</li>
346<li> It is up to you to add the <tt>To</tt> header with the list of primary 347<li> It is up to you to add the <tt>To</tt> header with the list of primary
347recipients so that other recipients can see it; 348recipients so that other recipients can see it;</li>
348<li> It is also up to you to add the <tt>Cc</tt> header with the 349<li> It is also up to you to add the <tt>Cc</tt> header with the
349list of additional recipients so that everyone else sees it; 350list of additional recipients so that everyone else sees it;</li>
350<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is 351<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
351empty. Otherwise, everyone receiving the message will see it and that is 352empty. Otherwise, everyone receiving the message will see it and that is
352exactly what you <em>don't</em> want to happen! 353exactly what you <em>don't</em> want to happen!</li>
353</ul> 354</ul>
354 355
355<p class=note> 356<p class="note">
356I hope this clarifies the issue. Otherwise, please refer to 357I hope this clarifies the issue. Otherwise, please refer to
357<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> 358<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>
358and 359and
359<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. 360<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>.
360</p> 361</p>
361 362
362<pre class=example> 363<pre class="example">
363-- load the smtp support 364-- load the smtp support
364local smtp = require("socket.smtp") 365local smtp = require("socket.smtp")
365 366
366-- Connects to server "localhost" and sends a message to users 367-- Connects to server "localhost" and sends a message to users
367-- "fulano@example.com", "beltrano@example.com", 368-- "fulano@example.com", "beltrano@example.com",
368-- and "sicrano@example.com". 369-- and "sicrano@example.com".
369-- Note that "fulano" is the primary recipient, "beltrano" receives a 370-- Note that "fulano" is the primary recipient, "beltrano" receives a
370-- carbon copy and neither of them knows that "sicrano" received a blind 371-- carbon copy and neither of them knows that "sicrano" received a blind
@@ -388,17 +389,17 @@ mesgt = {
388 389
389r, e = smtp.send{ 390r, e = smtp.send{
390 from = from, 391 from = from,
391 rcpt = rcpt, 392 rcpt = rcpt,
392 source = smtp.message(mesgt) 393 source = smtp.message(mesgt)
393} 394}
394</pre> 395</pre>
395 396
396<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 397<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
397 398
398<div class=footer> 399<div class="footer">
399<hr> 400<hr>
400<center> 401<center>
401<p class=bar> 402<p class="bar">
402<a href="index.html">home</a> &middot; 403<a href="index.html">home</a> &middot;
403<a href="index.html#down">download</a> &middot; 404<a href="index.html#down">download</a> &middot;
404<a href="installation.html">installation</a> &middot; 405<a href="installation.html">installation</a> &middot;
diff --git a/doc/socket.html b/doc/socket.html
index 35f8391..68db7cc 100644
--- a/doc/socket.html
+++ b/doc/socket.html
@@ -1,10 +1,10 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd"> 2 "http://www.w3.org/TR/html4/strict.dtd">
3<html> 3<html>
4 4
5<head> 5<head>
6<meta name="description" content="LuaSocket: The core namespace"> 6<meta name="description" content="LuaSocket: The core namespace">
7<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> 7<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
8<title>LuaSocket: The socket namespace</title> 8<title>LuaSocket: The socket namespace</title>
9<link rel="stylesheet" href="reference.css" type="text/css"> 9<link rel="stylesheet" href="reference.css" type="text/css">
10</head> 10</head>
@@ -13,22 +13,22 @@
13 13
14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="https://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot; 30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a> 31<a href="reference.html">reference</a>
32</p> 32</p>
33</center> 33</center>
34<hr> 34<hr>
@@ -36,71 +36,71 @@
36 36
37<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 37<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38 38
39<h2 id=socket>The socket namespace</h2> 39<h2 id="socket">The socket namespace</h2>
40 40
41<p> 41<p>
42The <tt>socket</tt> namespace contains the core functionality of LuaSocket. 42The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
43</p> 43</p>
44 44
45<p> 45<p>
46To obtain the <tt>socket</tt> namespace, run: 46To obtain the <tt>socket</tt> namespace, run:
47</p> 47</p>
48 48
49<pre class=example> 49<pre class="example">
50-- loads the socket module 50-- loads the socket module
51local socket = require("socket") 51local socket = require("socket")
52</pre> 52</pre>
53 53
54<!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 54<!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
55 55
56<p class=name id="headers.canonic"> 56<p class="name" id="headers.canonic">
57socket.headers.<b>canonic</b></p> 57socket.headers.<b>canonic</b></p>
58 58
59<p> The <tt>socket.headers.canonic</tt> table 59<p> The <tt>socket.headers.canonic</tt> table
60is used by the HTTP and SMTP modules to translate from 60is used by the HTTP and SMTP modules to translate from
61lowercase field names back into their canonic 61lowercase field names back into their canonic
62capitalization. When a lowercase field name exists as a key 62capitalization. When a lowercase field name exists as a key
63in this table, the associated value is substituted in 63in this table, the associated value is substituted in
64whenever the field name is sent out. 64whenever the field name is sent out.
65</p> 65</p>
66 66
67<p> 67<p>
68You can obtain the <tt>headers</tt> namespace if case run-time 68You can obtain the <tt>headers</tt> namespace if case run-time
69modifications are required by running: 69modifications are required by running:
70</p> 70</p>
71 71
72<pre class=example> 72<pre class="example">
73-- loads the headers module 73-- loads the headers module
74local headers = require("headers") 74local headers = require("headers")
75</pre> 75</pre>
76 76
77 77
78<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 78<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
79 79
80<p class=name id=bind> 80<p class="name" id="bind">
81socket.<b>bind(</b>address, port [, backlog]<b>)</b> 81socket.<b>bind(</b>address, port [, backlog]<b>)</b>
82</p> 82</p>
83 83
84<p class=description> 84<p class="description">
85This function is a shortcut that creates and returns a TCP server object 85This function is a shortcut that creates and returns a TCP server object
86bound to a local <tt>address</tt> and <tt>port</tt>, ready to 86bound to a local <tt>address</tt> and <tt>port</tt>, ready to
87accept client connections. Optionally, 87accept client connections. Optionally,
88user can also specify the <tt>backlog</tt> argument to the 88user can also specify the <tt>backlog</tt> argument to the
89<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32). 89<a href="tcp.html#listen"><tt>listen</tt></a> method (defaults to 32).
90</p> 90</p>
91 91
92<p class=note> 92<p class="note">
93Note: The server object returned will have the option "<tt>reuseaddr</tt>" 93Note: The server object returned will have the option "<tt>reuseaddr</tt>"
94set to <tt><b>true</b></tt>. 94set to <tt><b>true</b></tt>.
95</p> 95</p>
96 96
97<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 97<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
98 98
99<p class=name id=connect> 99<p class="name" id="connect">
100socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> 100socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
101</p> 101</p>
102 102
103<p class=description> 103<p class="description">
104This function is a shortcut that creates and returns a TCP client object 104This function is a shortcut that creates and returns a TCP client object
105connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, 105connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally,
106the user can also specify the local address and port to bind 106the 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
114 114
115<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 115<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
116 116
117<p class=name id=debug> 117<p class="name" id="debug">
118socket.<b>_DEBUG</b> 118socket.<b>_DEBUG</b>
119</p> 119</p>
120 120
121<p class=description> 121<p class="description">
122This constant is set to <tt><b>true</b></tt> if the library was compiled 122This constant is set to <tt><b>true</b></tt> if the library was compiled
123with debug support. 123with debug support.
124</p> 124</p>
125 125
126<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 126<!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
127 127
128<p class=name id=debug> 128<p class="name" id="datagramsize">
129socket.<b>_DATAGRAMSIZE</b> 129socket.<b>_DATAGRAMSIZE</b>
130</p> 130</p>
131 131
132<p class=description> 132<p class="description">
133Default datagram size used by calls to 133Default datagram size used by calls to
134<a href="udp.html#receive"<tt>receive</tt></a> and 134<a href="udp.html#receive"><tt>receive</tt></a> and
135<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. 135<a href="udp.html#receivefrom"><tt>receivefrom</tt></a>.
136(Unless changed in compile time, the value is 8192.) 136(Unless changed in compile time, the value is 8192.)
137</p> 137</p>
138 138
139<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 139<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
140 140
141<p class=name id=gettime> 141<p class="name" id="gettime">
142socket.<b>gettime()</b> 142socket.<b>gettime()</b>
143</p> 143</p>
144 144
145<p class=description> 145<p class="description">
146Returns the UNIX time in seconds. You should subtract the values returned by this function 146Returns the UNIX time in seconds. You should subtract the values returned by this function
147to get meaningful values. 147to get meaningful values.
148</p> 148</p>
149 149
150<pre class=example> 150<pre class="example">
151t = socket.gettime() 151t = socket.gettime()
152-- do stuff 152-- do stuff
153print(socket.gettime() - t .. " seconds elapsed") 153print(socket.gettime() - t .. " seconds elapsed")
@@ -155,38 +155,38 @@ print(socket.gettime() - t .. " seconds elapsed")
155 155
156<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 156<!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
157 157
158<p class=name id=newtry> 158<p class="name" id="newtry">
159socket.<b>newtry(</b>finalizer<b>)</b> 159socket.<b>newtry(</b>finalizer<b>)</b>
160</p> 160</p>
161 161
162<p class=description> 162<p class="description">
163Creates and returns a <em>clean</em> 163Creates and returns a <em>clean</em>
164<a href="#try"><tt>try</tt></a> 164<a href="#try"><tt>try</tt></a>
165function that allows for cleanup before the exception 165function that allows for cleanup before the exception
166is raised. 166is raised.
167</p> 167</p>
168 168
169<p class=parameters> 169<p class="parameters">
170<tt>Finalizer</tt> is a function that will be called before 170<tt>Finalizer</tt> is a function that will be called before
171<tt>try</tt> throws the exception. 171<tt>try</tt> throws the exception.
172</p> 172</p>
173 173
174<p class=return> 174<p class="return">
175The function returns your customized <tt>try</tt> function. 175The function returns your customized <tt>try</tt> function.
176</p> 176</p>
177 177
178<p class=note> 178<p class="note">
179Note: This idea saved a <em>lot</em> of work with the 179Note: This idea saved a <em>lot</em> of work with the
180implementation of protocols in LuaSocket: 180implementation of protocols in LuaSocket:
181</p> 181</p>
182 182
183<pre class=example> 183<pre class="example">
184foo = socket.protect(function() 184foo = socket.protect(function()
185 -- connect somewhere 185 -- connect somewhere
186 local c = socket.try(socket.connect("somewhere", 42)) 186 local c = socket.try(socket.connect("somewhere", 42))
187 -- create a try function that closes 'c' on error 187 -- create a try function that closes 'c' on error
188 local try = socket.newtry(function() c:close() end) 188 local try = socket.newtry(function() c:close() end)
189 -- do everything reassured c will be closed 189 -- do everything reassured c will be closed
190 try(c:send("hello there?\r\n")) 190 try(c:send("hello there?\r\n"))
191 local answer = try(c:receive()) 191 local answer = try(c:receive())
192 ... 192 ...
@@ -198,40 +198,40 @@ end)
198 198
199<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 199<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
200 200
201<p class=name id=protect> 201<p class="name" id="protect">
202socket.<b>protect(</b>func<b>)</b> 202socket.<b>protect(</b>func<b>)</b>
203</p> 203</p>
204 204
205<p class=description> 205<p class="description">
206Converts a function that throws exceptions into a safe function. This 206Converts a function that throws exceptions into a safe function. This
207function only catches exceptions thrown by the <a href=#try><tt>try</tt></a> 207function only catches exceptions thrown by the <a href="#try"><tt>try</tt></a>
208and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal 208and <a href="#newtry"><tt>newtry</tt></a> functions. It does not catch normal
209Lua errors. 209Lua errors.
210</p> 210</p>
211 211
212<p class=parameters> 212<p class="parameters">
213<tt>Func</tt> is a function that calls 213<tt>Func</tt> is a function that calls
214<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) 214<a href="#try"><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
215to throw exceptions. 215to throw exceptions.
216</p> 216</p>
217 217
218<p class=return> 218<p class="return">
219Returns an equivalent function that instead of throwing exceptions in case of 219Returns an equivalent function that instead of throwing exceptions in case of
220a failed <a href=#try><tt>try</tt></a> call, returns <tt><b>nil</b></tt> 220a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt>
221followed by an error message. 221followed by an error message.
222</p> 222</p>
223 223
224<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 224<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
225 225
226<p class=name id=select> 226<p class="name" id="select">
227socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> 227socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
228</p> 228</p>
229 229
230<p class=description> 230<p class="description">
231Waits for a number of sockets to change status. 231Waits for a number of sockets to change status.
232</p> 232</p>
233 233
234<p class=parameters> 234<p class="parameters">
235<tt>Recvt</tt> is an array with the sockets to test for characters 235<tt>Recvt</tt> is an array with the sockets to test for characters
236available for reading. Sockets in the <tt>sendt</tt> array are watched to 236available for reading. Sockets in the <tt>sendt</tt> array are watched to
237see if it is OK to immediately write on them. <tt>Timeout</tt> is the 237see 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
242non-numeric indices) in the arrays will be silently ignored. 242non-numeric indices) in the arrays will be silently ignored.
243</p> 243</p>
244 244
245<p class=return> The function returns a list with the sockets ready for 245<p class="return"> The function returns a list with the sockets ready for
246reading, a list with the sockets ready for writing and an error message. 246reading, a list with the sockets ready for writing and an error message.
247The error message is "<tt>timeout</tt>" if a timeout 247The error message is "<tt>timeout</tt>" if a timeout
248condition was met, "<tt>select failed</tt>" if the call 248condition was met, "<tt>select failed</tt>" if the call
@@ -250,10 +250,10 @@ to <tt>select</tt> failed, and
250<tt><b>nil</b></tt> otherwise. The returned tables are 250<tt><b>nil</b></tt> otherwise. The returned tables are
251doubly keyed both by integers and also by the sockets 251doubly keyed both by integers and also by the sockets
252themselves, to simplify the test if a specific socket has 252themselves, to simplify the test if a specific socket has
253changed status. 253changed status.
254</p> 254</p>
255 255
256<p class=note> 256<p class="note">
257<b>Note:</b> <tt>select</tt> can monitor a limited number 257<b>Note:</b> <tt>select</tt> can monitor a limited number
258of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This 258of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This
259number may be as high as 1024 or as low as 64 by default, 259number may be as high as 1024 or as low as 64 by default,
@@ -262,204 +262,204 @@ at compile time. Invoking <tt>select</tt> with a larger
262number of sockets will raise an error. 262number of sockets will raise an error.
263</p> 263</p>
264 264
265<p class=note> 265<p class="note">
266<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail 266<b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail
267on non-blocking TCP sockets. The function may return a socket as 267on non-blocking TCP sockets. The function may return a socket as
268writable even though the socket is <em>not</em> ready for sending. 268writable even though the socket is <em>not</em> ready for sending.
269</p> 269</p>
270 270
271<p class=note> 271<p class="note">
272<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 272<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
273<a href=tcp.html#accept><tt>accept</tt></a> will return immediately. 273<a href="tcp.html#accept"><tt>accept</tt></a> will return immediately.
274Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a> 274Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a>
275method or <tt>accept</tt> might block forever. 275method or <tt>accept</tt> might block forever.
276</p> 276</p>
277 277
278<p class=note> 278<p class="note">
279<b>Yet another note</b>: If you close a socket and pass 279<b>Yet another note</b>: If you close a socket and pass
280it to <tt>select</tt>, it will be ignored. 280it to <tt>select</tt>, it will be ignored.
281</p> 281</p>
282 282
283<p class=note> 283<p class="note">
284<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. 284<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.
285</p> 285</p>
286 286
287<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 287<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
288 288
289<p class=name id=setsize> 289<p class="name" id="setsize">
290socket.<b>_SETSIZE</b> 290socket.<b>_SETSIZE</b>
291</p> 291</p>
292 292
293<p class=description> 293<p class="description">
294The maximum number of sockets that the <a 294The maximum number of sockets that the <a
295href=#select><tt>select</tt></a> function can handle. 295href="#select"><tt>select</tt></a> function can handle.
296</p> 296</p>
297 297
298 298
299<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 299<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
300 300
301<p class=name id=sink> 301<p class="name" id="sink">
302socket.<b>sink(</b>mode, socket<b>)</b> 302socket.<b>sink(</b>mode, socket<b>)</b>
303</p> 303</p>
304 304
305<p class=description> 305<p class="description">
306Creates an 306Creates an
307<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 307<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
308sink from a stream socket object. 308sink from a stream socket object.
309</p> 309</p>
310 310
311<p class=parameters> 311<p class="parameters">
312<tt>Mode</tt> defines the behavior of the sink. The following 312<tt>Mode</tt> defines the behavior of the sink. The following
313options are available: 313options are available:
314</p> 314</p>
315<ul> 315<ul>
316<li> <tt>"http-chunked"</tt>: sends data through socket after applying the 316<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
317<em>chunked transfer coding</em>, closing the socket when done; 317<em>chunked transfer coding</em>, closing the socket when done;</li>
318<li> <tt>"close-when-done"</tt>: sends all received data through the 318<li> <tt>"close-when-done"</tt>: sends all received data through the
319socket, closing the socket when done; 319socket, closing the socket when done;</li>
320<li> <tt>"keep-open"</tt>: sends all received data through the 320<li> <tt>"keep-open"</tt>: sends all received data through the
321socket, leaving it open when done. 321socket, leaving it open when done.</li>
322</ul> 322</ul>
323<p> 323<p>
324<tt>Socket</tt> is the stream socket object used to send the data. 324<tt>Socket</tt> is the stream socket object used to send the data.
325</p> 325</p>
326 326
327<p class=return> 327<p class="return">
328The function returns a sink with the appropriate behavior. 328The function returns a sink with the appropriate behavior.
329</p> 329</p>
330 330
331<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 331<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
332 332
333<p class=name id=skip> 333<p class="name" id="skip">
334socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> 334socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
335</p> 335</p>
336 336
337<p class=description> 337<p class="description">
338Drops a number of arguments and returns the remaining. 338Drops a number of arguments and returns the remaining.
339</p> 339</p>
340 340
341<p class=parameters> 341<p class="parameters">
342<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to 342<tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
343<tt>ret<sub>N</sub></tt> are the arguments. 343<tt>ret<sub>N</sub></tt> are the arguments.
344</p> 344</p>
345 345
346<p class=return> 346<p class="return">
347The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. 347The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
348</p> 348</p>
349 349
350<p class=note> 350<p class="note">
351Note: This function is useful to avoid creation of dummy variables: 351Note: This function is useful to avoid creation of dummy variables:
352</p> 352</p>
353 353
354<pre class=example> 354<pre class="example">
355-- get the status code and separator from SMTP server reply 355-- get the status code and separator from SMTP server reply
356local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) 356local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
357</pre> 357</pre>
358 358
359<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 359<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
360 360
361<p class=name id=sleep> 361<p class="name" id="sleep">
362socket.<b>sleep(</b>time<b>)</b> 362socket.<b>sleep(</b>time<b>)</b>
363</p> 363</p>
364 364
365<p class=description> 365<p class="description">
366Freezes the program execution during a given amount of time. 366Freezes the program execution during a given amount of time.
367</p> 367</p>
368 368
369<p class=parameters> 369<p class="parameters">
370<tt>Time</tt> is the number of seconds to sleep for. If 370<tt>Time</tt> is the number of seconds to sleep for. If
371<tt>time</tt> is negative, the function returns immediately. 371<tt>time</tt> is negative, the function returns immediately.
372</p> 372</p>
373 373
374<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 374<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
375 375
376<p class=name id=source> 376<p class="name" id="source">
377socket.<b>source(</b>mode, socket [, length]<b>)</b> 377socket.<b>source(</b>mode, socket [, length]<b>)</b>
378</p> 378</p>
379 379
380<p class=description> 380<p class="description">
381Creates an 381Creates an
382<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> 382<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
383source from a stream socket object. 383source from a stream socket object.
384</p> 384</p>
385 385
386<p class=parameters> 386<p class="parameters">
387<tt>Mode</tt> defines the behavior of the source. The following 387<tt>Mode</tt> defines the behavior of the source. The following
388options are available: 388options are available:
389</p> 389</p>
390<ul> 390<ul>
391<li> <tt>"http-chunked"</tt>: receives data from socket and removes the 391<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
392<em>chunked transfer coding</em> before returning the data; 392<em>chunked transfer coding</em> before returning the data;</li>
393<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the 393<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
394socket. This mode requires the extra argument <tt>length</tt>; 394socket. This mode requires the extra argument <tt>length</tt>;</li>
395<li> <tt>"until-closed"</tt>: receives data from a socket until the other 395<li> <tt>"until-closed"</tt>: receives data from a socket until the other
396side closes the connection. 396side closes the connection.</li>
397</ul> 397</ul>
398<p> 398<p>
399<tt>Socket</tt> is the stream socket object used to receive the data. 399<tt>Socket</tt> is the stream socket object used to receive the data.
400</p> 400</p>
401 401
402<p class=return> 402<p class="return">
403The function returns a source with the appropriate behavior. 403The function returns a source with the appropriate behavior.
404</p> 404</p>
405 405
406<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 406<!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
407 407
408<p class=name id=socketinvalid> 408<p class="name" id="socketinvalid">
409socket.<b>_SOCKETINVALID</b> 409socket.<b>_SOCKETINVALID</b>
410</p> 410</p>
411 411
412<p class=description> 412<p class="description">
413The OS value for an invalid socket. 413The OS value for an invalid socket.
414</p> 414</p>
415 415
416<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 416<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
417 417
418<p class=name id=try> 418<p class="name" id="try">
419socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> 419socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
420</p> 420</p>
421 421
422<p class=description> 422<p class="description">
423Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using 423Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using
424<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught 424<tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught
425by a <a href=#protect><tt>protect</tt></a>ed function only. 425by a <a href="#protect"><tt>protect</tt></a>ed function only.
426</p> 426</p>
427 427
428<p class=parameters> 428<p class="parameters">
429<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary 429<tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
430arguments, but are usually the return values of a function call 430arguments, but are usually the return values of a function call
431nested with <tt>try</tt>. 431nested with <tt>try</tt>.
432</p> 432</p>
433 433
434<p class=return> 434<p class="return">
435The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if 435The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
436<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. 436<tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>.
437Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped 437Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped
438in a table with metatable used by <a href=#protect><tt>protect</tt></a> to 438in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to
439distinguish exceptions from runtime errors. 439distinguish exceptions from runtime errors.
440</p> 440</p>
441 441
442<pre class=example> 442<pre class="example">
443-- connects or throws an exception with the appropriate error message 443-- connects or throws an exception with the appropriate error message
444c = socket.try(socket.connect("localhost", 80)) 444c = socket.try(socket.connect("localhost", 80))
445</pre> 445</pre>
446 446
447<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 447<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
448 448
449<p class=name id=version> 449<p class="name" id="version">
450socket.<b>_VERSION</b> 450socket.<b>_VERSION</b>
451</p> 451</p>
452 452
453<p class=description> 453<p class="description">
454This constant has a string describing the current LuaSocket version. 454This constant has a string describing the current LuaSocket version.
455</p> 455</p>
456 456
457<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 457<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
458 458
459<div class=footer> 459<div class="footer">
460<hr> 460<hr>
461<center> 461<center>
462<p class=bar> 462<p class="bar">
463<a href="index.html">home</a> &middot; 463<a href="index.html">home</a> &middot;
464<a href="index.html#down">download</a> &middot; 464<a href="index.html#down">download</a> &middot;
465<a href="installation.html">installation</a> &middot; 465<a href="installation.html">installation</a> &middot;
diff --git a/doc/tcp.html b/doc/tcp.html
index 6050a5f..2d6e327 100644
--- a/doc/tcp.html
+++ b/doc/tcp.html
@@ -13,17 +13,17 @@
13 13
14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
@@ -40,42 +40,43 @@
40 40
41<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 41<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
42 42
43<p class=name id="accept"> 43<p class="name" id="accept">
44server:<b>accept()</b> 44server:<b>accept()</b>
45</p> 45</p>
46 46
47<p class=description> 47<p class="description">
48Waits for a remote connection on the server 48Waits for a remote connection on the server
49object and returns a client object representing that connection. 49object and returns a client object representing that connection.
50</p> 50</p>
51 51
52<p class=return> 52<p class="return">
53If a connection is successfully initiated, a client object is returned. 53If a connection is successfully initiated, a client object is returned.
54If a timeout condition is met, the method returns <b><tt>nil</tt></b> 54If a timeout condition is met, the method returns <b><tt>nil</tt></b>
55followed by the error string '<tt>timeout</tt>'. Other errors are 55followed by the error string '<tt>timeout</tt>'. Other errors are
56reported by <b><tt>nil</tt></b> followed by a message describing the error. 56reported by <b><tt>nil</tt></b> followed by a message describing the error.
57</p> 57</p>
58 58
59<p class=note> 59<p class="note">
60Note: calling <a href=socket.html#select><tt>socket.select</tt></a> 60Note: calling <a href="socket.html#select"><tt>socket.select</tt></a>
61with a server object in 61with a server object in
62the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does 62the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does
63<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a 63<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
64href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt> 64href="#settimeout"><tt>settimeout</tt></a> method or <tt>accept</tt>
65might block until <em>another</em> client shows up. 65might block until <em>another</em> client shows up.
66</p> 66</p>
67 67
68<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 68<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
69 69
70<p class=name id="bind"> 70<p class="name" id="bind">
71master:<b>bind(</b>address, port<b>)</b> 71master:<b>bind(</b>address, port<b>)</b>
72</p> 72</p>
73 73
74<p class=description> 74<p class="description">
75Binds a master object to <tt>address</tt> and <tt>port</tt> on the 75Binds a master object to <tt>address</tt> and <tt>port</tt> on the
76local host. 76local host.
77</p>
77 78
78<p class=parameters> 79<p class="parameters">
79<tt>Address</tt> can be an IP address or a host name. 80<tt>Address</tt> can be an IP address or a host name.
80<tt>Port</tt> must be an integer number in the range [0..64K). 81<tt>Port</tt> must be an integer number in the range [0..64K).
81If <tt>address</tt> 82If <tt>address</tt>
@@ -86,25 +87,25 @@ If <tt>port</tt> is 0, the system automatically
86chooses an ephemeral port. 87chooses an ephemeral port.
87</p> 88</p>
88 89
89<p class=return> 90<p class="return">
90In case of success, the method returns 1. In case of error, the 91In case of success, the method returns 1. In case of error, the
91method returns <b><tt>nil</tt></b> followed by an error message. 92method returns <b><tt>nil</tt></b> followed by an error message.
92</p> 93</p>
93 94
94<p class=note> 95<p class="note">
95Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a> 96Note: The function <a href="socket.html#bind"><tt>socket.bind</tt></a>
96is available and is a shortcut for the creation of server sockets. 97is available and is a shortcut for the creation of server sockets.
97</p> 98</p>
98 99
99<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 100<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
100 101
101<p class=name id="close"> 102<p class="name" id="close">
102master:<b>close()</b><br> 103master:<b>close()</b><br>
103client:<b>close()</b><br> 104client:<b>close()</b><br>
104server:<b>close()</b> 105server:<b>close()</b>
105</p> 106</p>
106 107
107<p class=description> 108<p class="description">
108Closes a TCP object. The internal socket used by the object is closed 109Closes a TCP object. The internal socket used by the object is closed
109and the local address to which the object was 110and the local address to which the object was
110bound is made available to other applications. No further operations 111bound is made available to other applications. No further operations
@@ -112,7 +113,7 @@ bound is made available to other applications. No further operations
112a closed socket. 113a closed socket.
113</p> 114</p>
114 115
115<p class=note> 116<p class="note">
116Note: It is important to close all used sockets once they are not 117Note: It is important to close all used sockets once they are not
117needed, since, in many systems, each socket uses a file descriptor, 118needed, since, in many systems, each socket uses a file descriptor,
118which are limited system resources. Garbage-collected objects are 119which are limited system resources. Garbage-collected objects are
@@ -121,53 +122,53 @@ automatically closed before destruction, though.
121 122
122<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 123<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
123 124
124<p class=name id="connect"> 125<p class="name" id="connect">
125master:<b>connect(</b>address, port<b>)</b> 126master:<b>connect(</b>address, port<b>)</b>
126</p> 127</p>
127 128
128<p class=description> 129<p class="description">
129Attempts to connect a master object to a remote host, transforming it into a 130Attempts to connect a master object to a remote host, transforming it into a
130client object. 131client object.
131Client objects support methods 132Client objects support methods
132<a href=#send><tt>send</tt></a>, 133<a href="#send"><tt>send</tt></a>,
133<a href=#receive><tt>receive</tt></a>, 134<a href="#receive"><tt>receive</tt></a>,
134<a href=#getsockname><tt>getsockname</tt></a>, 135<a href="#getsockname"><tt>getsockname</tt></a>,
135<a href=#getpeername><tt>getpeername</tt></a>, 136<a href="#getpeername"><tt>getpeername</tt></a>,
136<a href=#settimeout><tt>settimeout</tt></a>, 137<a href="#settimeout"><tt>settimeout</tt></a>,
137and <a href=#close><tt>close</tt></a>. 138and <a href="#close"><tt>close</tt></a>.
138</p> 139</p>
139 140
140<p class=parameters> 141<p class="parameters">
141<tt>Address</tt> can be an IP address or a host name. 142<tt>Address</tt> can be an IP address or a host name.
142<tt>Port</tt> must be an integer number in the range [1..64K). 143<tt>Port</tt> must be an integer number in the range [1..64K).
143</p> 144</p>
144 145
145<p class=return> 146<p class="return">
146In case of error, the method returns <b><tt>nil</tt></b> followed by a string 147In case of error, the method returns <b><tt>nil</tt></b> followed by a string
147describing the error. In case of success, the method returns 1. 148describing the error. In case of success, the method returns 1.
148</p> 149</p>
149 150
150<p class=note> 151<p class="note">
151Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a> 152Note: The function <a href="socket.html#connect"><tt>socket.connect</tt></a>
152is available and is a shortcut for the creation of client sockets. 153is available and is a shortcut for the creation of client sockets.
153</p> 154</p>
154 155
155<p class=note> 156<p class="note">
156Note: Starting with LuaSocket 2.0, 157Note: Starting with LuaSocket 2.0,
157the <a href=#settimeout><tt>settimeout</tt></a> 158the <a href="#settimeout"><tt>settimeout</tt></a>
158method affects the behavior of <tt>connect</tt>, causing it to return 159method affects the behavior of <tt>connect</tt>, causing it to return
159with an error in case of a timeout. If that happens, you can still call <a 160with an error in case of a timeout. If that happens, you can still call <a
160href=socket.html#select><tt>socket.select</tt></a> with the socket in the 161href="socket.html#select"><tt>socket.select</tt></a> with the socket in the
161<tt>sendt</tt> table. The socket will be writable when the connection is 162<tt>sendt</tt> table. The socket will be writable when the connection is
162established. 163established.
163</p> 164</p>
164 165
165<p class=note> 166<p class="note">
166Note: Starting with LuaSocket 3.0, the host name resolution 167Note: Starting with LuaSocket 3.0, the host name resolution
167depends on whether the socket was created by 168depends on whether the socket was created by
168<a href=#socket.tcp><tt>socket.tcp</tt></a>, 169<a href="#socket.tcp"><tt>socket.tcp</tt></a>,
169<a href=#socket.tcp4><tt>socket.tcp4</tt></a> or 170<a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or
170<a href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from 171<a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from
171the appropriate family (or both) are tried in the order 172the appropriate family (or both) are tried in the order
172returned by the resolver until the 173returned by the resolver until the
173first success or until the last failure. If the timeout was 174first success or until the last failure. If the timeout was
@@ -176,42 +177,42 @@ set to zero, only the first address is tried.
176 177
177<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 178<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
178 179
179<p class=name id="dirty"> 180<p class="name" id="dirty">
180master:<b>dirty()</b><br> 181master:<b>dirty()</b><br>
181client:<b>dirty()</b><br> 182client:<b>dirty()</b><br>
182server:<b>dirty()</b> 183server:<b>dirty()</b>
183</p> 184</p>
184 185
185<p class=description> 186<p class="description">
186Check the read buffer status. 187Check the read buffer status.
187</p> 188</p>
188 189
189<p class=return> 190<p class="return">
190Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. 191Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
191</p> 192</p>
192 193
193<p class=note> 194<p class="note">
194Note: <b>This is an internal method, use at your own risk.</b> 195Note: <b>This is an internal method, use at your own risk.</b>
195</p> 196</p>
196 197
197 198
198<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 199<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
199 200
200<p class=name id="getfd"> 201<p class="name" id="getfd">
201master:<b>getfd()</b><br> 202master:<b>getfd()</b><br>
202client:<b>getfd()</b><br> 203client:<b>getfd()</b><br>
203server:<b>getfd()</b> 204server:<b>getfd()</b>
204</p> 205</p>
205 206
206<p class=description> 207<p class="description">
207Returns the underling socket descriptor or handle associated to the object. 208Returns the underling socket descriptor or handle associated to the object.
208</p> 209</p>
209 210
210<p class=return> 211<p class="return">
211The descriptor or handle. In case the object has been closed, the return will be -1. 212The descriptor or handle. In case the object has been closed, the return will be -1.
212</p> 213</p>
213 214
214<p class=note> 215<p class="note">
215Note: <b>This is an internal method. Unlikely to be 216Note: <b>This is an internal method. Unlikely to be
216portable. Use at your own risk. </b> 217portable. Use at your own risk. </b>
217</p> 218</p>
@@ -219,28 +220,27 @@ portable. Use at your own risk. </b>
219 220
220<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 221<!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
221 222
222<p class=name id="getoption"> 223<p class="name" id="getoption">
223client:<b>getoption(</b>option)</b><br> 224client:<b>getoption(option)</b><br>
224server:<b>getoption(</b>option)</b> 225server:<b>getoption(option)</b>
225</p> 226</p>
226 227
227<p class=description> 228<p class="description">
228Gets options for the TCP object. 229Gets options for the TCP object.
229See <a href=#setoption><tt>setoption</tt></a> for description of the 230See <a href="#setoption"><tt>setoption</tt></a> for description of the
230option names and values. 231option names and values.
231</p> 232</p>
232 233
233<p class=parameters> 234<p class="parameters">
234<tt>Option</tt> is a string with the option name. 235<tt>Option</tt> is a string with the option name.</p>
235<ul> 236<ul>
236 237<li> '<tt>keepalive</tt>'</li>
237<li> '<tt>keepalive</tt>' 238<li> '<tt>linger</tt>'</li>
238<li> '<tt>linger</tt>' 239<li> '<tt>reuseaddr</tt>'</li>
239<li> '<tt>reuseaddr</tt>' 240<li> '<tt>tcp-nodelay</tt>'</li>
240<li> '<tt>tcp-nodelay</tt>'
241</ul> 241</ul>
242 242
243<p class=return> 243<p class="return">
244The method returns the option <tt>value</tt> in case of success, or 244The method returns the option <tt>value</tt> in case of success, or
245<b><tt>nil</tt></b> followed by an error message otherwise. 245<b><tt>nil</tt></b> followed by an error message otherwise.
246</p> 246</p>
@@ -248,38 +248,38 @@ The method returns the option <tt>value</tt> in case of success, or
248 248
249<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 249<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
250 250
251<p class=name id="getpeername"> 251<p class="name" id="getpeername">
252client:<b>getpeername()</b> 252client:<b>getpeername()</b>
253</p> 253</p>
254 254
255<p class=description> 255<p class="description">
256Returns information about the remote side of a connected client object. 256Returns information about the remote side of a connected client object.
257</p> 257</p>
258 258
259<p class=return> 259<p class="return">
260Returns a string with the IP address of the peer, the 260Returns a string with the IP address of the peer, the
261port number that peer is using for the connection, 261port number that peer is using for the connection,
262and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 262and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
263In case of error, the method returns <b><tt>nil</tt></b>. 263In case of error, the method returns <b><tt>nil</tt></b>.
264</p> 264</p>
265 265
266<p class=note> 266<p class="note">
267Note: It makes no sense to call this method on server objects. 267Note: It makes no sense to call this method on server objects.
268</p> 268</p>
269 269
270<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 270<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
271 271
272<p class=name id="getsockname"> 272<p class="name" id="getsockname">
273master:<b>getsockname()</b><br> 273master:<b>getsockname()</b><br>
274client:<b>getsockname()</b><br> 274client:<b>getsockname()</b><br>
275server:<b>getsockname()</b> 275server:<b>getsockname()</b>
276</p> 276</p>
277 277
278<p class=description> 278<p class="description">
279Returns the local address information associated to the object. 279Returns the local address information associated to the object.
280</p> 280</p>
281 281
282<p class=return> 282<p class="return">
283The method returns a string with local IP address, a number with 283The method returns a string with local IP address, a number with
284the local port, 284the local port,
285and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 285and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@@ -288,31 +288,31 @@ In case of error, the method returns <b><tt>nil</tt></b>.
288 288
289<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 289<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
290 290
291<p class=name id="getstats"> 291<p class="name" id="getstats">
292master:<b>getstats()</b><br> 292master:<b>getstats()</b><br>
293client:<b>getstats()</b><br> 293client:<b>getstats()</b><br>
294server:<b>getstats()</b><br> 294server:<b>getstats()</b><br>
295</p> 295</p>
296 296
297<p class=description> 297<p class="description">
298Returns accounting information on the socket, useful for throttling 298Returns accounting information on the socket, useful for throttling
299of bandwidth. 299of bandwidth.
300</p> 300</p>
301 301
302<p class=return> 302<p class="return">
303The method returns the number of bytes received, the number of bytes sent, 303The method returns the number of bytes received, the number of bytes sent,
304and the age of the socket object in seconds. 304and the age of the socket object in seconds.
305</p> 305</p>
306 306
307<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 307<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
308 308
309<p class=name id="gettimeout"> 309<p class="name" id="gettimeout">
310master:<b>gettimeout()</b><br> 310master:<b>gettimeout()</b><br>
311client:<b>gettimeout()</b><br> 311client:<b>gettimeout()</b><br>
312server:<b>gettimeout()</b> 312server:<b>gettimeout()</b>
313</p> 313</p>
314 314
315<p class=description> 315<p class="description">
316Returns the current block timeout followed by the curent 316Returns the current block timeout followed by the curent
317total timeout. 317total timeout.
318</p> 318</p>
@@ -320,65 +320,65 @@ total timeout.
320 320
321<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 321<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
322 322
323<p class=name id="listen"> 323<p class="name" id="listen">
324master:<b>listen(</b>backlog<b>)</b> 324master:<b>listen(</b>backlog<b>)</b>
325</p> 325</p>
326 326
327<p class=description> 327<p class="description">
328Specifies the socket is willing to receive connections, transforming the 328Specifies the socket is willing to receive connections, transforming the
329object into a server object. Server objects support the 329object into a server object. Server objects support the
330<a href=#accept><tt>accept</tt></a>, 330<a href="#accept"><tt>accept</tt></a>,
331<a href=#getsockname><tt>getsockname</tt></a>, 331<a href="#getsockname"><tt>getsockname</tt></a>,
332<a href=#setoption><tt>setoption</tt></a>, 332<a href="#setoption"><tt>setoption</tt></a>,
333<a href=#settimeout><tt>settimeout</tt></a>, 333<a href="#settimeout"><tt>settimeout</tt></a>,
334and <a href=#close><tt>close</tt></a> methods. 334and <a href="#close"><tt>close</tt></a> methods.
335</p> 335</p>
336 336
337<p class=parameters> 337<p class="parameters">
338The parameter <tt>backlog</tt> specifies the number of client 338The parameter <tt>backlog</tt> specifies the number of client
339connections that can 339connections that can
340be queued waiting for service. If the queue is full and another client 340be queued waiting for service. If the queue is full and another client
341attempts connection, the connection is refused. 341attempts connection, the connection is refused.
342</p> 342</p>
343 343
344<p class=return> 344<p class="return">
345In case of success, the method returns 1. In case of error, the 345In case of success, the method returns 1. In case of error, the
346method returns <b><tt>nil</tt></b> followed by an error message. 346method returns <b><tt>nil</tt></b> followed by an error message.
347</p> 347</p>
348 348
349<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 349<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
350 350
351<p class=name id="receive"> 351<p class="name" id="receive">
352client:<b>receive(</b>[pattern [, prefix]]<b>)</b> 352client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
353</p> 353</p>
354 354
355<p class=description> 355<p class="description">
356Reads data from a client object, according to the specified <em>read 356Reads data from a client object, according to the specified <em>read
357pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. 357pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
358</p> 358</p>
359 359
360<p class=parameters> 360<p class="parameters">
361<tt>Pattern</tt> can be any of the following: 361<tt>Pattern</tt> can be any of the following:
362</p> 362</p>
363 363
364<ul> 364<ul>
365<li> '<tt>*a</tt>': reads from the socket until the connection is 365<li> '<tt>*a</tt>': reads from the socket until the connection is
366closed. No end-of-line translation is performed; 366closed. No end-of-line translation is performed;</li>
367<li> '<tt>*l</tt>': reads a line of text from the socket. The line is 367<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
368terminated by a LF character (ASCII&nbsp;10), optionally preceded by a 368terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
369CR character (ASCII&nbsp;13). The CR and LF characters are not included in 369CR character (ASCII&nbsp;13). The CR and LF characters are not included in
370the returned line. In fact, <em>all</em> CR characters are 370the returned line. In fact, <em>all</em> CR characters are
371ignored by the pattern. This is the default pattern; 371ignored by the pattern. This is the default pattern;</li>
372<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> 372<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
373of bytes from the socket. 373of bytes from the socket.</li>
374</ul> 374</ul>
375 375
376<p class=parameters> 376<p class="parameters">
377<tt>Prefix</tt> is an optional string to be concatenated to the beginning 377<tt>Prefix</tt> is an optional string to be concatenated to the beginning
378of any received data before return. 378of any received data before return.
379</p> 379</p>
380 380
381<p class=return> 381<p class="return">
382If successful, the method returns the received pattern. In case of error, 382If successful, the method returns the received pattern. In case of error,
383the method returns <tt><b>nil</b></tt> followed by an error 383the method returns <tt><b>nil</b></tt> followed by an error
384message, followed by a (possibly empty) string containing 384message, followed by a (possibly empty) string containing
@@ -388,7 +388,7 @@ closed before the transmission was completed or the string
388'<tt>timeout</tt>' in case there was a timeout during the operation. 388'<tt>timeout</tt>' in case there was a timeout during the operation.
389</p> 389</p>
390 390
391<p class=note> 391<p class="note">
392<b>Important note</b>: This function was changed <em>severely</em>. It used 392<b>Important note</b>: This function was changed <em>severely</em>. It used
393to support multiple patterns (but I have never seen this feature used) and 393to support multiple patterns (but I have never seen this feature used) and
394now it doesn't anymore. Partial results used to be returned in the same 394now it doesn't anymore. Partial results used to be returned in the same
@@ -399,22 +399,22 @@ too.
399 399
400<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 400<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
401 401
402<p class=name id="send"> 402<p class="name" id="send">
403client:<b>send(</b>data [, i [, j]]<b>)</b> 403client:<b>send(</b>data [, i [, j]]<b>)</b>
404</p> 404</p>
405 405
406<p class=description> 406<p class="description">
407Sends <tt>data</tt> through client object. 407Sends <tt>data</tt> through client object.
408</p> 408</p>
409 409
410<p class=parameters> 410<p class="parameters">
411<tt>Data</tt> is the string to be sent. The optional arguments 411<tt>Data</tt> is the string to be sent. The optional arguments
412<tt>i</tt> and <tt>j</tt> work exactly like the standard 412<tt>i</tt> and <tt>j</tt> work exactly like the standard
413<tt>string.sub</tt> Lua function to allow the selection of a 413<tt>string.sub</tt> Lua function to allow the selection of a
414substring to be sent. 414substring to be sent.
415</p> 415</p>
416 416
417<p class=return> 417<p class="return">
418If successful, the method returns the index of the last byte 418If successful, the method returns the index of the last byte
419within <tt>[i, j]</tt> that has been sent. Notice that, if 419within <tt>[i, j]</tt> that has been sent. Notice that, if
420<tt>i</tt> is 1 or absent, this is effectively the total 420<tt>i</tt> is 1 or absent, this is effectively the total
@@ -428,7 +428,7 @@ was completed or the string '<tt>timeout</tt>' in case
428there was a timeout during the operation. 428there was a timeout during the operation.
429</p> 429</p>
430 430
431<p class=note> 431<p class="note">
432Note: Output is <em>not</em> buffered. For small strings, 432Note: Output is <em>not</em> buffered. For small strings,
433it is always better to concatenate them in Lua 433it is always better to concatenate them in Lua
434(with the '<tt>..</tt>' operator) and send the result in one call 434(with the '<tt>..</tt>' operator) and send the result in one call
@@ -437,27 +437,27 @@ instead of calling the method several times.
437 437
438<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 438<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
439 439
440<p class=name id="setoption"> 440<p class="name" id="setoption">
441client:<b>setoption(</b>option [, value]<b>)</b><br> 441client:<b>setoption(</b>option [, value]<b>)</b><br>
442server:<b>setoption(</b>option [, value]<b>)</b> 442server:<b>setoption(</b>option [, value]<b>)</b>
443</p> 443</p>
444 444
445<p class=description> 445<p class="description">
446Sets options for the TCP object. Options are only needed by low-level or 446Sets options for the TCP object. Options are only needed by low-level or
447time-critical applications. You should only modify an option if you 447time-critical applications. You should only modify an option if you
448are sure you need it. 448are sure you need it.
449</p> 449</p>
450 450
451<p class=parameters> 451<p class="parameters">
452<tt>Option</tt> is a string with the option name, and <tt>value</tt> 452<tt>Option</tt> is a string with the option name, and <tt>value</tt>
453depends on the option being set: 453depends on the option being set:</p>
454 454
455<ul> 455<ul>
456 456
457<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables 457<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
458the periodic transmission of messages on a connected socket. Should the 458the periodic transmission of messages on a connected socket. Should the
459connected party fail to respond to these messages, the connection is 459connected party fail to respond to these messages, the connection is
460considered broken and processes using the socket are notified; 460considered broken and processes using the socket are notified;</li>
461 461
462<li> '<tt>linger</tt>': Controls the action taken when unsent data are 462<li> '<tt>linger</tt>': Controls the action taken when unsent data are
463queued on a socket and a close is performed. The value is a table with a 463queued on a socket and a close is performed. The value is a table with a
@@ -468,79 +468,79 @@ it is able to transmit the data or until '<tt>timeout</tt>' has passed. If
468'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will 468'<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will
469process the close in a manner that allows the process to continue as 469process the close in a manner that allows the process to continue as
470quickly as possible. I do not advise you to set this to anything other than 470quickly as possible. I do not advise you to set this to anything other than
471zero; 471zero;</li>
472 472
473<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules 473<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
474used in validating addresses supplied in a call to 474used in validating addresses supplied in a call to
475<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses; 475<a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li>
476 476
477<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> 477<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
478disables the Nagle's algorithm for the connection; 478disables the Nagle's algorithm for the connection;</li>
479 479
480<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!! 480<li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li>
481 481
482<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!! 482<li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li>
483 483
484<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!! 484<li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li>
485 485
486<li> '<tt>ipv6-v6only</tt>': 486<li> '<tt>ipv6-v6only</tt>':
487Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to 487Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to
488sending and receiving only IPv6 packets. 488sending and receiving only IPv6 packets.</li>
489</ul> 489</ul>
490 490
491<p class=return> 491<p class="return">
492The method returns 1 in case of success, or <b><tt>nil</tt></b> 492The method returns 1 in case of success, or <b><tt>nil</tt></b>
493followed by an error message otherwise. 493followed by an error message otherwise.
494</p> 494</p>
495 495
496<p class=note> 496<p class="note">
497Note: The descriptions above come from the man pages. 497Note: The descriptions above come from the man pages.
498</p> 498</p>
499 499
500<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 500<!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
501 501
502<p class=name id="setstats"> 502<p class="name" id="setstats">
503master:<b>setstats(</b>received, sent, age<b>)</b><br> 503master:<b>setstats(</b>received, sent, age<b>)</b><br>
504client:<b>setstats(</b>received, sent, age<b>)</b><br> 504client:<b>setstats(</b>received, sent, age<b>)</b><br>
505server:<b>setstats(</b>received, sent, age<b>)</b><br> 505server:<b>setstats(</b>received, sent, age<b>)</b><br>
506</p> 506</p>
507 507
508<p class=description> 508<p class="description">
509Resets accounting information on the socket, useful for throttling 509Resets accounting information on the socket, useful for throttling
510of bandwidth. 510of bandwidth.
511</p> 511</p>
512 512
513<p class=parameters> 513<p class="parameters">
514<tt>Received</tt> is a number with the new number of bytes received. 514<tt>Received</tt> is a number with the new number of bytes received.
515<tt>Sent</tt> is a number with the new number of bytes sent. 515<tt>Sent</tt> is a number with the new number of bytes sent.
516<tt>Age</tt> is the new age in seconds. 516<tt>Age</tt> is the new age in seconds.
517</p> 517</p>
518 518
519<p class=return> 519<p class="return">
520The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. 520The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
521</p> 521</p>
522 522
523<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 523<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
524 524
525<p class=name id="settimeout"> 525<p class="name" id="settimeout">
526master:<b>settimeout(</b>value [, mode]<b>)</b><br> 526master:<b>settimeout(</b>value [, mode]<b>)</b><br>
527client:<b>settimeout(</b>value [, mode]<b>)</b><br> 527client:<b>settimeout(</b>value [, mode]<b>)</b><br>
528server:<b>settimeout(</b>value [, mode]<b>)</b> 528server:<b>settimeout(</b>value [, mode]<b>)</b>
529</p> 529</p>
530 530
531<p class=description> 531<p class="description">
532Changes the timeout values for the object. By default, 532Changes the timeout values for the object. By default,
533all I/O operations are blocking. That is, any call to the methods 533all I/O operations are blocking. That is, any call to the methods
534<a href=#send><tt>send</tt></a>, 534<a href="#send"><tt>send</tt></a>,
535<a href=#receive><tt>receive</tt></a>, and 535<a href="#receive"><tt>receive</tt></a>, and
536<a href=#accept><tt>accept</tt></a> 536<a href="#accept"><tt>accept</tt></a>
537will block indefinitely, until the operation completes. The 537will block indefinitely, until the operation completes. The
538<tt>settimeout</tt> method defines a limit on the amount of time the 538<tt>settimeout</tt> method defines a limit on the amount of time the
539I/O methods can block. When a timeout is set and the specified amount of 539I/O methods can block. When a timeout is set and the specified amount of
540time has elapsed, the affected methods give up and fail with an error code. 540time has elapsed, the affected methods give up and fail with an error code.
541</p> 541</p>
542 542
543<p class=parameters> 543<p class="parameters">
544The amount of time to wait is specified as the 544The amount of time to wait is specified as the
545<tt>value</tt> parameter, in seconds. There are two timeout modes and 545<tt>value</tt> parameter, in seconds. There are two timeout modes and
546both can be used together for fine tuning: 546both can be used together for fine tuning:
@@ -557,12 +557,12 @@ the amount of time LuaSocket can block a Lua script before returning from
557a call.</li> 557a call.</li>
558</ul> 558</ul>
559 559
560<p class=parameters> 560<p class="parameters">
561The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block 561The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block
562indefinitely. Negative timeout values have the same effect. 562indefinitely. Negative timeout values have the same effect.
563</p> 563</p>
564 564
565<p class=note> 565<p class="note">
566Note: although timeout values have millisecond precision in LuaSocket, 566Note: although timeout values have millisecond precision in LuaSocket,
567large blocks can cause I/O functions not to respect timeout values due 567large blocks can cause I/O functions not to respect timeout values due
568to the time the library takes to transfer blocks to and from the OS 568to the time the library takes to transfer blocks to and from the OS
@@ -571,7 +571,7 @@ and perform automatic name resolution might be blocked by the resolver for
571longer than the specified timeout value. 571longer than the specified timeout value.
572</p> 572</p>
573 573
574<p class=note> 574<p class="note">
575Note: The old <tt>timeout</tt> method is deprecated. The name has been 575Note: The old <tt>timeout</tt> method is deprecated. The name has been
576changed for sake of uniformity, since all other method names already 576changed for sake of uniformity, since all other method names already
577contained verbs making their imperative nature obvious. 577contained verbs making their imperative nature obvious.
@@ -579,123 +579,124 @@ contained verbs making their imperative nature obvious.
579 579
580<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 580<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
581 581
582<p class=name id="shutdown"> 582<p class="name" id="shutdown">
583client:<b>shutdown(</b>mode<b>)</b><br> 583client:<b>shutdown(</b>mode<b>)</b><br>
584</p> 584</p>
585 585
586<p class=description> 586<p class="description">
587Shuts down part of a full-duplex connection. 587Shuts down part of a full-duplex connection.
588</p> 588</p>
589 589
590<p class=parameters> 590<p class="parameters">
591Mode tells which way of the connection should be shut down and can 591Mode tells which way of the connection should be shut down and can
592take the value: 592take the value:
593<ul> 593<ul>
594<li>"<tt>both</tt>": disallow further sends and receives on the object. 594<li>"<tt>both</tt>": disallow further sends and receives on the object.
595This is the default mode; 595This is the default mode;</li>
596<li>"<tt>send</tt>": disallow further sends on the object; 596<li>"<tt>send</tt>": disallow further sends on the object;</li>
597<li>"<tt>receive</tt>": disallow further receives on the object. 597<li>"<tt>receive</tt>": disallow further receives on the object.</li>
598</ul> 598</ul>
599</p>
599 600
600<p class=return> 601<p class="return">
601This function returns 1. 602This function returns 1.
602</p> 603</p>
603 604
604<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 605<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
605 606
606<p class=name id="setfd"> 607<p class="name" id="setfd">
607master:<b>setfd(</b>fd<b>)</b><br> 608master:<b>setfd(</b>fd<b>)</b><br>
608client:<b>setfd(</b>fd<b>)</b><br> 609client:<b>setfd(</b>fd<b>)</b><br>
609server:<b>setfd(</b>fd<b>)</b> 610server:<b>setfd(</b>fd<b>)</b>
610</p> 611</p>
611 612
612<p class=description> 613<p class="description">
613Sets 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. 614Sets 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.
614</p> 615</p>
615 616
616<p class=return> 617<p class="return">
617No return value. 618No return value.
618</p> 619</p>
619 620
620<p class=note> 621<p class="note">
621Note: <b>This is an internal method. Unlikely to be 622Note: <b>This is an internal method. Unlikely to be
622portable. Use at your own risk. </b> 623portable. Use at your own risk. </b>
623</p> 624</p>
624 625
625<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 626<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
626 627
627<p class=name id="socket.tcp"> 628<p class="name" id="socket.tcp">
628socket.<b>tcp()</b> 629socket.<b>tcp()</b>
629</p> 630</p>
630 631
631<p class=description> 632<p class="description">
632Creates and returns an TCP master object. A master object can 633Creates and returns an TCP master object. A master object can
633be transformed into a server object with the method 634be transformed into a server object with the method
634<a href=#listen><tt>listen</tt></a> (after a call to <a 635<a href="#listen"><tt>listen</tt></a> (after a call to <a
635href=#bind><tt>bind</tt></a>) or into a client object with 636href="#bind"><tt>bind</tt></a>) or into a client object with
636the method <a href=#connect><tt>connect</tt></a>. The only other 637the method <a href="#connect"><tt>connect</tt></a>. The only other
637method supported by a master object is the 638method supported by a master object is the
638<a href=#close><tt>close</tt></a> method.</p> 639<a href="#close"><tt>close</tt></a> method.</p>
639 640
640<p class=return> 641<p class="return">
641In case of success, a new master object is returned. In case of error, 642In case of success, a new master object is returned. In case of error,
642<b><tt>nil</tt></b> is returned, followed by an error message. 643<b><tt>nil</tt></b> is returned, followed by an error message.
643</p> 644</p>
644 645
645<p class=note> 646<p class="note">
646Note: The choice between IPv4 and IPv6 happens during a call to 647Note: The choice between IPv4 and IPv6 happens during a call to
647<a href=#bind><tt>bind</tt></a> or <a 648<a href="#bind"><tt>bind</tt></a> or <a
648href=#bind><tt>connect</tt></a>, depending on the address 649href="#bind"><tt>connect</tt></a>, depending on the address
649family obtained from the resolver. 650family obtained from the resolver.
650</p> 651</p>
651 652
652<p class=note> 653<p class="note">
653Note: Before the choice between IPv4 and IPv6 happens, 654Note: Before the choice between IPv4 and IPv6 happens,
654the internal socket object is invalid and therefore <a 655the internal socket object is invalid and therefore <a
655href=#setoption><tt>setoption</tt></a> will fail. 656href="#setoption"><tt>setoption</tt></a> will fail.
656</p> 657</p>
657 658
658<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 659<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
659 660
660<p class=name id="socket.tcp4"> 661<p class="name" id="socket.tcp4">
661socket.<b>tcp4()</b> 662socket.<b>tcp4()</b>
662</p> 663</p>
663 664
664<p class=description> 665<p class="description">
665Creates and returns an IPv4 TCP master object. A master object can 666Creates and returns an IPv4 TCP master object. A master object can
666be transformed into a server object with the method 667be transformed into a server object with the method
667<a href=#listen><tt>listen</tt></a> (after a call to <a 668<a href="#listen"><tt>listen</tt></a> (after a call to <a
668href=#bind><tt>bind</tt></a>) or into a client object with 669href="#bind"><tt>bind</tt></a>) or into a client object with
669the method <a href=#connect><tt>connect</tt></a>. The only other 670the method <a href="#connect"><tt>connect</tt></a>. The only other
670method supported by a master object is the 671method supported by a master object is the
671<a href=#close><tt>close</tt></a> method.</p> 672<a href="#close"><tt>close</tt></a> method.</p>
672 673
673<p class=return> 674<p class="return">
674In case of success, a new master object is returned. In case of error, 675In case of success, a new master object is returned. In case of error,
675<b><tt>nil</tt></b> is returned, followed by an error message. 676<b><tt>nil</tt></b> is returned, followed by an error message.
676</p> 677</p>
677 678
678<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 679<!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
679 680
680<p class=name id="socket.tcp6"> 681<p class="name" id="socket.tcp6">
681socket.<b>tcp6()</b> 682socket.<b>tcp6()</b>
682</p> 683</p>
683 684
684<p class=description> 685<p class="description">
685Creates and returns an IPv6 TCP master object. A master object can 686Creates and returns an IPv6 TCP master object. A master object can
686be transformed into a server object with the method 687be transformed into a server object with the method
687<a href=#listen><tt>listen</tt></a> (after a call to <a 688<a href="#listen"><tt>listen</tt></a> (after a call to <a
688href=#bind><tt>bind</tt></a>) or into a client object with 689href="#bind"><tt>bind</tt></a>) or into a client object with
689the method <a href=#connect><tt>connect</tt></a>. The only other 690the method <a href="#connect"><tt>connect</tt></a>. The only other
690method supported by a master object is the 691method supported by a master object is the
691<a href=#close><tt>close</tt></a> method.</p> 692<a href="#close"><tt>close</tt></a> method.</p>
692 693
693<p class=return> 694<p class="return">
694In case of success, a new master object is returned. In case of error, 695In case of success, a new master object is returned. In case of error,
695<b><tt>nil</tt></b> is returned, followed by an error message. 696<b><tt>nil</tt></b> is returned, followed by an error message.
696</p> 697</p>
697 698
698<p class=note> 699<p class="note">
699Note: The TCP object returned will have the option 700Note: The TCP object returned will have the option
700"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. 701"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
701</p> 702</p>
@@ -704,10 +705,10 @@ Note: The TCP object returned will have the option
704 705
705<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 706<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
706 707
707<div class=footer> 708<div class="footer">
708<hr> 709<hr>
709<center> 710<center>
710<p class=bar> 711<p class="bar">
711<a href="index.html">home</a> &middot; 712<a href="index.html">home</a> &middot;
712<a href="index.html#down">download</a> &middot; 713<a href="index.html#down">download</a> &middot;
713<a href="installation.html">installation</a> &middot; 714<a href="installation.html">installation</a> &middot;
diff --git a/doc/udp.html b/doc/udp.html
index 4618aad..db711cb 100644
--- a/doc/udp.html
+++ b/doc/udp.html
@@ -13,17 +13,17 @@
13 13
14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15 15
16<div class=header> 16<div class="header">
17<hr> 17<hr>
18<center> 18<center>
19<table summary="LuaSocket logo"> 19<table summary="LuaSocket logo">
20<tr><td align=center><a href="http://www.lua.org"> 20<tr><td align="center"><a href="http://www.lua.org">
21<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> 21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr> 22</a></td></tr>
23<tr><td align=center valign=top>Network support for the Lua language 23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr> 24</td></tr>
25</table> 25</table>
26<p class=bar> 26<p class="bar">
27<a href="index.html">home</a> &middot; 27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot; 28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot; 29<a href="installation.html">installation</a> &middot;
@@ -71,26 +71,26 @@ unconnected:<b>getoption()</b>
71 71
72<p class="description"> 72<p class="description">
73Gets an option value from the UDP object. 73Gets an option value from the UDP object.
74See <a href=#setoption><tt>setoption</tt></a> for 74See <a href="#setoption"><tt>setoption</tt></a> for
75description of the option names and values. 75description of the option names and values.
76</p> 76</p>
77 77
78<p class="parameters"><tt>Option</tt> is a string with the option name. 78<p class="parameters"><tt>Option</tt> is a string with the option name.
79<ul> 79<ul>
80<li> '<tt>dontroute</tt>' 80<li> '<tt>dontroute</tt>'</li>
81<li> '<tt>broadcast</tt>' 81<li> '<tt>broadcast</tt>'</li>
82<li> '<tt>reuseaddr</tt>' 82<li> '<tt>reuseaddr</tt>'</li>
83<li> '<tt>reuseport</tt>' 83<li> '<tt>reuseport</tt>'</li>
84<li> '<tt>ip-multicast-loop</tt>' 84<li> '<tt>ip-multicast-loop</tt>'</li>
85<li> '<tt>ipv6-v6only</tt>' 85<li> '<tt>ipv6-v6only</tt>'</li>
86<li> '<tt>ip-multicast-if</tt>' 86<li> '<tt>ip-multicast-if</tt>'</li>
87<li> '<tt>ip-multicast-ttl</tt>' 87<li> '<tt>ip-multicast-ttl</tt>'</li>
88<li> '<tt>ip-add-membership</tt>' 88<li> '<tt>ip-add-membership</tt>'</li>
89<li> '<tt>ip-drop-membership</tt>' 89<li> '<tt>ip-drop-membership</tt>'</li>
90</ul> 90</ul>
91</p> 91</p>
92 92
93<p class=return> 93<p class="return">
94The method returns the option <tt>value</tt> in case of 94The method returns the option <tt>value</tt> in case of
95success, or 95success, or
96<b><tt>nil</tt></b> followed by an error message otherwise. 96<b><tt>nil</tt></b> followed by an error message otherwise.
@@ -108,7 +108,7 @@ associated with a connected UDP object.
108</p> 108</p>
109 109
110 110
111<p class=return> 111<p class="return">
112Returns a string with the IP address of the peer, the 112Returns a string with the IP address of the peer, the
113port number that peer is using for the connection, 113port number that peer is using for the connection,
114and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 114and 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.
131</p> 131</p>
132 132
133 133
134<p class=return> 134<p class="return">
135The method returns a string with local IP address, a number with 135The method returns a string with local IP address, a number with
136the local port, 136the local port,
137and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). 137and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
@@ -148,12 +148,12 @@ wild-card address).
148 148
149<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 149<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
150 150
151<p class=name id="gettimeout"> 151<p class="name" id="gettimeout">
152connected:<b>settimeout(</b>value<b>)</b><br> 152connected:<b>settimeout(</b>value<b>)</b><br>
153unconnected:<b>settimeout(</b>value<b>)</b> 153unconnected:<b>settimeout(</b>value<b>)</b>
154</p> 154</p>
155 155
156<p class=description> 156<p class="description">
157Returns the current timeout value. 157Returns the current timeout value.
158</p> 158</p>
159 159
@@ -180,8 +180,8 @@ the excess bytes are discarded. If there are less then
180<tt>size</tt> bytes available in the current datagram, the 180<tt>size</tt> bytes available in the current datagram, the
181available bytes are returned. 181available bytes are returned.
182If <tt>size</tt> is omitted, the 182If <tt>size</tt> is omitted, the
183compile-time constant <a 183compile-time constant <a href="socket.html#datagramsize">
184href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used 184<tt>socket._DATAGRAMSIZE</tt></a> is used
185(it defaults to 8192 bytes). Larger sizes will cause a 185(it defaults to 8192 bytes). Larger sizes will cause a
186temporary buffer to be allocated for the operation. 186temporary buffer to be allocated for the operation.
187</p> 187</p>
@@ -286,45 +286,45 @@ name, and <tt>value</tt> depends on the option being set:
286<ul> 286<ul>
287<li> '<tt>dontroute</tt>': Indicates that outgoing 287<li> '<tt>dontroute</tt>': Indicates that outgoing
288messages should bypass the standard routing facilities. 288messages should bypass the standard routing facilities.
289Receives a boolean value; 289Receives a boolean value;</li>
290<li> '<tt>broadcast</tt>': Requests permission to send 290<li> '<tt>broadcast</tt>': Requests permission to send
291broadcast datagrams on the socket. 291broadcast datagrams on the socket.
292Receives a boolean value; 292Receives a boolean value;</li>
293<li> '<tt>reuseaddr</tt>': Indicates that the rules used in 293<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
294validating addresses supplied in a <tt>bind()</tt> call 294validating addresses supplied in a <tt>bind()</tt> call
295should allow reuse of local addresses. 295should allow reuse of local addresses.
296Receives a boolean value; 296Receives a boolean value;</li>
297<li> '<tt>reuseport</tt>': Allows completely duplicate 297<li> '<tt>reuseport</tt>': Allows completely duplicate
298bindings by multiple processes if they all set 298bindings by multiple processes if they all set
299'<tt>reuseport</tt>' before binding the port. 299'<tt>reuseport</tt>' before binding the port.
300Receives a boolean value; 300Receives a boolean value;</li>
301<li> '<tt>ip-multicast-loop</tt>': 301<li> '<tt>ip-multicast-loop</tt>':
302Specifies whether or not a copy of an outgoing multicast 302Specifies whether or not a copy of an outgoing multicast
303datagram is delivered to the sending host as long as it is a 303datagram is delivered to the sending host as long as it is a
304member of the multicast group. 304member of the multicast group.
305Receives a boolean value; 305Receives a boolean value;</li>
306<li> '<tt>ipv6-v6only</tt>': 306<li> '<tt>ipv6-v6only</tt>':
307Specifies whether to restrict <tt>inet6</tt> sockets to 307Specifies whether to restrict <tt>inet6</tt> sockets to
308sending and receiving only IPv6 packets. 308sending and receiving only IPv6 packets.
309Receive a boolean value; 309Receive a boolean value;</li>
310<li> '<tt>ip-multicast-if</tt>': 310<li> '<tt>ip-multicast-if</tt>':
311Sets the interface over which outgoing multicast datagrams 311Sets the interface over which outgoing multicast datagrams
312are sent. 312are sent.
313Receives an IP address; 313Receives an IP address;</li>
314<li> '<tt>ip-multicast-ttl</tt>': 314<li> '<tt>ip-multicast-ttl</tt>':
315Sets the Time To Live in the IP header for outgoing 315Sets the Time To Live in the IP header for outgoing
316multicast datagrams. 316multicast datagrams.
317Receives a number; 317Receives a number;</li>
318<li> '<tt>ip-add-membership</tt>': 318<li> '<tt>ip-add-membership</tt>':
319Joins the multicast group specified. 319Joins the multicast group specified.
320Receives a table with fields 320Receives a table with fields
321<tt>multiaddr</tt> and <tt>interface</tt>, each containing an 321<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
322IP address; 322IP address;</li>
323<li> '<tt>ip-drop-membership</tt>': Leaves the multicast 323<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
324group specified. 324group specified.
325Receives a table with fields 325Receives a table with fields
326<tt>multiaddr</tt> and <tt>interface</tt>, each containing an 326<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
327IP address. 327IP address.</li>
328</ul> 328</ul>
329 329
330<p class="return"> 330<p class="return">
@@ -332,7 +332,7 @@ The method returns 1 in case of success, or
332<b><tt>nil</tt></b> followed by an error message otherwise. 332<b><tt>nil</tt></b> followed by an error message otherwise.
333</p> 333</p>
334 334
335<p class=note> 335<p class="note">
336Note: The descriptions above come from the man pages. 336Note: The descriptions above come from the man pages.
337</p> 337</p>
338 338
@@ -381,11 +381,11 @@ is recommended when the same peer is used for several transmissions
381and can result in up to 30% performance gains. 381and can result in up to 30% performance gains.
382</p> 382</p>
383 383
384<p class=note> 384<p class="note">
385Note: Starting with LuaSocket 3.0, the host name resolution 385Note: Starting with LuaSocket 3.0, the host name resolution
386depends on whether the socket was created by <a 386depends on whether the socket was created by <a
387href=#socket.udp><tt>socket.udp</tt></a> or <a 387href="#socket.udp"><tt>socket.udp</tt></a> or <a
388href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from 388href="#socket.udp6"><tt>socket.udp6</tt></a>. Addresses from
389the appropriate family are tried in succession until the 389the appropriate family are tried in succession until the
390first success or until the last failure. 390first success or until the last failure.
391</p> 391</p>
@@ -492,23 +492,23 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
492an error message. 492an error message.
493</p> 493</p>
494 494
495<p class=note> 495<p class="note">
496Note: The choice between IPv4 and IPv6 happens during a call to 496Note: The choice between IPv4 and IPv6 happens during a call to
497<a href=#sendto><tt>sendto</tt></a>, <a 497<a href="#sendto"><tt>sendto</tt></a>, <a
498href=#setpeername><tt>setpeername</tt></a>, or <a 498href="#setpeername"><tt>setpeername</tt></a>, or <a
499href=#setsockname><tt>sockname</tt></a>, depending on the address 499href="#setsockname"><tt>sockname</tt></a>, depending on the address
500family obtained from the resolver. 500family obtained from the resolver.
501</p> 501</p>
502 502
503<p class=note> 503<p class="note">
504Note: Before the choice between IPv4 and IPv6 happens, 504Note: Before the choice between IPv4 and IPv6 happens,
505the internal socket object is invalid and therefore <a 505the internal socket object is invalid and therefore <a
506href=#setoption><tt>setoption</tt></a> will fail. 506href="#setoption"><tt>setoption</tt></a> will fail.
507</p> 507</p>
508 508
509<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 509<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
510 510
511<p class="name" id="socket.udp"> 511<p class="name" id="socket.udp4">
512socket.<b>udp4()</b> 512socket.<b>udp4()</b>
513</p> 513</p>
514 514
@@ -564,7 +564,7 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
564an error message. 564an error message.
565</p> 565</p>
566 566
567<p class=note> 567<p class="note">
568Note: The TCP object returned will have the option 568Note: The TCP object returned will have the option
569"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. 569"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
570</p> 570</p>
@@ -573,10 +573,10 @@ Note: The TCP object returned will have the option
573 573
574<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> 574<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
575 575
576<div class=footer> 576<div class="footer">
577<hr> 577<hr>
578<center> 578<center>
579<p class=bar> 579<p class="bar">
580<a href="index.html">home</a> &middot; 580<a href="index.html">home</a> &middot;
581<a href="index.html#download">download</a> &middot; 581<a href="index.html#download">download</a> &middot;
582<a href="installation.html">installation</a> &middot; 582<a href="installation.html">installation</a> &middot;
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-15 19:40:32 +0000