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