aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
committerCaleb Maclennan <caleb@alerque.com>2023-11-10 09:12:04 +0300
commit5c4fc93d5f4137bf4c22ddf1a048c907a4a26727 (patch)
treea9a68e1f6a9c3bfe2b64fa1c3a4098865b7d3b5d /doc
parentccef3bc4e2aa6ee5b997a80aabb58f4ff0b0e98f (diff)
parent43a97b7f0053313b43906371dbdc226271e6c8ab (diff)
downloadluasocket-hjelmeland-patch-1.tar.gz
luasocket-hjelmeland-patch-1.tar.bz2
luasocket-hjelmeland-patch-1.zip
Merge branch 'master' into hjelmeland-patch-1hjelmeland-patch-1
Diffstat (limited to 'doc')
-rw-r--r--doc/dns.html183
-rw-r--r--doc/ftp.html289
-rw-r--r--doc/http.html332
-rw-r--r--doc/index.html215
-rw-r--r--doc/installation.html127
-rw-r--r--doc/introduction.html333
-rw-r--r--doc/ltn12.html430
-rw-r--r--doc/lua05.pptbin304128 -> 0 bytes
-rw-r--r--doc/luasocket.pngbin11732 -> 0 bytes
-rw-r--r--doc/mime.html476
-rw-r--r--doc/reference.css55
-rw-r--r--doc/reference.html256
-rw-r--r--doc/smtp.html417
-rw-r--r--doc/socket.html456
-rw-r--r--doc/tcp.html697
-rw-r--r--doc/udp.html578
-rw-r--r--doc/url.html328
17 files changed, 0 insertions, 5172 deletions
diff --git a/doc/dns.html b/doc/dns.html
deleted file mode 100644
index c4a0472..0000000
--- a/doc/dns.html
+++ /dev/null
@@ -1,183 +0,0 @@
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="LuaSocket: DNS support">
7<meta name="keywords" content="Lua, LuaSocket, DNS, Network, Library, Support">
8<title>LuaSocket: DNS support</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<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id=dns>DNS</h2>
40
41<p>
42IPv4 name resolution functions
43<a href=#toip><tt>dns.toip</tt></a>
44and
45<a href=#tohostname><tt>dns.tohostname</tt></a>
46return <em>all</em> information obtained from
47the resolver in a table of the form:
48</p>
49
50<blockquote><tt>
51resolved4 = {<br>
52&nbsp;&nbsp;name = <i>canonic-name</i>,<br>
53&nbsp;&nbsp;alias = <i>alias-list</i>,<br>
54&nbsp;&nbsp;ip = <i>ip-address-list</i><br>
55}
56</tt> </blockquote>
57
58<p>
59Note that the <tt>alias</tt> list can be empty.
60</p>
61
62<p>
63The more general name resolution function
64<a href=#getaddrinfo><tt>dns.getaddrinfo</tt></a>, which
65supports both IPv6 and IPv4,
66returns <em>all</em> information obtained from
67the resolver in a table of the form:
68</p>
69
70<blockquote><tt>
71resolved6 = {<br>
72&nbsp;&nbsp;[1] = {<br>
73&nbsp;&nbsp;&nbsp;&nbsp;family = <i>family-name-1</i>,<br>
74&nbsp;&nbsp;&nbsp;&nbsp;addr = <i>address-1</i><br>
75&nbsp;&nbsp;},<br>
76&nbsp;&nbsp;...<br>
77&nbsp;&nbsp;[n] = {<br>
78&nbsp;&nbsp;&nbsp;&nbsp;family = <i>family-name-n</i>,<br>
79&nbsp;&nbsp;&nbsp;&nbsp;addr = <i>address-n</i><br>
80&nbsp;&nbsp;}<br>
81}
82</tt> </blockquote>
83
84<p>
85Here, <tt>family</tt> contains the string <tt>"inet"</tt> for IPv4
86addresses, and <tt>"inet6"</tt> for IPv6 addresses.
87</p>
88
89<!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
90
91<p class=name id=getaddrinfo>
92socket.dns.<b>getaddrinfo(</b>address<b>)</b>
93</p>
94
95<p class=description>
96Converts from host name to address.
97</p>
98
99<p class=parameters>
100<tt>Address</tt> can be an IPv4 or IPv6 address or host name.
101</p>
102
103<p class=return>
104The function returns a table with all information returned by
105the resolver. In case of error, the function returns <b><tt>nil</tt></b>
106followed by an error message.
107</p>
108
109<!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111<p class=name id=gethostname>
112socket.dns.<b>gethostname()</b>
113</p>
114
115<p class=description>
116Returns the standard host name for the machine as a string.
117</p>
118
119<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
120
121<p class=name id=tohostname>
122socket.dns.<b>tohostname(</b>address<b>)</b>
123</p>
124
125<p class=description>
126Converts from IPv4 address to host name.
127</p>
128
129<p class=parameters>
130<tt>Address</tt> can be an IP address or host name.
131</p>
132
133<p class=return>
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
136the resolver. In case of error, the function returns <b><tt>nil</tt></b>
137followed by an error message.
138</p>
139
140<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
141
142<p class=name id=toip>
143socket.dns.<b>toip(</b>address<b>)</b>
144</p>
145
146<p class=description>
147Converts from host name to IPv4 address.
148</p>
149
150<p class=parameters>
151<tt>Address</tt> can be an IP address or host name.
152</p>
153
154<p class=return>
155Returns a string with the first IP address found for <tt>address</tt>,
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
158message.
159</p>
160
161<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
162
163<div class=footer>
164<hr>
165<center>
166<p class=bar>
167<a href="index.html">home</a> &middot;
168<a href="index.html#down">download</a> &middot;
169<a href="installation.html">installation</a> &middot;
170<a href="introduction.html">introduction</a> &middot;
171<a href="reference.html">reference</a>
172</p>
173<p>
174<small>
175Last modified by Diego Nehab on <br>
176Thu Apr 20 00:25:07 EDT 2006
177</small>
178</p>
179</center>
180</div>
181
182</body>
183</html>
diff --git a/doc/ftp.html b/doc/ftp.html
deleted file mode 100644
index 3f23a4a..0000000
--- a/doc/ftp.html
+++ /dev/null
@@ -1,289 +0,0 @@
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="LuaSocket: FTP support">
7<meta name="keywords" content="Lua, LuaSocket, FTP, Network, Library, Support">
8<title>LuaSocket: FTP support</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<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id=ftp>FTP</h2>
40
41<p>
42FTP (File Transfer Protocol) is a protocol used to transfer files
43between hosts. The <tt>ftp</tt> namespace offers thorough support
44to FTP, under a simple interface. The implementation conforms to
45<a href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</a>.
46</p>
47
48<p>
49High level functions are provided supporting the most common operations.
50These high level functions are implemented on top of a lower level
51interface. Using the low-level interface, users can easily create their
52own functions to access <em>any</em> operation supported by the FTP
53protocol. For that, check the implementation.
54</p>
55
56<p>
57To really benefit from this module, a good understanding of
58<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
59LTN012, Filters sources and sinks</a> is necessary.
60</p>
61
62<p>
63To obtain the <tt>ftp</tt> namespace, run:
64</p>
65
66<pre class=example>
67-- loads the FTP module and any libraries it requires
68local ftp = require("socket.ftp")
69</pre>
70
71<p>
72URLs MUST conform to
73<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
74that is, an URL is a string in the form:
75</p>
76
77<blockquote>
78<tt>
79[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i]</tt>
80</blockquote>
81
82<p>
83The following constants in the namespace can be set to control the default behavior of
84the FTP module:
85</p>
86
87<ul>
88<li> <tt>PASSWORD</tt>: default anonymous password.
89<li> <tt>PORT</tt>: default port used for the control connection;
90<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
91<li> <tt>USER</tt>: default anonymous user;
92</ul>
93
94
95<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
96
97<p class=name id=get>
98ftp.<b>get(</b>url<b>)</b><br>
99ftp.<b>get{</b><br>
100&nbsp;&nbsp;host = <i>string</i>,<br>
101&nbsp;&nbsp;sink = <i>LTN12 sink</i>,<br>
102&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
103&nbsp;&nbsp;[user = <i>string</i>,]<br>
104&nbsp;&nbsp;[password = <i>string</i>]<br>
105&nbsp;&nbsp;[command = <i>string</i>,]<br>
106&nbsp;&nbsp;[port = <i>number</i>,]<br>
107&nbsp;&nbsp;[type = <i>string</i>,]<br>
108&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
109&nbsp;&nbsp;[create = <i>function</i>]<br>
110<b>}</b>
111</p>
112
113<p class=description>
114The <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
116string. The generic form allows a <em>lot</em> more control, as explained
117below.
118</p>
119
120<p class=parameters>
121If 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
123<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
125the <em>simple</em>
126<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
127sink 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
129optional arguments are the following:
130</p>
131<ul>
132<li><tt>user</tt>, <tt>password</tt>: User name and password used for
133authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
134<li><tt>command</tt>: The FTP command used to obtain data. Defaults to
135"<tt>retr</tt>", but see example below;
136<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
137<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;
139<li><tt>step</tt>:
140<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
141pump step function used to pass data from the
142server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
143<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.
145</ul>
146
147<p class=return>
148If successful, the simple version returns the URL contents as a
149string, and the generic function returns 1. In case of error, both
150functions return <b><tt>nil</tt></b> and an error message describing the
151error.
152</p>
153
154<pre class=example>
155-- load the ftp support
156local ftp = require("socket.ftp")
157
158-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
159-- and get file "lua.tar.gz" from directory "pub/lua" as binary.
160f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
161</pre>
162
163<pre class=example>
164-- load needed modules
165local ftp = require("socket.ftp")
166local ltn12 = require("ltn12")
167local url = require("socket.url")
168
169-- a function that returns a directory listing
170function nlst(u)
171 local t = {}
172 local p = url.parse(u)
173 p.command = "nlst"
174 p.sink = ltn12.sink.table(t)
175 local r, e = ftp.get(p)
176 return r and table.concat(t), e
177end
178</pre>
179
180<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
181
182<p class=name id=put>
183ftp.<b>put(</b>url, content<b>)</b><br>
184ftp.<b>put{</b><br>
185&nbsp;&nbsp;host = <i>string</i>,<br>
186&nbsp;&nbsp;source = <i>LTN12 sink</i>,<br>
187&nbsp;&nbsp;argument <i>or</i> path = <i>string</i>,<br>
188&nbsp;&nbsp;[user = <i>string</i>,]<br>
189&nbsp;&nbsp;[password = <i>string</i>]<br>
190&nbsp;&nbsp;[command = <i>string</i>,]<br>
191&nbsp;&nbsp;[port = <i>number</i>,]<br>
192&nbsp;&nbsp;[type = <i>string</i>,]<br>
193&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
194&nbsp;&nbsp;[create = <i>function</i>]<br>
195<b>}</b>
196</p>
197
198<p class=description>
199The <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
201allows a <em>lot</em> more control, as explained below.
202</p>
203
204<p class=parameters>
205If 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
207<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
209the <em>simple</em>
210<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
211source that will provide the contents to be uploaded.
212<tt>Argument</tt> or
213<tt>path</tt> give the target path to the resource in the server. The
214optional arguments are the following:
215</p>
216<ul>
217<li><tt>user</tt>, <tt>password</tt>: User name and password used for
218authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";
219<li><tt>command</tt>: The FTP command used to send data. Defaults to
220"<tt>stor</tt>", but see example below;
221<li><tt>port</tt>: The port to used for the control connection. Defaults to 21;
222<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;
224<li><tt>step</tt>:
225<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
226pump step function used to pass data from the
227server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;
228<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.
230</ul>
231
232<p class=return>
233Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error
234message describing the reason for failure.
235</p>
236
237<pre class=example>
238-- load the ftp support
239local ftp = require("socket.ftp")
240
241-- Log as user "fulano" on server "ftp.example.com",
242-- using password "silva", and store a file "README" with contents
243-- "wrong password, of course"
244f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
245 "wrong password, of course")
246</pre>
247
248<pre class=example>
249-- load the ftp support
250local ftp = require("socket.ftp")
251local ltn12 = require("ltn12")
252
253-- Log as user "fulano" on server "ftp.example.com",
254-- using password "silva", and append to the remote file "LOG", sending the
255-- contents of the local file "LOCAL-LOG"
256f, e = ftp.put{
257 host = "ftp.example.com",
258 user = "fulano",
259 password = "silva",
260 command = "appe",
261 argument = "LOG",
262 source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
263}
264</pre>
265
266
267<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
268
269<div class=footer>
270<hr>
271<center>
272<p class=bar>
273<a href="index.html">home</a> &middot;
274<a href="index.html#download">download</a> &middot;
275<a href="installation.html">installation</a> &middot;
276<a href="introduction.html">introduction</a> &middot;
277<a href="reference.html">reference</a>
278</p>
279<p>
280<small>
281Last modified by Diego Nehab on <br>
282Thu Apr 20 00:25:18 EDT 2006
283</small>
284</p>
285</center>
286</div>
287
288</body>
289</html>
diff --git a/doc/http.html b/doc/http.html
deleted file mode 100644
index cd41c0d..0000000
--- a/doc/http.html
+++ /dev/null
@@ -1,332 +0,0 @@
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="LuaSocket: HTTP support">
7<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support">
8<title>LuaSocket: HTTP support</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="introduction.html">introduction</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<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id="http">HTTP</h2>
40
41<p>
42HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange
43information between web-browsers and servers. The <tt>http</tt>
44namespace offers full support for the client side of the HTTP
45protocol (i.e.,
46the facilities that would be used by a web-browser implementation). The
47implementation conforms to the HTTP/1.1 standard,
48<a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
49</p>
50
51<p>
52The module exports functions that provide HTTP functionality in different
53levels of abstraction. From the simple
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.
56</p>
57
58<p>
59To obtain the <tt>http</tt> namespace, run:
60</p>
61
62<pre class=example>
63-- loads the HTTP module and any libraries it requires
64local http = require("socket.http")
65</pre>
66
67<p>
68URLs must conform to
69<a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>,
70that is, an URL is a string in the form:
71</p>
72
73<blockquote>
74<pre>
75[http://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;]
76</pre>
77</blockquote>
78
79<p>
80MIME headers are represented as a Lua table in the form:
81</p>
82
83<blockquote>
84<table summary="MIME headers in Lua table">
85<tr><td><tt>
86headers = {<br>
87&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
88&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
89&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
90&nbsp;&nbsp;...<br>
91&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
92}
93</tt></td></tr>
94</table>
95</blockquote>
96
97<p>
98Field names are case insensitive (as specified by the standard) and all
99functions work with lowercase field names (but see
100<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>).
101Field values are left unmodified.
102</p>
103
104<p class=note>
105Note: MIME headers are independent of order. Therefore, there is no problem
106in representing them in a Lua table.
107</p>
108
109<p>
110The following constants can be set to control the default behavior of
111the HTTP module:
112</p>
113
114<ul>
115<li> <tt>PORT</tt>: default port used for connections;
116<li> <tt>PROXY</tt>: default proxy used for connections;
117<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
118<li> <tt>USERAGENT</tt>: default user agent reported to server.
119</ul>
120
121
122<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
123
124<p class=name id="request">
125http.<b>request(</b>url [, body]<b>)</b><br>
126http.<b>request{</b><br>
127&nbsp;&nbsp;url = <i>string</i>,<br>
128&nbsp;&nbsp;[sink = <i>LTN12 sink</i>,]<br>
129&nbsp;&nbsp;[method = <i>string</i>,]<br>
130&nbsp;&nbsp;[headers = <i>header-table</i>,]<br>
131&nbsp;&nbsp;[source = <i>LTN12 source</i>],<br>
132&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
133&nbsp;&nbsp;[proxy = <i>string</i>,]<br>
134&nbsp;&nbsp;[redirect = <i>boolean</i>,]<br>
135&nbsp;&nbsp;[create = <i>function</i>]<br>
136<b>}</b>
137</p>
138
139<p class=description>
140The request function has two forms. The simple form downloads
141a 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
143<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based.
144</p>
145
146<p class=parameters>
147If 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>
149is 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
151<tt>url</tt>
152</p>
153
154<p class=parameters>
155If the first argument is instead a table, the most important fields are
156the <tt>url</tt> and the <em>simple</em>
157<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
158<tt>sink</tt> that will receive the downloaded content.
159Any part of the <tt>url</tt> can be overridden by including
160the appropriate field in the request table.
161If authentication information is provided, the function
162uses the Basic Authentication Scheme (see <a href="#authentication">note</a>)
163to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the
164function discards the downloaded data. The optional parameters are the
165following:
166</p>
167<ul>
168<li><tt>method</tt>: The HTTP request method. Defaults to "GET";
169<li><tt>headers</tt>: Any additional HTTP headers to send with the request;
170<li><tt>source</tt>: <em>simple</em>
171<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
172source to provide the request body. If there
173is 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
175"<tt>chunked</tt>" (something few servers support). Defaults to the empty source;
176<li><tt>step</tt>:
177<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
178pump step function used to move data.
179Defaults to the LTN12 <tt>pump.step</tt> function.
180<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;
181<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
182function from automatically following 301 or 302 server redirect messages;
183<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.
185</ul>
186
187<p class=return>
188In case of failure, the function returns <tt><b>nil</b></tt> followed by an
189error message. If successful, the simple form returns the response
190body as a string, followed by the response status code, the response
191headers and the response status line. The generic function returns the same
192information, except the first return value is just the number 1 (the body
193goes to the <tt>sink</tt>).
194</p>
195
196<p class=return>
197Even 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
199URL was not found or some other useless page). To make sure the
200operation was successful, check the returned status <tt>code</tt>. For
201a list of the possible values and their meanings, refer to <a
202href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>.
203</p>
204
205<p class=description>
206Here are a few examples with the simple interface:
207</p>
208
209<pre class=example>
210-- load the http module
211local io = require("io")
212local http = require("socket.http")
213local ltn12 = require("ltn12")
214
215-- connect to server "www.cs.princeton.edu" and retrieves this manual
216-- file from "~diego/professional/luasocket/http.html" and print it to stdout
217http.request{
218 url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html",
219 sink = ltn12.sink.file(io.stdout)
220}
221
222-- connect to server "www.example.com" and tries to retrieve
223-- "/private/index.html". Fails because authentication is needed.
224b, c, h = http.request("http://www.example.com/private/index.html")
225-- b returns some useless page telling about the denied access,
226-- h returns authentication information
227-- and c returns with value 401 (Authentication Required)
228
229-- tries to connect to server "wrong.host" to retrieve "/"
230-- and fails because the host does not exist.
231r, e = http.request("http://wrong.host/")
232-- r is nil, and e returns with value "host not found"
233</pre>
234
235<p class=description>
236And here is an example using the generic interface:
237</p>
238
239<pre class=example>
240-- load the http module
241http = require("socket.http")
242
243-- Requests information about a document, without downloading it.
244-- Useful, for example, if you want to display a download gauge and need
245-- to know the size of the document in advance
246r, c, h = http.request {
247 method = "HEAD",
248 url = "http://www.tecgraf.puc-rio.br/~diego"
249}
250-- r is 1, c is 200, and h would return the following headers:
251-- h = {
252-- date = "Tue, 18 Sep 2001 20:42:21 GMT",
253-- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)",
254-- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
255-- ["content-length"] = 15652,
256-- ["connection"] = "close",
257-- ["content-Type"] = "text/html"
258-- }
259</pre>
260
261<p class=note id="post">
262Note: When sending a POST request, simple interface adds a
263"<tt>Content-type: application/x-www-form-urlencoded</tt>"
264header to the request. This is the type used by
265HTML forms. If you need another type, use the generic
266interface.
267</p>
268
269<p class=note id="authentication">
270Note: Some URLs are protected by their
271servers from anonymous download. For those URLs, the server must receive
272some sort of authentication along with the request or it will deny
273download and return status "401&nbsp;Authentication Required".
274</p>
275
276<p class=note>
277The HTTP/1.1 standard defines two authentication methods: the Basic
278Authentication Scheme and the Digest Authentication Scheme, both
279explained in detail in
280<a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>.
281</p>
282
283<p class=note>The Basic Authentication Scheme sends
284<tt>&lt;user&gt;</tt> and
285<tt>&lt;password&gt;</tt> unencrypted to the server and is therefore
286considered unsafe. Unfortunately, by the time of this implementation,
287the wide majority of servers and browsers support the Basic Scheme only.
288Therefore, this is the method used by the toolkit whenever
289authentication is required.
290</p>
291
292<pre class=example>
293-- load required modules
294http = require("socket.http")
295mime = require("mime")
296
297-- Connect to server "www.example.com" and tries to retrieve
298-- "/private/index.html", using the provided name and password to
299-- authenticate the request
300b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html")
301
302-- Alternatively, one could fill the appropriate header and authenticate
303-- the request directly.
304r, c = http.request {
305 url = "http://www.example.com/private/index.html",
306 headers = { authorization = "Basic " .. (mime.b64("fulano:silva")) }
307}
308</pre>
309
310<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
311
312<div class=footer>
313<hr>
314<center>
315<p class=bar>
316<a href="index.html">home</a> &middot;
317<a href="index.html#download">download</a> &middot;
318<a href="installation.html">installation</a> &middot;
319<a href="introduction.html">introduction</a> &middot;
320<a href="reference.html">reference</a>
321</p>
322<p>
323<small>
324Last modified by Diego Nehab on <br>
325Thu Apr 20 00:25:26 EDT 2006
326</small>
327</p>
328</center>
329</div>
330
331</body>
332</html>
diff --git a/doc/index.html b/doc/index.html
deleted file mode 100644
index 7d81b41..0000000
--- a/doc/index.html
+++ /dev/null
@@ -1,215 +0,0 @@
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.0-rc1 is now available for download!
91It is compatible with Lua&nbsp;5.1 and 5.2, and has
92been tested on Windows&nbsp;XP, Linux, and Mac OS X. Chances
93are it works well on most UNIX distributions and Windows flavors.
94</p>
95
96<p>
97The current version of the library can be found at
98the <a href="https://github.com/diegonehab/luasocket">LuaSocket
99project page</a> on GitHub. Besides the full C and Lua source code
100for the library, the distribution contains several examples,
101this user's manual and basic test procedures.
102</p>
103
104<p> Take a look at the <a
105href=installation.html>installation</a> section of the
106manual to find out how to properly install the library.
107</p>
108
109<!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111<h2 id=thanks>Special thanks</h2>
112
113<p>
114This marks the first release of LuaSocket that
115wholeheartedly embraces the open-source development
116philosophy. After a long hiatus, Matthew Wild finally
117convinced me it was time for a release including IPv6 and
118Lua 5.2 support. It was more work than we anticipated.
119Special thanks to Sam Roberts, Florian Zeitz, and Paul
120Aurich, Liam Devine, Alexey Melnichuk, and everybody else
121that has helped bring this library back to life.
122</p>
123
124<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
125
126<h2 id=new>What's New</h2>
127
128<p>
129Main changes for LuaSocket&nbsp;3.0-rc1 are IPv6 support
130and Lua&nbsp;5.2 compatibility.
131</p>
132
133<ul>
134<li> Added: Compatible with Lua&nbsp;5.2
135<ul>
136<li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>,
137package tables will <em>not</em> be exported as globals!
138</ul>
139<li> Added: IPv6 support;
140<ul>
141<li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;
142<li> <tt>Getpeername</tt> and <tt>getsockname</tt> support
143IPv6 addresses, and return the socket family as a third value;
144<li> URL module updated to support IPv6 host names;
145<li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;
146<li> New <tt>socket.dns.getaddrinfo</tt> and
147 <tt>socket.dns.getnameinfo</tt> functions;
148</ul>
149<li> Added: <tt>getoption</tt> method;
150<li> Fixed: <tt>url.unescape</tt> was returning additional values;
151<li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>,
152 <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could
153 mistaking their own stack slots for functions arguments;
154<li> Fixed: Receiving zero-length datagram is now possible;
155<li> Improved: Hidden all internal library symbols;
156<li> Improved: Better error messages;
157<li> Improved: Better documentation of socket options.
158<li> Fixed: manual sample of HTTP authentication now uses correct
159 "authorization" header (Alexandre Ittner);
160<li> Fixed: failure on bind() was destroying the socket (Sam Roberts);
161<li> Fixed: receive() returns immediatelly if prefix can satisfy
162 bytes requested (M Joonas Pihlaja);
163<li> Fixed: multicast didn't work on Windows, or anywhere
164 else for that matter (Herbert Leuwer, Adrian Sietsma);
165<li> Fixed: select() now reports an error when called with more
166 sockets than FD_SETSIZE (Lorenzo Leonini);
167<li> Fixed: manual links to home.html changed to index.html
168(Robert Hahn);
169<li> Fixed: mime.unb64() would return an empty string on results that started
170 with a null character (Robert Raschke);
171<li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);
172<li> Fixed: calling sleep() with negative numbers could
173 block forever, wasting CPU. Now it returns immediately (MPB);
174<li> Improved: FTP commands are now sent in upper case to
175 help buggy servers (Anders Eurenius);
176<li> Improved: known headers now sent in canonic
177 capitalization to help buggy servers (Joseph Stewart);
178<li> Improved: Clarified tcp:receive() in the manual (MPB);
179<li> Improved: Decent makefiles (LHF).
180<li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).
181</ul>
182
183<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
184
185<h2 id=old>Old Versions</h2>
186
187<p>
188All previous versions of the LuaSocket library can be downloaded <a
189href="http://www.impa.br/~diego/software/luasocket/old">
190here</a>. Although these versions are no longer supported, they are
191still available for those that have compatibility issues.
192</p>
193
194<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
195
196<div class=footer>
197<hr>
198<center>
199<p class=bar>
200<a href="index.html#download">download</a> &middot;
201<a href="installation.html">installation</a> &middot;
202<a href="introduction.html">introduction</a> &middot;
203<a href="reference.html">reference</a>
204</p>
205<p>
206<small>
207Last modified by Diego Nehab on <br>
208Tue Jun 11 18:50:23 HKT 2013
209</small>
210</p>
211</center>
212</div>
213
214</body>
215</html>
diff --git a/doc/installation.html b/doc/installation.html
deleted file mode 100644
index 28a9fbb..0000000
--- a/doc/installation.html
+++ /dev/null
@@ -1,127 +0,0 @@
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="LuaSocket: Introduction to the core">
7<meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network, Support,
8Installation">
9<title>LuaSocket: Installation</title>
10<link rel="stylesheet" href="reference.css" type="text/css">
11</head>
12
13<body>
14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17<div class=header>
18<hr>
19<center>
20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language
25</td></tr>
26</table>
27<p class=bar>
28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a>
33</p>
34</center>
35<hr>
36</div>
37
38<!-- installation ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2>Installation</h2>
41
42<p> Here we describe the standard distribution. If the
43standard doesn't meet your needs, we refer you to the Lua
44discussion list, where any question about the package scheme
45will likely already have been answered. </p>
46
47<h3>Directory structure</h3>
48
49<p> On Unix systems, the standard distribution uses two base
50directories, one for system dependent files, and another for system
51independent files. Let's call these directories <tt>&lt;CDIR&gt;</tt>
52and <tt>&lt;LDIR&gt;</tt>, respectively.
53For example, in my laptp, Lua&nbsp;5.1 is configured to
54use '<tt>/usr/local/lib/lua/5.1</tt>' for
55<tt>&lt;CDIR&gt;</tt> and '<tt>/usr/local/share/lua/5.1</tt>' for
56<tt>&lt;LDIR&gt;</tt>. On Windows, <tt>&lt;CDIR&gt;</tt>
57usually points to the directory where the Lua executable is
58found, and <tt>&lt;LDIR&gt;</tt> points to a
59<tt>lua/</tt> directory inside <tt>&lt;CDIR&gt;</tt>. (These
60settings can be overridden by environment variables
61<tt>LUA_PATH</tt> and <tt>LUA_CPATH</tt>. See the Lua
62documentation for details.) Here is the standard LuaSocket
63distribution directory structure:</p>
64
65<pre class=example>
66&lt;LDIR&gt;/ltn12.lua
67&lt;LDIR&gt;/socket.lua
68&lt;CDIR&gt;/socket/core.dll
69&lt;LDIR&gt;/socket/http.lua
70&lt;LDIR&gt;/socket/tp.lua
71&lt;LDIR&gt;/socket/ftp.lua
72&lt;LDIR&gt;/socket/smtp.lua
73&lt;LDIR&gt;/socket/url.lua
74&lt;LDIR&gt;/mime.lua
75&lt;CDIR&gt;/mime/core.dll
76</pre>
77
78<p> Naturally, on Unix systems, <tt>core.dll</tt>
79would be replaced by <tt>core.so</tt>.
80</p>
81
82<h3>Using LuaSocket</h3>
83
84<p> With the above setup, and an interpreter with shared library support,
85it should be easy to use LuaSocket. Just fire the interpreter and use the
86<tt>require</tt> function to gain access to whatever module you need:</p>
87
88<pre class=example>
89Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio
90&gt; socket = require("socket")
91&gt; print(socket._VERSION)
92--&gt; LuaSocket 3.0-rc1
93</pre>
94
95<p> Each module loads their dependencies automatically, so you only need to
96load the modules you directly depend upon: </p>
97
98<pre class=example>
99Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio
100&gt; http = require("socket.http")
101&gt; print(http.request("http://www.impa.br/~diego/software/luasocket"))
102--&gt; homepage gets dumped to terminal
103</pre>
104
105<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
106
107<div class=footer>
108<hr>
109<center>
110<p class=bar>
111<a href="index.html">home</a> &middot;
112<a href="index.html#down">download</a> &middot;
113<a href="installation.html">installation</a> &middot;
114<a href="introduction.html">introduction</a> &middot;
115<a href="reference.html">reference</a>
116</p>
117<p>
118<small>
119Last modified by Diego Nehab on <br>
120Tue Jun 11 19:06:14 HKT 2013
121</small>
122</p>
123</center>
124</div>
125
126</body>
127</html>
diff --git a/doc/introduction.html b/doc/introduction.html
deleted file mode 100644
index fd22f48..0000000
--- a/doc/introduction.html
+++ /dev/null
@@ -1,333 +0,0 @@
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="LuaSocket: Introduction to the core">
7<meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network,
8Library, Support">
9<title>LuaSocket: Introduction to the core</title>
10<link rel="stylesheet" href="reference.css" type="text/css">
11</head>
12
13<body>
14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17<div class=header>
18<hr>
19<center>
20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language
25</td></tr>
26</table>
27<p class=bar>
28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a>
33</p>
34</center>
35<hr>
36</div>
37
38<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2>Introduction</h2>
41
42<p>
43LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
44that is composed by two parts: a C core that provides support for the TCP
45and UDP transport layers, and a set of Lua modules that add support for
46the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
47downloading files) protocols and other functionality commonly needed by
48applications that deal with the Internet. This introduction is about the C
49core.
50</p>
51
52<p>
53Communication in LuaSocket is performed via I/O objects. These can
54represent different network domains. Currently, support is provided for TCP
55and UDP, but nothing prevents other developers from implementing SSL, Local
56Domain, Pipes, File Descriptors etc. I/O objects provide a standard
57interface to I/O across different domains and operating systems.
58</p>
59
60<p>
61The API design had two goals in mind. First, users
62experienced with the C API to sockets should feel comfortable using LuaSocket.
63Second, the simplicity and the feel of the Lua language should be
64preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified.
65</p>
66
67
68<p>
69One of the simplifications is the receive pattern capability.
70Applications can read data from stream domains (such as TCP)
71line by line, block by block, or until the connection is closed.
72All I/O reads are buffered and the performance differences between
73different receive patterns are negligible.
74</p>
75
76<p>
77Another advantage is the flexible timeout control
78mechanism. As in C, all I/O operations are blocking by default. For
79example, the <a href=tcp.html#send><tt>send</tt></a>,
80<a href=tcp.html#receive><tt>receive</tt></a> and
81<a href=tcp.html#accept><tt>accept</tt></a> methods
82of the TCP domain will block the caller application until
83the operation is completed (if ever!). However, with a call to the
84<a href=tcp.html#settimeout><tt>settimeout</tt></a>
85method, an application can specify upper limits on
86the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
87the time LuaSocket can internally be blocked by any OS call (the
88"<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
89call might perform several OS calls, so that the two timeout values are
90<em>not</em> equivalent.
91</p>
92
93<p>
94Finally, the host name resolution is transparent, meaning that most
95functions and methods accept both IP addresses and host names. In case a
96host name is given, the library queries the system's resolver and
97tries the main IP address returned. Note that direct use of IP addresses
98is more efficient, of course. The
99<a href=dns.html#toip><tt>toip</tt></a>
100and <a href=dns.html#tohostname><tt>tohostname</tt></a>
101functions from the DNS module are provided to convert between host names and IP addresses.
102</p>
103
104<p>
105Together, these changes make network programming in LuaSocket much simpler
106than it is in C, as the following sections will show.
107</p>
108
109<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111<h3 id=tcp>TCP</h3>
112
113<p>
114TCP (Transfer Control Protocol) is reliable stream protocol. In other
115words, applications communicating through TCP can send and receive data as
116an error free stream of bytes. Data is split in one end and
117reassembled transparently on the other end. There are no boundaries in
118the data transfers. The library allows users to read data from the
119sockets in several different granularities: patterns are available for
120lines, arbitrary sized blocks or "read up to connection closed", all with
121good performance.
122</p>
123
124<p>
125The library distinguishes three types of TCP sockets: <em>master</em>,
126<em>client</em> and <em>server</em> sockets.
127</p>
128
129<p>
130Master sockets are newly created TCP sockets returned by the function
131<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
132transformed into a server socket
133after it is associated with a <em>local</em> address by a call to the
134<a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the
135<a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket
136can be changed into a client socket with the method
137<a href=tcp.html#connect><tt>connect</tt></a>,
138which associates it with a <em>remote</em> address.
139</p>
140
141<p>
142On server sockets, applications can use the
143<a href=tcp.html#accept><tt>accept</tt></a> method
144to wait for a client connection. Once a connection is established, a
145client socket object is returned representing this connection. The
146other methods available for server socket objects are
147<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
148<a href=tcp.html#setoption><tt>setoption</tt></a>,
149<a href=tcp.html#settimeout><tt>settimeout</tt></a>, and
150<a href=tcp.html#close><tt>close</tt></a>.
151</p>
152
153<p>
154Client sockets are used to exchange data between two applications over
155the Internet. Applications can call the methods
156<a href=tcp.html#send><tt>send</tt></a> and
157<a href=tcp.html#receive><tt>receive</tt></a>
158to send and receive data. The other methods
159available for client socket objects are
160<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
161<a href=tcp.html#getpeername><tt>getpeername</tt></a>,
162<a href=tcp.html#setoption><tt>setoption</tt></a>,
163<a href=tcp.html#settimeout><tt>settimeout</tt></a>,
164<a href=tcp.html#shutdown><tt>shutdown</tt></a>, and
165<a href=tcp.html#close><tt>close</tt></a>.
166</p>
167
168<p>
169Example:
170</p>
171<blockquote>
172<p>
173A simple echo server, using LuaSocket. The program binds to an ephemeral
174port (one that is chosen by the operating system) on the local host and
175awaits client connections on that port. When a connection is established,
176the program reads a line from the remote end and sends it back, closing
177the connection immediately. You can test it using the telnet
178program.
179</p>
180
181<pre class=example>
182-- load namespace
183local socket = require("socket")
184-- create a TCP socket and bind it to the local host, at any port
185local server = assert(socket.bind("*", 0))
186-- find out which port the OS chose for us
187local ip, port = server:getsockname()
188-- print a message informing what's up
189print("Please telnet to localhost on port " .. port)
190print("After connecting, you have 10s to enter a line to be echoed")
191-- loop forever waiting for clients
192while 1 do
193 -- wait for a connection from any client
194 local client = server:accept()
195 -- make sure we don't block waiting for this client's line
196 client:settimeout(10)
197 -- receive the line
198 local line, err = client:receive()
199 -- if there was no error, send it back to the client
200 if not err then client:send(line .. "\n") end
201 -- done with client, close the object
202 client:close()
203end
204</pre>
205</blockquote>
206
207<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
208
209<h3 id=udp>UDP</h3>
210
211<p>
212UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
213other words, applications communicating through UDP send and receive
214data as independent blocks, which are not guaranteed to reach the other
215end. Even when they do reach the other end, they are not guaranteed to be
216error free. Data transfers are atomic, one datagram at a time. Reading
217only part of a datagram discards the rest, so that the following read
218operation will act on the next datagram. The advantages are in
219simplicity (no connection setup) and performance (no error checking or
220error correction).
221</p>
222
223<p>
224Note that although no guarantees are made, these days
225networks are so good that, under normal circumstances, few errors
226happen in practice.
227</p>
228
229<p>
230An UDP socket object is created by the
231<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
232sockets do not need to be connected before use. The method
233<a href=udp.html#sendto><tt>sendto</tt></a>
234can be used immediately after creation to
235send a datagram to IP address and port. Host names are not allowed
236because performing name resolution for each packet would be forbiddingly
237slow. Methods
238<a href=udp.html#receive><tt>receive</tt></a> and
239<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
240can be used to retrieve datagrams, the latter returning the IP and port of
241the sender as extra return values (thus being slightly less
242efficient).
243</p>
244
245<p>
246When communication is performed repeatedly with a single peer, an
247application should call the
248<a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
249permanent partner. Methods
250<a href=udp.html#sendto><tt>sendto</tt></a> and
251<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
252can no longer be used, but the method
253<a href=udp.html#send><tt>send</tt></a> can be used to send data
254directly to the peer, and the method
255<a href=udp.html#receive><tt>receive</tt></a>
256will only return datagrams originating
257from that peer. There is about 30% performance gain due to this practice.
258</p>
259
260<p>
261To associate an UDP socket with a local address, an application calls the
262<a href=udp.html#setsockname><tt>setsockname</tt></a>
263method <em>before</em> sending any datagrams. Otherwise, the socket is
264automatically bound to an ephemeral address before the first data
265transmission and once bound the local address cannot be changed.
266The other methods available for UDP sockets are
267<a href=udp.html#getpeername><tt>getpeername</tt></a>,
268<a href=udp.html#getsockname><tt>getsockname</tt></a>,
269<a href=udp.html#settimeout><tt>settimeout</tt></a>,
270<a href=udp.html#setoption><tt>setoption</tt></a> and
271<a href=udp.html#close><tt>close</tt></a>.
272</p>
273
274<p>
275Example:
276</p>
277<blockquote>
278<p>
279A simple daytime client, using LuaSocket. The program connects to a remote
280server and tries to retrieve the daytime, printing the answer it got or an
281error message.
282</p>
283
284<pre class=example>
285-- change here to the host an port you want to contact
286local host, port = "localhost", 13
287-- load namespace
288local socket = require("socket")
289-- convert host name to ip address
290local ip = assert(socket.dns.toip(host))
291-- create a new UDP object
292local udp = assert(socket.udp())
293-- contact daytime host
294assert(udp:sendto("anything", ip, port))
295-- retrieve the answer and print results
296io.write(assert(udp:receive()))
297</pre>
298</blockquote>
299
300<!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
301
302<h3 id=more>Support modules</h3>
303
304<p> Although not covered in the introduction, LuaSocket offers
305much more than TCP and UDP functionality. As the library
306evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>,
307and <a href=smtp.html>SMTP</a> were built on top of these. These modules
308and many others are covered by the <a href=reference.html>reference manual</a>.
309</p>
310
311<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
312
313<div class=footer>
314<hr>
315<center>
316<p class=bar>
317<a href="index.html">home</a> &middot;
318<a href="index.html#down">download</a> &middot;
319<a href="installation.html">installation</a> &middot;
320<a href="introduction.html">introduction</a> &middot;
321<a href="reference.html">reference</a>
322</p>
323<p>
324<small>
325Last modified by Diego Nehab on <br>
326Thu Apr 20 00:25:36 EDT 2006
327</small>
328</p>
329</center>
330</div>
331
332</body>
333</html>
diff --git a/doc/ltn12.html b/doc/ltn12.html
deleted file mode 100644
index 54e66fb..0000000
--- a/doc/ltn12.html
+++ /dev/null
@@ -1,430 +0,0 @@
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="LuaSocket: LTN12 support">
7<meta name="keywords" content="Lua, LuaSocket, Filters, Source, Sink,
8Pump, Support, Library">
9<title>LuaSocket: LTN12 module</title>
10<link rel="stylesheet" href="reference.css" type="text/css">
11</head>
12
13<body>
14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17<div class=header>
18<hr>
19<center>
20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language
25</td></tr>
26</table>
27<p class=bar>
28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a>
33</p>
34</center>
35<hr>
36</div>
37
38<!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2 id=ltn12>LTN12</h2>
41
42<p> The <tt>ltn12</tt> namespace implements the ideas described in
43<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
44LTN012, Filters sources and sinks</a>. This manual simply describes the
45functions. Please refer to the LTN for a deeper explanation of the
46functionality provided by this module.
47</p>
48
49<p>
50To obtain the <tt>ltn12</tt> namespace, run:
51</p>
52
53<pre class=example>
54-- loads the LTN21 module
55local ltn12 = require("ltn12")
56</pre>
57
58<!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
59
60<h3 id="filter">Filters</h3>
61
62<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
63
64<p class=name id="filter.chain">
65ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub>
66[, ... filter<sub>N</sub>]<b>)</b>
67</p>
68
69<p class=description>
70Returns a filter that passes all data it receives through each of a
71series of given filters.
72</p>
73
74<p class=parameters>
75<tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple
76filters.
77</p>
78
79<p class=return>
80The function returns the chained filter.
81</p>
82
83<p class=note>
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,
86unaltered.
87</p>
88
89<pre class=example>
90-- load required modules
91local ltn12 = require("ltn12")
92local mime = require("mime")
93
94-- create a silly identity filter
95id = ltn12.filter.chain(
96 mime.encode("quoted-printable"),
97 mime.encode("base64"),
98 mime.decode("base64"),
99 mime.decode("quoted-printable")
100)
101</pre>
102
103<!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
104
105<p class=name id="filter.cycle">
106ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b>
107</p>
108
109<p class=description>
110Returns a high-level filter that cycles though a low-level filter by
111passing it each chunk and updating a context between calls.
112</p>
113
114<p class=parameters>
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
117argument the low-level filter might take.
118</p>
119
120<p class=return>
121The function returns the high-level filter.
122</p>
123
124<pre class=example>
125-- load the ltn12 module
126local ltn12 = require("ltn12")
127
128-- the base64 mime filter factory
129encodet['base64'] = function()
130 return ltn12.filter.cycle(b64, "")
131end
132</pre>
133
134<!-- pumps ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
135
136<h3 id="pump">Pumps</h3>
137
138<!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id="pump.all">
141ltn12.pump.<b>all(</b>source, sink<b>)</b>
142</p>
143
144<p class=description>
145Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>.
146</p>
147
148<p class=return>
149If successful, the function returns a value that evaluates to
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.
152</p>
153
154<!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
155
156<p class=name id="pump.step">
157ltn12.pump.<b>step(</b>source, sink<b>)</b>
158</p>
159
160<p class=description>
161Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>.
162</p>
163
164<p class=return>
165If successful, the function returns a value that evaluates to
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.
168</p>
169
170<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
171
172<h3 id="sink">Sinks</h3>
173
174<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
175
176<p class=name id="sink.chain">
177ltn12.sink.<b>chain(</b>filter, sink<b>)</b>
178</p>
179
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>.
182</p>
183
184<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
185
186<p class=name id="sink.error">
187ltn12.sink.<b>error(</b>message<b>)</b>
188</p>
189
190<p class=description>
191Creates and returns a sink that aborts transmission with the error
192<tt>message</tt>.
193</p>
194
195<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
196
197<p class=name id="sink.file">
198ltn12.sink.<b>file(</b>handle, message<b>)</b>
199</p>
200
201<p class=description>
202Creates a sink that sends data to a file.
203</p>
204
205<p class=parameters>
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.
208</p>
209
210<p class=return>
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
213the error <tt>message</tt>
214</p>
215
216<p class=note>
217In the following example, notice how the prototype is designed to
218fit nicely with the <tt>io.open</tt> function.
219</p>
220
221<pre class=example>
222-- load the ltn12 module
223local ltn12 = require("ltn12")
224
225-- copy a file
226ltn12.pump.all(
227 ltn12.source.file(io.open("original.png", "rb")),
228 ltn12.sink.file(io.open("copy.png", "wb"))
229)
230</pre>
231
232<!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
233
234<p class=name id="sink.null">
235ltn12.sink.<b>null()</b>
236</p>
237
238<p class=description>
239Returns a sink that ignores all data it receives.
240</p>
241
242<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
243
244<p class=name id="sink.simplify">
245ltn12.sink.<b>simplify(</b>sink<b>)</b>
246</p>
247
248<p class=description>
249Creates and returns a simple sink given a fancy <tt>sink</tt>.
250</p>
251
252<!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254<p class=name id="sink.table">
255ltn12.sink.<b>table(</b>[table]<b>)</b>
256</p>
257
258<p class=description>
259Creates a sink that stores all chunks in a table. The chunks can later be
260efficiently concatenated into a single string.
261</p>
262
263<p class=parameters>
264<tt>Table</tt> is used to hold the chunks. If
265<tt><b>nil</b></tt>, the function creates its own table.
266</p>
267
268<p class=return>
269The function returns the sink and the table used to store the chunks.
270</p>
271
272<pre class=example>
273-- load needed modules
274local http = require("socket.http")
275local ltn12 = require("ltn12")
276
277-- a simplified http.get function
278function http.get(u)
279 local t = {}
280 local respt = request{
281 url = u,
282 sink = ltn12.sink.table(t)
283 }
284 return table.concat(t), respt.headers, respt.code
285end
286</pre>
287
288<!-- sinks ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
289
290<h3 id="source">Sources</h3>
291
292<!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
293
294<p class=name id="source.cat">
295ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ...,
296source<sub>N</sub>]<b>)</b>
297</p>
298
299<p class=description>
300Creates a new source that produces the concatenation of the data produced
301by a number of sources.
302</p>
303
304<p class=parameters>
305<tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original
306sources.
307</p>
308
309<p class=return>
310The function returns the new source.
311</p>
312
313<!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
314
315<p class=name id="source.chain">
316ltn12.source.<b>chain(</b>source, filter<b>)</b>
317</p>
318
319<p class=description>
320Creates a new <tt>source</tt> that passes data through a <tt>filter</tt>
321before returning it.
322</p>
323
324<p class=return>
325The function returns the new source.
326</p>
327
328<!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
329
330<p class=name id="source.empty">
331ltn12.source.<b>empty()</b>
332</p>
333
334<p class=description>
335Creates and returns an empty source.
336</p>
337
338<!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339
340<p class=name id="source.error">
341ltn12.source.<b>error(</b>message<b>)</b>
342</p>
343
344<p class=description>
345Creates and returns a source that aborts transmission with the error
346<tt>message</tt>.
347</p>
348
349<!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
350
351<p class=name id="source.file">
352ltn12.source.<b>file(</b>handle, message<b>)</b>
353</p>
354
355<p class=description>
356Creates a source that produces the contents of a file.
357</p>
358
359<p class=parameters>
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.
362</p>
363
364<p class=return>
365The function returns a source that reads chunks of data from
366given <tt>handle</tt> and returns it to the user,
367closing the file when done, or a source that aborts the transmission with
368the error <tt>message</tt>
369</p>
370
371<p class=note>
372In the following example, notice how the prototype is designed to
373fit nicely with the <tt>io.open</tt> function.
374</p>
375
376<pre class=example>
377-- load the ltn12 module
378local ltn12 = require("ltn12")
379
380-- copy a file
381ltn12.pump.all(
382 ltn12.source.file(io.open("original.png", "rb")),
383 ltn12.sink.file(io.open("copy.png", "wb"))
384)
385</pre>
386
387<!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
388
389<p class=name id="source.simplify">
390ltn12.source.<b>simplify(</b>source<b>)</b>
391</p>
392
393<p class=description>
394Creates and returns a simple source given a fancy <tt>source</tt>.
395</p>
396
397<!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398
399<p class=name id="source.string">
400ltn12.source.<b>string(</b>string<b>)</b>
401</p>
402
403<p class=description>
404Creates and returns a source that produces the contents of a
405<tt>string</tt>, chunk by chunk.
406</p>
407
408<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
409
410<div class=footer>
411<hr>
412<center>
413<p class=bar>
414<a href="index.html">home</a> &middot;
415<a href="index.html#down">download</a> &middot;
416<a href="installation.html">installation</a> &middot;
417<a href="introduction.html">introduction</a> &middot;
418<a href="reference.html">reference</a>
419</p>
420<p>
421<small>
422Last modified by Diego Nehab on <br>
423Thu Apr 20 00:25:41 EDT 2006
424</small>
425</p>
426</center>
427</div>
428
429</body>
430</html>
diff --git a/doc/lua05.ppt b/doc/lua05.ppt
deleted file mode 100644
index e2b7ab4..0000000
--- a/doc/lua05.ppt
+++ /dev/null
Binary files differ
diff --git a/doc/luasocket.png b/doc/luasocket.png
deleted file mode 100644
index d24a954..0000000
--- a/doc/luasocket.png
+++ /dev/null
Binary files differ
diff --git a/doc/mime.html b/doc/mime.html
deleted file mode 100644
index ae136fd..0000000
--- a/doc/mime.html
+++ /dev/null
@@ -1,476 +0,0 @@
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="LuaSocket: MIME support">
7<meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support">
8<title>LuaSocket: MIME module</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<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id=mime>MIME</h2>
40
41<p>
42The <tt>mime</tt> namespace offers filters that apply and remove common
43content transfer encodings, such as Base64 and Quoted-Printable.
44It also provides functions to break text into lines and change
45the end-of-line convention.
46MIME is described mainly in
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>,
49<a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>,
50<a href="http://www.ietf.org/rfc/rfc2047.txt">2048</a>, and
51<a href="http://www.ietf.org/rfc/rfc2048.txt">2049</a>.
52</p>
53
54<p>
55All functionality provided by the MIME module
56follows the ideas presented in
57<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">
58LTN012, Filters sources and sinks</a>.
59</p>
60
61<p>
62To obtain the <tt>mime</tt> namespace, run:
63</p>
64
65<pre class=example>
66-- loads the MIME module and everything it requires
67local mime = require("mime")
68</pre>
69
70
71<!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
72
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
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
104<!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
105
106<p class=name id="decode">
107mime.<b>decode(</b>"base64"<b>)</b><br>
108mime.<b>decode(</b>"quoted-printable"<b>)</b>
109</p>
110
111<p class=description>
112Returns a filter that decodes data from a given transfer content
113encoding.
114</p>
115
116<!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
117
118<p class=name id="encode">
119mime.<b>encode(</b>"base64"<b>)</b><br>
120mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b>
121</p>
122
123<p class=description>
124Returns a filter that encodes data according to a given transfer content
125encoding.
126</p>
127
128<p class=parameters>
129In 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
131"<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>".
132</p>
133
134<p class=note>
135Although both transfer content encodings specify a limit for the line
136length, the encoding filters do <em>not</em> break text into lines (for
137added flexibility).
138Below is a filter that converts binary data to the Base64 transfer content
139encoding and breaks it into lines of the correct size.
140</p>
141
142<pre class=example>
143base64 = ltn12.filter.chain(
144 mime.encode("base64"),
145 mime.wrap("base64")
146)
147</pre>
148
149<p class=note>
150Note: Text data <em>has</em> to be converted to canonic form
151<em>before</em> being encoded.
152</p>
153
154<pre class=example>
155base64 = ltn12.filter.chain(
156 mime.normalize(),
157 mime.encode("base64"),
158 mime.wrap("base64")
159)
160</pre>
161
162<!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
163
164<p class=name id="stuff">
165mime.<b>stuff()</b><br>
166</p>
167
168<p class=description>
169Creates and returns a filter that performs stuffing of SMTP messages.
170</p>
171
172<p class=note>
173Note: 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
175source, or apply it to your message body.
176</p>
177
178<!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
179
180<p class=name id="wrap">
181mime.<b>wrap(</b>"text" [, length]<b>)</b><br>
182mime.<b>wrap(</b>"base64"<b>)</b><br>
183mime.<b>wrap(</b>"quoted-printable"<b>)</b>
184</p>
185
186<p class=description>
187Returns a filter that breaks data into lines.
188</p>
189
190<p class=parameters>
191The "<tt>text</tt>" line-wrap filter simply breaks text into lines by
192inserting CRLF end-of-line markers at appropriate positions.
193<tt>Length</tt> defaults 76.
194The "<tt>base64</tt>" line-wrap filter works just like the default
195"<tt>text</tt>" line-wrap filter with default length.
196The 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
198line length is fixed at 76.
199</p>
200
201<p class=note>
202For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following:
203</p>
204
205<pre class=example>
206qp = ltn12.filter.chain(
207 mime.normalize(),
208 mime.encode("quoted-printable"),
209 mime.wrap("quoted-printable")
210)
211</pre>
212
213<p class=note>
214Note: To break into lines with a different end-of-line convention, apply
215a normalization filter after the line break filter.
216</p>
217
218<!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
219
220<h3 id=low>Low-level filters</h3>
221
222<!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
223
224<p class=name id="b64">
225A, B = mime.<b>b64(</b>C [, D]<b>)</b>
226</p>
227
228<p class=description>
229Low-level filter to perform Base64 encoding.
230</p>
231
232<p class=description>
233<tt>A</tt> is the encoded version of the largest prefix of
234<tt>C..D</tt>
235that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
236<tt>C..D</tt>, <em>before</em> encoding.
237If <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>.
239</p>
240
241<p class=note>
242Note: The simplest use of this function is to encode a string into it's
243Base64 transfer content encoding. Notice the extra parenthesis around the
244call to <tt>mime.b64</tt>, to discard the second return value.
245</p>
246
247<pre class=example>
248print((mime.b64("diego:password")))
249--&gt; ZGllZ286cGFzc3dvcmQ=
250</pre>
251
252<!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253<p class=name id="dot">
254A, n = mime.<b>dot(</b>m [, B]<b>)</b>
255</p>
256
257<p class=description>
258Low-level filter to perform SMTP stuffing and enable transmission of
259messages containing the sequence "CRLF.CRLF".
260</p>
261
262<p class=parameters>
263<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>.
265'<tt>m</tt>' should tell the same, but for the previous chunk.
266</p>
267
268<p class=note>Note: The message body is defined to begin with
269an implicit CRLF. Therefore, to stuff a message correctly, the
270first <tt>m</tt> should have the value 2.
271</p>
272
273<pre class=example>
274print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
275--&gt; ..\nStuffing the message.\n..\n..
276</pre>
277
278<p class=note>
279Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function
280uses this filter automatically. You don't need to
281apply it again.
282</p>
283
284<!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
285
286<p class=name id="eol">
287A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b>
288</p>
289
290<p class=description>
291Low-level filter to perform end-of-line marker translation.
292For 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
294context the function receives besides the chunk. An updated version of
295the context is returned after each new chunk.
296</p>
297
298<p class=parameters>
299<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
301candidate for line break, or 0 otherwise.
302<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.
304</p>
305
306<pre class=example>
307-- translates the end-of-line marker to UNIX
308unix = mime.eol(0, dos, "\n")
309</pre>
310
311<!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
312
313<p class=name id="qp">
314A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b>
315</p>
316
317<p class=description>
318Low-level filter to perform Quoted-Printable encoding.
319</p>
320
321<p class=parameters>
322<tt>A</tt> is the encoded version of the largest prefix of
323<tt>C..D</tt>
324that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of
325<tt>C..D</tt>, <em>before</em> encoding.
326If <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>.
328Throughout encoding, occurrences of CRLF are replaced by the
329<tt>marker</tt>, which itself defaults to CRLF.
330</p>
331
332<p class=note>
333Note: The simplest use of this function is to encode a string into it's
334Quoted-Printable transfer content encoding.
335Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value.
336</p>
337
338<pre class=example>
339print((mime.qp("maçã")))
340--&gt; ma=E7=E3=
341</pre>
342
343<!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
344
345<p class=name id="qpwrp">
346A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b>
347</p>
348
349<p class=description>
350Low-level filter to break Quoted-Printable text into lines.
351</p>
352
353<p class=parameters>
354<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>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
358left in the last line of <tt>A</tt>.
359</p>
360
361<p class=note>
362Note: Besides breaking text into lines, this function makes sure the line
363breaks 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.
365</p>
366
367<!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
368
369<p class=name id="unb64">
370A, B = mime.<b>unb64(</b>C [, D]<b>)</b>
371</p>
372
373<p class=description>
374Low-level filter to perform Base64 decoding.
375</p>
376
377<p class=parameters>
378<tt>A</tt> is the decoded version of the largest prefix of
379<tt>C..D</tt>
380that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
381<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
383and <tt>B</tt> returns whatever couldn't be decoded.
384</p>
385
386<p class=note>
387Note: The simplest use of this function is to decode a string from it's
388Base64 transfer content encoding.
389Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
390</p>
391
392<pre class=example>
393print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
394--&gt; diego:password
395</pre>
396
397<!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
398
399<p class=name id="unqp">
400A, B = mime.<b>unqp(</b>C [, D]<b>)</b>
401</p>
402
403<p class=description>
404Low-level filter to remove the Quoted-Printable transfer content encoding
405from data.
406</p>
407
408<p class=parameters>
409<tt>A</tt> is the decoded version of the largest prefix of
410<tt>C..D</tt>
411that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of
412<tt>C..D</tt>, <em>before</em> decoding.
413If <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>.
415</p>
416
417<p class=note>
418Note: The simplest use of this function is to decode a string from it's
419Quoted-Printable transfer content encoding.
420Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value.
421</p>
422
423<pre class=example>
424print((mime.qp("ma=E7=E3=")))
425--&gt; maçã
426</pre>
427
428<!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
429
430<p class=name id="wrp">
431A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b>
432</p>
433
434<p class=description>
435Low-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.
437</p>
438
439<p class=parameters>
440<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>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
444left in the last line of <tt>A</tt>.
445</p>
446
447<p class=note>
448Note: This function only breaks lines that are bigger than
449<tt>length</tt> bytes. The resulting line length does not include the CRLF
450marker.
451</p>
452
453
454<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
455
456<div class=footer>
457<hr>
458<center>
459<p class=bar>
460<a href="index.html">home</a> &middot;
461<a href="index.html#down">download</a> &middot;
462<a href="installation.html">installation</a> &middot;
463<a href="introduction.html">introduction</a> &middot;
464<a href="reference.html">reference</a>
465</p>
466<p>
467<small>
468Last modified by Diego Nehab on <br>
469Thu Apr 20 00:25:44 EDT 2006
470</small>
471</p>
472</center>
473</div>
474
475</body>
476</html>
diff --git a/doc/reference.css b/doc/reference.css
deleted file mode 100644
index 04e38cf..0000000
--- a/doc/reference.css
+++ /dev/null
@@ -1,55 +0,0 @@
1body {
2 margin-left: 1em;
3 margin-right: 1em;
4 font-family: "Verdana", sans-serif;
5 background: #ffffff;
6}
7
8tt {
9 font-family: "Andale Mono", monospace;
10}
11
12h1, h2, h3, h4 { margin-left: 0em; }
13
14
15h3 { padding-top: 1em; }
16
17p { margin-left: 1em; }
18
19p.name {
20 font-family: "Andale Mono", monospace;
21 padding-top: 1em;
22 margin-left: 0em;
23}
24
25a[href] { color: #00007f; }
26
27blockquote { margin-left: 3em; }
28
29pre.example {
30 background: #ccc;
31 padding: 1em;
32 margin-left: 1em;
33 font-family: "Andale Mono", monospace;
34 font-size: small;
35}
36
37hr {
38 margin-left: 0em;
39 background: #00007f;
40 border: 0px;
41 height: 1px;
42}
43
44ul { list-style-type: disc; }
45
46table.index { border: 1px #00007f; }
47table.index td { text-align: left; vertical-align: top; }
48table.index ul { padding-top: 0em; margin-top: 0em; }
49
50h1:first-letter,
51h2:first-letter,
52h2:first-letter,
53h3:first-letter { color: #00007f; }
54
55div.header, div.footer { margin-left: 0em; }
diff --git a/doc/reference.html b/doc/reference.html
deleted file mode 100644
index 6067ba6..0000000
--- a/doc/reference.html
+++ /dev/null
@@ -1,256 +0,0 @@
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="LuaSocket: Index to reference manual">
7<meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library,
8Support, Manual">
9<title>LuaSocket: Index to reference manual</title>
10<link rel="stylesheet" href="reference.css" type="text/css">
11</head>
12
13<body>
14
15<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17<div class=header>
18<hr>
19<center>
20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language
25</td></tr>
26</table>
27<p class=bar>
28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a>
33</p>
34</center>
35<hr>
36</div>
37
38<!-- reference +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2>Reference</h2>
41
42<blockquote>
43<a href="dns.html">DNS (in socket)</a>
44<blockquote>
45<a href="dns.html#getaddrinfo">getaddrinfo</a>,
46<a href="dns.html#gethostname">gethostname</a>,
47<a href="dns.html#tohostname">tohostname</a>,
48<a href="dns.html#toip">toip</a>.
49</blockquote>
50</blockquote>
51
52<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
53
54<blockquote>
55<a href="ftp.html">FTP</a>
56<blockquote>
57<a href="ftp.html#get">get</a>,
58<a href="ftp.html#put">put</a>.
59</blockquote>
60</blockquote>
61
62<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
63
64<blockquote>
65<a href="http.html">HTTP</a>
66<blockquote>
67<a href="http.html#request">request</a>.
68</blockquote>
69</blockquote>
70
71<!-- ltn12 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
72
73<blockquote>
74<a href="ltn12.html">LTN12</a>
75<blockquote>
76<a href="ltn12.html#filter">filter</a>:
77<a href="ltn12.html#filter.chain">chain</a>,
78<a href="ltn12.html#filter.cycle">cycle</a>.
79</blockquote>
80<blockquote>
81<a href="ltn12.html#pump">pump</a>:
82<a href="ltn12.html#pump.all">all</a>,
83<a href="ltn12.html#pump.step">step</a>.
84</blockquote>
85<blockquote>
86<a href="ltn12.html#sink">sink</a>:
87<a href="ltn12.html#sink.chain">chain</a>,
88<a href="ltn12.html#sink.error">error</a>,
89<a href="ltn12.html#sink.file">file</a>,
90<a href="ltn12.html#sink.null">null</a>,
91<a href="ltn12.html#sink.simplify">simplify</a>,
92<a href="ltn12.html#sink.table">table</a>.
93</blockquote>
94<blockquote>
95<a href="ltn12.html#source">source</a>:
96<a href="ltn12.html#source.cat">cat</a>,
97<a href="ltn12.html#source.chain">chain</a>,
98<a href="ltn12.html#source.empty">empty</a>,
99<a href="ltn12.html#source.error">error</a>,
100<a href="ltn12.html#source.file">file</a>,
101<a href="ltn12.html#source.simplify">simplify</a>,
102<a href="ltn12.html#source.string">string</a>.
103</blockquote>
104</blockquote>
105
106<!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
107
108<blockquote>
109<a href="mime.html">MIME</a>
110<blockquote>
111<a href="mime.html#high">high-level</a>:
112<a href="mime.html#decode">decode</a>,
113<a href="mime.html#encode">encode</a>,
114<a href="mime.html#normalize">normalize</a>,
115<a href="mime.html#stuff">stuff</a>,
116<a href="mime.html#wrap">wrap</a>.
117</blockquote>
118<blockquote>
119<a href="mime.html#low">low-level</a>:
120<a href="mime.html#b64">b64</a>,
121<a href="mime.html#dot">dot</a>,
122<a href="mime.html#eol">eol</a>,
123<a href="mime.html#qp">qp</a>,
124<a href="mime.html#qpwrp">qpwrp</a>,
125<a href="mime.html#unb64">unb64</a>,
126<a href="mime.html#unqp">unqp</a>,
127<a href="mime.html#wrp">wrp</a>.
128</blockquote>
129</blockquote>
130
131<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
132
133<blockquote>
134<a href="smtp.html">SMTP</a>
135<blockquote>
136<a href="smtp.html#message">message</a>,
137<a href="smtp.html#send">send</a>.
138</blockquote>
139</blockquote>
140
141<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
142
143<blockquote>
144<a href="socket.html">Socket</a>
145<blockquote>
146<a href="socket.html#bind">bind</a>,
147<a href="socket.html#connect">connect</a>,
148<a href="socket.html#connect">connect4</a>,
149<a href="socket.html#connect">connect6</a>,
150<a href="socket.html#debug">_DEBUG</a>,
151<a href="dns.html#dns">dns</a>,
152<a href="socket.html#gettime">gettime</a>,
153<a href="socket.html#headers.canonic">headers.canonic</a>,
154<a href="socket.html#newtry">newtry</a>,
155<a href="socket.html#protect">protect</a>,
156<a href="socket.html#select">select</a>,
157<a href="socket.html#sink">sink</a>,
158<a href="socket.html#skip">skip</a>,
159<a href="socket.html#sleep">sleep</a>,
160<a href="socket.html#setsize">_SETSIZE</a>,
161<a href="socket.html#source">source</a>,
162<a href="tcp.html#socket.tcp">tcp</a>,
163<a href="tcp.html#socket.tcp4">tcp4</a>,
164<a href="tcp.html#socket.tcp6">tcp6</a>,
165<a href="socket.html#try">try</a>,
166<a href="udp.html#socket.udp">udp</a>,
167<a href="udp.html#socket.udp4">udp4</a>,
168<a href="udp.html#socket.udp6">udp6</a>,
169<a href="socket.html#version">_VERSION</a>.
170</blockquote>
171</blockquote>
172
173<!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
174
175<blockquote>
176<a href="tcp.html">TCP (in socket)</a>
177<blockquote>
178<a href="tcp.html#accept">accept</a>,
179<a href="tcp.html#bind">bind</a>,
180<a href="tcp.html#close">close</a>,
181<a href="tcp.html#connect">connect</a>,
182<a href="tcp.html#dirty">dirty</a>,
183<a href="tcp.html#getfd">getfd</a>,
184<a href="tcp.html#getoption">getoption</a>,
185<a href="tcp.html#getpeername">getpeername</a>,
186<a href="tcp.html#getsockname">getsockname</a>,
187<a href="tcp.html#getstats">getstats</a>,
188<a href="tcp.html#listen">listen</a>,
189<a href="tcp.html#receive">receive</a>,
190<a href="tcp.html#send">send</a>,
191<a href="tcp.html#setfd">setfd</a>,
192<a href="tcp.html#setoption">setoption</a>,
193<a href="tcp.html#setstats">setstats</a>,
194<a href="tcp.html#settimeout">settimeout</a>,
195<a href="tcp.html#shutdown">shutdown</a>.
196</blockquote>
197</blockquote>
198
199<!-- udp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
200
201<blockquote>
202<a href="udp.html">UDP (in socket)</a>
203<blockquote>
204<a href="udp.html#close">close</a>,
205<a href="udp.html#getoption">getoption</a>,
206<a href="udp.html#getpeername">getpeername</a>,
207<a href="udp.html#getsockname">getsockname</a>,
208<a href="udp.html#receive">receive</a>,
209<a href="udp.html#receivefrom">receivefrom</a>,
210<a href="udp.html#send">send</a>,
211<a href="udp.html#sendto">sendto</a>,
212<a href="udp.html#setpeername">setpeername</a>,
213<a href="udp.html#setsockname">setsockname</a>,
214<a href="udp.html#setoption">setoption</a>,
215<a href="udp.html#settimeout">settimeout</a>.
216</blockquote>
217</blockquote>
218
219<!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
220
221<blockquote>
222<a href="url.html">URL</a>
223<blockquote>
224<a href="url.html#absolute">absolute</a>,
225<a href="url.html#build">build</a>,
226<a href="url.html#build_path">build_path</a>,
227<a href="url.html#escape">escape</a>,
228<a href="url.html#parse">parse</a>,
229<a href="url.html#parse_path">parse_path</a>,
230<a href="url.html#unescape">unescape</a>.
231</blockquote>
232</blockquote>
233
234<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
235
236<div class=footer>
237<hr>
238<center>
239<p class=bar>
240<a href="index.html">home</a> &middot;
241<a href="index.html#down">download</a> &middot;
242<a href="installation.html">installation</a> &middot;
243<a href="introduction.html">introduction</a> &middot;
244<a href="reference.html">reference</a>
245</p>
246<p>
247<small>
248Last modified by Diego Nehab on <br>
249Thu Apr 20 00:25:47 EDT 2006
250</small>
251</p>
252</center>
253</div>
254
255</body>
256</html>
diff --git a/doc/smtp.html b/doc/smtp.html
deleted file mode 100644
index bbbff80..0000000
--- a/doc/smtp.html
+++ /dev/null
@@ -1,417 +0,0 @@
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="LuaSocket: SMTP support">
7<meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart,
8Library, Support">
9<title>LuaSocket: SMTP support</title>
10<link rel="stylesheet" href="reference.css" type="text/css">
11</head>
12
13<body>
14
15<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
16
17<div class=header>
18<hr>
19<center>
20<table summary="LuaSocket logo">
21<tr><td align=center><a href="http://www.lua.org">
22<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
23</a></td></tr>
24<tr><td align=center valign=top>Network support for the Lua language
25</td></tr>
26</table>
27<p class=bar>
28<a href="index.html">home</a> &middot;
29<a href="index.html#download">download</a> &middot;
30<a href="installation.html">installation</a> &middot;
31<a href="introduction.html">introduction</a> &middot;
32<a href="reference.html">reference</a>
33</p>
34</center>
35<hr>
36</div>
37
38<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2 id=smtp>SMTP</h2>
41
42<p> The <tt>smtp</tt> namespace provides functionality to send e-mail
43messages. The high-level API consists of two functions: one to
44define an e-mail message, and another to actually send the message.
45Although almost all users will find that these functions provide more than
46enough functionality, the underlying implementation allows for even more
47control (if you bother to read the code).
48</p>
49
50<p>The implementation conforms to the Simple Mail Transfer Protocol,
51<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>.
52Another RFC of interest is <a
53href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>,
54which governs the Internet Message Format.
55Multipart messages (those that contain attachments) are part
56of the MIME standard, but described mainly
57in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>
58
59<p> In the description below, good understanding of <a
60href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters
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
63creation. </p>
64
65<p>
66To obtain the <tt>smtp</tt> namespace, run:
67</p>
68
69<pre class=example>
70-- loads the SMTP module and everything it requires
71local smtp = require("socket.smtp")
72</pre>
73
74<p>
75MIME headers are represented as a Lua table in the form:
76</p>
77
78<blockquote>
79<table summary="MIME headers in Lua table">
80<tr><td><tt>
81headers = {<br>
82&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
83&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
84&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,<br>
85&nbsp;&nbsp;...<br>
86&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
87}
88</tt></td></tr>
89</table>
90</blockquote>
91
92<p>
93Field names are case insensitive (as specified by the standard) and all
94functions work with lowercase field names (but see
95<a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>).
96Field values are left unmodified.
97</p>
98
99<p class=note>
100Note: MIME headers are independent of order. Therefore, there is no problem
101in representing them in a Lua table.
102</p>
103
104<p>
105The following constants can be set to control the default behavior of
106the SMTP module:
107</p>
108
109<ul>
110<li> <tt>DOMAIN</tt>: domain used to greet the server;
111<li> <tt>PORT</tt>: default port used for the connection;
112<li> <tt>SERVER</tt>: default server used for the connection;
113<li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;
114<li> <tt>ZONE</tt>: default time zone.
115</ul>
116
117<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
118
119<p class=name id=send>
120smtp.<b>send{</b><br>
121&nbsp;&nbsp;from = <i>string</i>,<br>
122&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
123&nbsp;&nbsp;source = <i>LTN12 source</i>,<br>
124&nbsp;&nbsp;[user = <i>string</i>,]<br>
125&nbsp;&nbsp;[password = <i>string</i>,]<br>
126&nbsp;&nbsp;[server = <i>string</i>,]<br>
127&nbsp;&nbsp;[port = <i>number</i>,]<br>
128&nbsp;&nbsp;[domain = <i>string</i>,]<br>
129&nbsp;&nbsp;[step = <i>LTN12 pump step</i>,]<br>
130&nbsp;&nbsp;[create = <i>function</i>]<br>
131<b>}</b>
132</p>
133
134<p class=description>
135Sends 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
137doesn't have a simple interface. However, see the
138<a href=#message><tt>message</tt></a> source factory for
139a very powerful way to define the message contents.
140</p>
141
142
143<p class=parameters>
144The 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
146address, or a string
147in case there is just one recipient.
148The contents of the message are given by a <em>simple</em>
149<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
150<tt>source</tt>. Several arguments are optional:
151</p>
152<ul>
153<li> <tt>user</tt>, <tt>password</tt>: User and password for
154authentication. The function will attempt LOGIN and PLAIN authentication
155methods if supported by the server (both are unsafe);
156<li> <tt>server</tt>: Server to connect to. Defaults to "localhost";
157<li> <tt>port</tt>: Port to connect to. Defaults to 25;
158<li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the
159local machine host name;
160<li> <tt>step</tt>:
161<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
162pump step function used to pass data from the
163source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;
164<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.
166</ul>
167
168<p class=return>
169If successful, the function returns 1. Otherwise, the function returns
170<b><tt>nil</tt></b> followed by an error message.
171</p>
172
173<p class=note>
174Note: SMTP servers can be very picky with the format of e-mail
175addresses. To be safe, use only addresses of the form
176"<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
178addresses can take whatever form you like. </p>
179
180<p class=note>
181Big 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>',
183and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
184'<tt>Bcc</tt>' header to your messages because it will probably do the
185exact opposite of what you expect.
186</p>
187
188<p class=note>
189Only 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
191message body along with the headers, and nothing more. The headers
192<em>are</em> part of the message and should be produced by the
193<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
194<tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em>
195part of the message and will not be sent to anyone.
196</p>
197
198<p class=note>
199<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
201fields" and "5. Security considerations", explaining the proper
202use of these headers. Here is a summary of what it says:
203</p>
204
205<ul>
206<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
207of the message;
208<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
210addresses of others who are to receive the message, though the
211content of the message may not be directed at them;
212<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.
214</ul>
215
216<p class=note>
217The 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
219to whom it is sent:
220</p>
221<ul>
222<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
224gets a copy of the message;
225<li> If there are multiple recipients, none of them will automatically
226know that someone else got that message. That is, the default behavior is
227similar to the <tt>Bcc</tt> field of popular e-mail clients;
228<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;
230<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;
232<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
233empty. Otherwise, everyone receiving the message will see it and that is
234exactly what you <em>don't</em> want to happen!
235</ul>
236
237<p class=note>
238I hope this clarifies the issue. Otherwise, please refer to
239<a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a>
240and
241<a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>.
242</p>
243
244<pre class=example>
245-- load the smtp support
246local smtp = require("socket.smtp")
247
248-- Connects to server "localhost" and sends a message to users
249-- "fulano@example.com", "beltrano@example.com",
250-- and "sicrano@example.com".
251-- Note that "fulano" is the primary recipient, "beltrano" receives a
252-- carbon copy and neither of them knows that "sicrano" received a blind
253-- carbon copy of the message.
254from = "&lt;luasocket@example.com&gt;"
255
256rcpt = {
257 "&lt;fulano@example.com&gt;",
258 "&lt;beltrano@example.com&gt;",
259 "&lt;sicrano@example.com&gt;"
260}
261
262mesgt = {
263 headers = {
264 to = "Fulano da Silva &lt;fulano@example.com&gt;",
265 cc = '"Beltrano F. Nunes" &lt;beltrano@example.com&gt;',
266 subject = "My first message"
267 },
268 body = "I hope this works. If it does, I can send you another 1000 copies."
269}
270
271r, e = smtp.send{
272 from = from,
273 rcpt = rcpt,
274 source = smtp.message(mesgt)
275}
276</pre>
277
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
396
397<div class=footer>
398<hr>
399<center>
400<p class=bar>
401<a href="index.html">home</a> &middot;
402<a href="index.html#down">download</a> &middot;
403<a href="installation.html">installation</a> &middot;
404<a href="introduction.html">introduction</a> &middot;
405<a href="reference.html">reference</a>
406</p>
407<p>
408<small>
409Last modified by Diego Nehab on <br>
410Thu Apr 20 00:25:51 EDT 2006
411</small>
412</p>
413</center>
414</div>
415
416</body>
417</html>
diff --git a/doc/socket.html b/doc/socket.html
deleted file mode 100644
index e6a9bf8..0000000
--- a/doc/socket.html
+++ /dev/null
@@ -1,456 +0,0 @@
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="LuaSocket: The core namespace">
7<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support">
8<title>LuaSocket: The socket namespace</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<!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id=socket>The socket namespace</h2>
40
41<p>
42The <tt>socket</tt> namespace contains the core functionality of LuaSocket.
43</p>
44
45<p>
46To obtain the <tt>socket</tt> namespace, run:
47</p>
48
49<pre class=example>
50-- loads the socket module
51local socket = require("socket")
52</pre>
53
54<!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
55
56<p class=name id=bind>
57socket.<b>bind(</b>address, port [, backlog]<b>)</b>
58</p>
59
60<p class=description>
61This 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
63accept client connections. Optionally,
64user can also specify the <tt>backlog</tt> argument to the
65<a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32).
66</p>
67
68<p class=note>
69Note: The server object returned will have the option "<tt>reuseaddr</tt>"
70set to <tt><b>true</b></tt>.
71</p>
72
73<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
74
75<p class=name id=connect>
76socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b>
77</p>
78
79<p class=description>
80This 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,
82the user can also specify the local address and port to bind
83(<tt>locaddr</tt> and <tt>locport</tt>), or restrict the socket family
84to "<tt>inet</tt>" or "<tt>inet6</tt>".
85Without specifying <tt>family</tt> to <tt>connect</tt>, whether a tcp or tcp6
86connection is created depends on your system configuration. Two variations
87of connect are defined as simple helper functions that restrict the
88<tt>family</tt>, <tt>socket.connect4</tt> and <tt>socket.connect6</tt>.
89</p>
90
91<!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
92
93<p class=name id=debug>
94socket.<b>_DEBUG</b>
95</p>
96
97<p class=description>
98This constant is set to <tt><b>true</b></tt> if the library was compiled
99with debug support.
100</p>
101
102<!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
103
104<p class=name id=gettime>
105socket.<b>gettime()</b>
106</p>
107
108<p class=description>
109Returns the UNIX time in seconds. You should subtract the values returned by this function
110to get meaningful values.
111</p>
112
113<pre class=example>
114t = socket.gettime()
115-- do stuff
116print(socket.gettime() - t .. " seconds elapsed")
117</pre>
118
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
143
144<p class=name id=newtry>
145socket.<b>newtry(</b>finalizer<b>)</b>
146</p>
147
148<p class=description>
149Creates and returns a <em>clean</em>
150<a href="#try"><tt>try</tt></a>
151function that allows for cleanup before the exception
152is raised.
153</p>
154
155<p class=parameters>
156<tt>Finalizer</tt> is a function that will be called before
157<tt>try</tt> throws the exception. It will be called
158in <em>protected</em> mode.
159</p>
160
161<p class=return>
162The function returns your customized <tt>try</tt> function.
163</p>
164
165<p class=note>
166Note: This idea saved a <em>lot</em> of work with the
167implementation of protocols in LuaSocket:
168</p>
169
170<pre class=example>
171foo = socket.protect(function()
172 -- connect somewhere
173 local c = socket.try(socket.connect("somewhere", 42))
174 -- create a try function that closes 'c' on error
175 local try = socket.newtry(function() c:close() end)
176 -- do everything reassured c will be closed
177 try(c:send("hello there?\r\n"))
178 local answer = try(c:receive())
179 ...
180 try(c:send("good bye\r\n"))
181 c:close()
182end)
183</pre>
184
185
186<!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
187
188<p class=name id=protect>
189socket.<b>protect(</b>func<b>)</b>
190</p>
191
192<p class=description>
193Converts a function that throws exceptions into a safe function. This
194function 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
196Lua errors.
197</p>
198
199<p class=parameters>
200<tt>Func</tt> is a function that calls
201<a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>)
202to 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>
209
210<p class=note>
211Note: Beware that if your function performs some illegal operation that
212raises an error, the protected function will catch the error and return it
213as a string. This is because the <a href=#try><tt>try</tt></a> function
214uses errors as the mechanism to throw exceptions.
215</p>
216
217<!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
218
219<p class=name id=select>
220socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b>
221</p>
222
223<p class=description>
224Waits for a number of sockets to change status.
225</p>
226
227<p class=parameters>
228<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
230see if it is OK to immediately write on them. <tt>Timeout</tt> is the
231maximum amount of time (in seconds) to wait for a change in status. A
232<tt><b>nil</b></tt>, negative or omitted <tt>timeout</tt> value allows the
233function to block indefinitely. <tt>Recvt</tt> and <tt>sendt</tt> can also
234be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with
235non-numeric indices) in the arrays will be silently ignored.
236</p>
237
238<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.
240The error message is "<tt>timeout</tt>" if a timeout condition was met and
241<tt><b>nil</b></tt> otherwise. The returned tables are
242doubly keyed both by integers and also by the sockets
243themselves, to simplify the test if a specific socket has
244changed status.
245</p>
246
247<p class=note>
248<b>Note: </b>: <tt>select</tt> can monitor a limited number
249of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This
250number may be as high as 1024 or as low as 64 by default,
251depending on the system. It is usually possible to change this
252at compile time. Invoking <tt>select</tt> with a larger
253number of sockets will raise an error.
254</p>
255
256<p class=note>
257<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
259writable even though the socket is <em>not</em> ready for sending.
260</p>
261
262<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
264<a href=tcp.html#accept><tt>accept</tt></a> will return immediately.
265Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a>
266method or <tt>accept</tt> might block forever.
267</p>
268
269<p class=note>
270<b>Yet another note</b>: If you close a socket and pass
271it to <tt>select</tt>, it will be ignored.
272</p>
273
274<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.
276</p>
277
278<!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
279
280<p class=name id=sink>
281socket.<b>sink(</b>mode, socket<b>)</b>
282</p>
283
284<p class=description>
285Creates an
286<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
287sink from a stream socket object.
288</p>
289
290<p class=parameters>
291<tt>Mode</tt> defines the behavior of the sink. The following
292options are available:
293</p>
294<ul>
295<li> <tt>"http-chunked"</tt>: sends data through socket after applying the
296<em>chunked transfer coding</em>, closing the socket when done;
297<li> <tt>"close-when-done"</tt>: sends all received data through the
298socket, closing the socket when done;
299<li> <tt>"keep-open"</tt>: sends all received data through the
300socket, leaving it open when done.
301</ul>
302<p>
303<tt>Socket</tt> is the stream socket object used to send the data.
304</p>
305
306<p class=return>
307The function returns a sink with the appropriate behavior.
308</p>
309
310<!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
311
312<p class=name id=skip>
313socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
314</p>
315
316<p class=description>
317Drops a number of arguments and returns the remaining.
318</p>
319
320<p class=parameters>
321<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.
323</p>
324
325<p class=return>
326The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
327</p>
328
329<p class=note>
330Note: This function is useful to avoid creation of dummy variables:
331</p>
332
333<pre class=example>
334-- get the status code and separator from SMTP server reply
335local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
336</pre>
337
338<!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339
340<p class=name id=sleep>
341socket.<b>sleep(</b>time<b>)</b>
342</p>
343
344<p class=description>
345Freezes the program execution during a given amount of time.
346</p>
347
348<p class=parameters>
349<tt>Time</tt> is the number of seconds to sleep for. If
350<tt>time</tt> is negative, the function returns immediately.
351</p>
352
353<!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
354
355<p class=name id=source>
356socket.<b>source(</b>mode, socket [, length]<b>)</b>
357</p>
358
359<p class=description>
360Creates an
361<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
362source from a stream socket object.
363</p>
364
365<p class=parameters>
366<tt>Mode</tt> defines the behavior of the source. The following
367options are available:
368</p>
369<ul>
370<li> <tt>"http-chunked"</tt>: receives data from socket and removes the
371<em>chunked transfer coding</em> before returning the data;
372<li> <tt>"by-length"</tt>: receives a fixed number of bytes from the
373socket. This mode requires the extra argument <tt>length</tt>;
374<li> <tt>"until-closed"</tt>: receives data from a socket until the other
375side closes the connection.
376</ul>
377<p>
378<tt>Socket</tt> is the stream socket object used to receive the data.
379</p>
380
381<p class=return>
382The function returns a source with the appropriate behavior.
383</p>
384
385<!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
386
387<p class=name id=setsize>
388socket.<b>_SETSIZE</b>
389</p>
390
391<p class=description>
392The maximum number of sockets that the <a
393href=#select><tt>select</tt></a> function can handle.
394</p>
395
396<!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
397
398<p class=name id=try>
399socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b>
400</p>
401
402<p class=description>
403Throws an exception in case of error. The exception can only be caught
404by the <a href=#protect><tt>protect</tt></a> function. It does not explode
405into an error message.
406</p>
407
408<p class=parameters>
409<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
411nested with <tt>try</tt>.
412</p>
413
414<p class=return>
415The 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>.
417</p>
418
419<pre class=example>
420-- connects or throws an exception with the appropriate error message
421c = socket.try(socket.connect("localhost", 80))
422</pre>
423
424<!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
425
426<p class=name id=version>
427socket.<b>_VERSION</b>
428</p>
429
430<p class=description>
431This constant has a string describing the current LuaSocket version.
432</p>
433
434<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
435
436<div class=footer>
437<hr>
438<center>
439<p class=bar>
440<a href="index.html">home</a> &middot;
441<a href="index.html#down">download</a> &middot;
442<a href="installation.html">installation</a> &middot;
443<a href="introduction.html">introduction</a> &middot;
444<a href="reference.html">reference</a>
445</p>
446<p>
447<small>
448Last modified by Diego Nehab on <br>
449Thu Apr 20 00:25:54 EDT 2006
450</small>
451</p>
452</center>
453</div>
454
455</body>
456</html>
diff --git a/doc/tcp.html b/doc/tcp.html
deleted file mode 100644
index fb627a1..0000000
--- a/doc/tcp.html
+++ /dev/null
@@ -1,697 +0,0 @@
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="LuaSocket: The TCP/IP support">
7<meta name="keywords" content="Lua, LuaSocket, Socket, TCP, Library, Network, Support">
8<title>LuaSocket: TCP/IP support</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<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id="tcp">TCP</h2>
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
120
121<p class=name id="accept">
122server:<b>accept()</b>
123</p>
124
125<p class=description>
126Waits for a remote connection on the server
127object and returns a client object representing that connection.
128</p>
129
130<p class=return>
131If a connection is successfully initiated, a client object is returned.
132If a timeout condition is met, the method returns <b><tt>nil</tt></b>
133followed by the error string '<tt>timeout</tt>'. Other errors are
134reported by <b><tt>nil</tt></b> followed by a message describing the error.
135</p>
136
137<p class=note>
138Note: calling <a href=socket.html#select><tt>socket.select</tt></a>
139with a server object in
140the <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
142href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
143might block until <em>another</em> client shows up.
144</p>
145
146<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
147
148<p class=name id="bind">
149master:<b>bind(</b>address, port<b>)</b>
150</p>
151
152<p class=description>
153Binds a master object to <tt>address</tt> and <tt>port</tt> on the
154local host.
155
156<p class=parameters>
157<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).
159If <tt>address</tt>
160is '<tt>*</tt>', the system binds to all local interfaces
161using the <tt>INADDR_ANY</tt> constant or
162<tt>IN6ADDR_ANY_INIT</tt>, according to the family.
163If <tt>port</tt> is 0, the system automatically
164chooses an ephemeral port.
165</p>
166
167<p class=return>
168In case of success, the method returns 1. In case of error, the
169method returns <b><tt>nil</tt></b> followed by an error message.
170</p>
171
172<p class=note>
173Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a>
174is available and is a shortcut for the creation of server sockets.
175</p>
176
177<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
178
179<p class=name id="close">
180master:<b>close()</b><br>
181client:<b>close()</b><br>
182server:<b>close()</b>
183</p>
184
185<p class=description>
186Closes a TCP object. The internal socket used by the object is closed
187and the local address to which the object was
188bound is made available to other applications. No further operations
189(except for further calls to the <tt>close</tt> method) are allowed on
190a closed socket.
191</p>
192
193<p class=note>
194Note: It is important to close all used sockets once they are not
195needed, since, in many systems, each socket uses a file descriptor,
196which are limited system resources. Garbage-collected objects are
197automatically closed before destruction, though.
198</p>
199
200<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
201
202<p class=name id="connect">
203master:<b>connect(</b>address, port<b>)</b>
204</p>
205
206<p class=description>
207Attempts to connect a master object to a remote host, transforming it into a
208client object.
209Client objects support methods
210<a href=#send><tt>send</tt></a>,
211<a href=#receive><tt>receive</tt></a>,
212<a href=#getsockname><tt>getsockname</tt></a>,
213<a href=#getpeername><tt>getpeername</tt></a>,
214<a href=#settimeout><tt>settimeout</tt></a>,
215and <a href=#close><tt>close</tt></a>.
216</p>
217
218<p class=parameters>
219<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).
221</p>
222
223<p class=return>
224In 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.
226</p>
227
228<p class=note>
229Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a>
230is available and is a shortcut for the creation of client sockets.
231</p>
232
233<p class=note>
234Note: Starting with LuaSocket 2.0,
235the <a href=#settimeout><tt>settimeout</tt></a>
236method 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
238href=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
240established.
241</p>
242
243<p class=note>
244Note: Starting with LuaSocket 3.0, the host name resolution
245depends on whether the socket was created by <a
246href=#socket.tcp><tt>socket.tcp</tt></a> or <a
247href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from
248the appropriate family are tried in succession until the
249first success or until the last failure.
250</p>
251
252<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254<p class=name id="getpeername">
255client:<b>getpeername()</b>
256</p>
257
258<p class=description>
259Returns information about the remote side of a connected client object.
260</p>
261
262<p class=return>
263Returns a string with the IP address of the peer, the
264port number that peer is using for the connection,
265and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
266In case of error, the method returns <b><tt>nil</tt></b>.
267</p>
268
269<p class=note>
270Note: It makes no sense to call this method on server objects.
271</p>
272
273<!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
274
275<p class=name id="getsockname">
276master:<b>getsockname()</b><br>
277client:<b>getsockname()</b><br>
278server:<b>getsockname()</b>
279</p>
280
281<p class=description>
282Returns the local address information associated to the object.
283</p>
284
285<p class=return>
286The method returns a string with local IP address, a number with
287the local port,
288and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
289In case of error, the method returns <b><tt>nil</tt></b>.
290</p>
291
292<!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
293
294<p class=name id="getstats">
295master:<b>getstats()</b><br>
296client:<b>getstats()</b><br>
297server:<b>getstats()</b><br>
298</p>
299
300<p class=description>
301Returns accounting information on the socket, useful for throttling
302of bandwidth.
303</p>
304
305<p class=return>
306The method returns the number of bytes received, the number of bytes sent,
307and the age of the socket object in seconds.
308</p>
309
310<!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
311
312<p class=name id="listen">
313master:<b>listen(</b>backlog<b>)</b>
314</p>
315
316<p class=description>
317Specifies the socket is willing to receive connections, transforming the
318object into a server object. Server objects support the
319<a href=#accept><tt>accept</tt></a>,
320<a href=#getsockname><tt>getsockname</tt></a>,
321<a href=#setoption><tt>setoption</tt></a>,
322<a href=#settimeout><tt>settimeout</tt></a>,
323and <a href=#close><tt>close</tt></a> methods.
324</p>
325
326<p class=parameters>
327The parameter <tt>backlog</tt> specifies the number of client
328connections that can
329be queued waiting for service. If the queue is full and another client
330attempts connection, the connection is refused.
331</p>
332
333<p class=return>
334In case of success, the method returns 1. In case of error, the
335method returns <b><tt>nil</tt></b> followed by an error message.
336</p>
337
338<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
339
340<p class=name id="receive">
341client:<b>receive(</b>[pattern [, prefix]]<b>)</b>
342</p>
343
344<p class=description>
345Reads 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.
347</p>
348
349<p class=parameters>
350<tt>Pattern</tt> can be any of the following:
351</p>
352
353<ul>
354<li> '<tt>*a</tt>': reads from the socket until the connection is
355closed. No end-of-line translation is performed;
356<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
358CR character (ASCII&nbsp;13). The CR and LF characters are not included in
359the returned line. In fact, <em>all</em> CR characters are
360ignored by the pattern. This is the default pattern;
361<li> <tt>number</tt>: causes the method to read a specified <tt>number</tt>
362of bytes from the socket.
363</ul>
364
365<p class=parameters>
366<tt>Prefix</tt> is an optional string to be concatenated to the beginning
367of any received data before return.
368</p>
369
370<p class=return>
371If successful, the method returns the received pattern. In case of error,
372the method returns <tt><b>nil</b></tt> followed by an error
373message, followed by a (possibly empty) string containing
374the partial that was received. The error message can be
375the string '<tt>closed</tt>' in case the connection was
376closed before the transmission was completed or the string
377'<tt>timeout</tt>' in case there was a timeout during the operation.
378</p>
379
380<p class=note>
381<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
383now it doesn't anymore. Partial results used to be returned in the same
384way as successful results. This last feature violated the idea that all
385functions should return <tt><b>nil</b></tt> on error. Thus it was changed
386too.
387</p>
388
389<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
390
391<p class=name id="send">
392client:<b>send(</b>data [, i [, j]]<b>)</b>
393</p>
394
395<p class=description>
396Sends <tt>data</tt> through client object.
397</p>
398
399<p class=parameters>
400<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
402<tt>string.sub</tt> Lua function to allow the selection of a
403substring to be sent.
404</p>
405
406<p class=return>
407If successful, the method returns the index of the last byte
408within <tt>[i, j]</tt> that has been sent. Notice that, if
409<tt>i</tt> is 1 or absent, this is effectively the total
410number of bytes sent. In case of error, the method returns
411<b><tt>nil</tt></b>, followed by an error message, followed
412by the index of the last byte within <tt>[i, j]</tt> that
413has been sent. You might want to try again from the byte
414following that. The error message can be '<tt>closed</tt>'
415in case the connection was closed before the transmission
416was completed or the string '<tt>timeout</tt>' in case
417there was a timeout during the operation.
418</p>
419
420<p class=note>
421Note: Output is <em>not</em> buffered. For small strings,
422it is always better to concatenate them in Lua
423(with the '<tt>..</tt>' operator) and send the result in one call
424instead of calling the method several times.
425</p>
426
427<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
428
429<p class=name id="setoption">
430client:<b>setoption(</b>option [, value]<b>)</b><br>
431server:<b>setoption(</b>option [, value]<b>)</b>
432</p>
433
434<p class=description>
435Sets options for the TCP object. Options are only needed by low-level or
436time-critical applications. You should only modify an option if you
437are sure you need it.
438</p>
439
440<p class=parameters>
441<tt>Option</tt> is a string with the option name, and <tt>value</tt>
442depends on the option being set:
443
444<ul>
445
446<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
447the periodic transmission of messages on a connected socket. Should the
448connected party fail to respond to these messages, the connection is
449considered broken and processes using the socket are notified;
450
451<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
453boolean entry '<tt>on</tt>' and a numeric entry for the time interval
454'<tt>timeout</tt>' in seconds. If the '<tt>on</tt>' field is set to
455<tt>true</tt>, the system will block the process on the close attempt until
456it 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
458process 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
460zero;
461
462<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
463used in validating addresses supplied in a call to
464<a href=#bind><tt>bind</tt></a> should allow reuse of local addresses;
465
466<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt>
467disables the Nagle's algorithm for the connection;
468
469<li> '<tt>ipv6-v6only</tt>':
470Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to
471sending and receiving only IPv6 packets.
472</ul>
473
474<p class=return>
475The method returns 1 in case of success, or <b><tt>nil</tt></b>
476followed by an error message otherwise.
477</p>
478
479<p class=note>
480Note: The descriptions above come from the man pages.
481</p>
482
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
512
513<p class=name id="setstats">
514master:<b>setstats(</b>received, sent, age<b>)</b><br>
515client:<b>setstats(</b>received, sent, age<b>)</b><br>
516server:<b>setstats(</b>received, sent, age<b>)</b><br>
517</p>
518
519<p class=description>
520Resets accounting information on the socket, useful for throttling
521of bandwidth.
522</p>
523
524<p class=parameters>
525<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.
527<tt>Age</tt> is the new age in seconds.
528</p>
529
530<p class=return>
531The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
532</p>
533
534<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
535
536<p class=name id="settimeout">
537master:<b>settimeout(</b>value [, mode]<b>)</b><br>
538client:<b>settimeout(</b>value [, mode]<b>)</b><br>
539server:<b>settimeout(</b>value [, mode]<b>)</b>
540</p>
541
542<p class=description>
543Changes the timeout values for the object. By default,
544all I/O operations are blocking. That is, any call to the methods
545<a href=#send><tt>send</tt></a>,
546<a href=#receive><tt>receive</tt></a>, and
547<a href=#accept><tt>accept</tt></a>
548will block indefinitely, until the operation completes. The
549<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
551time has elapsed, the affected methods give up and fail with an error code.
552</p>
553
554<p class=parameters>
555The amount of time to wait is specified as the
556<tt>value</tt> parameter, in seconds. There are two timeout modes and
557both can be used together for fine tuning:
558</p>
559
560<ul>
561<li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on
562the amount of time LuaSocket can be blocked by the operating system
563while waiting for completion of any single I/O operation. This is the
564default mode;</li>
565
566<li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on
567the amount of time LuaSocket can block a Lua script before returning from
568a call.</li>
569</ul>
570
571<p class=parameters>
572The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block
573indefinitely. Negative timeout values have the same effect.
574</p>
575
576<p class=note>
577Note: although timeout values have millisecond precision in LuaSocket,
578large 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
580and to and from the Lua interpreter. Also, function that accept host names
581and perform automatic name resolution might be blocked by the resolver for
582longer than the specified timeout value.
583</p>
584
585<p class=note>
586Note: The old <tt>timeout</tt> method is deprecated. The name has been
587changed for sake of uniformity, since all other method names already
588contained verbs making their imperative nature obvious.
589</p>
590
591<!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
592
593<p class=name id="shutdown">
594client:<b>shutdown(</b>mode<b>)</b><br>
595</p>
596
597<p class=description>
598Shuts down part of a full-duplex connection.
599</p>
600
601<p class=parameters>
602Mode tells which way of the connection should be shut down and can
603take the value:
604<ul>
605<li>"<tt>both</tt>": disallow further sends and receives on the object.
606This is the default mode;
607<li>"<tt>send</tt>": disallow further sends on the object;
608<li>"<tt>receive</tt>": disallow further receives on the object.
609</ul>
610
611<p class=return>
612This function returns 1.
613</p>
614
615<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
616
617<p class=name id="dirty">
618master:<b>dirty()</b><br>
619client:<b>dirty()</b><br>
620server:<b>dirty()</b>
621</p>
622
623<p class=description>
624Check the read buffer status.
625</p>
626
627<p class=return>
628Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise.
629</p>
630
631<p class=note>
632Note: <b>This is an internal method, any use is unlikely to be portable.</b>
633</p>
634
635<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
636
637<p class=name id="getfd">
638master:<b>getfd()</b><br>
639client:<b>getfd()</b><br>
640server:<b>getfd()</b>
641</p>
642
643<p class=description>
644Returns the underling socket descriptor or handle associated to the object.
645</p>
646
647<p class=return>
648The descriptor or handle. In case the object has been closed, the return will be -1.
649</p>
650
651<p class=note>
652Note: <b>This is an internal method, any use is unlikely to be portable.</b>
653</p>
654
655<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
656
657<p class=name id="setfd">
658master:<b>setfd(</b>fd<b>)</b><br>
659client:<b>setfd(</b>fd<b>)</b><br>
660server:<b>setfd(</b>fd<b>)</b>
661</p>
662
663<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.
665</p>
666
667<p class=return>
668No return value.
669</p>
670
671<p class=note>
672Note: <b>This is an internal method, any use is unlikely to be portable.</b>
673</p>
674
675<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
676
677<div class=footer>
678<hr>
679<center>
680<p class=bar>
681<a href="index.html">home</a> &middot;
682<a href="index.html#down">download</a> &middot;
683<a href="installation.html">installation</a> &middot;
684<a href="introduction.html">introduction</a> &middot;
685<a href="reference.html">reference</a>
686</p>
687<p>
688<small>
689Last modified by Diego Nehab on <br>
690Thu Apr 20 00:25:57 EDT 2006
691</small>
692</p>
693</center>
694</div>
695
696</body>
697</html>
diff --git a/doc/udp.html b/doc/udp.html
deleted file mode 100644
index a300f2f..0000000
--- a/doc/udp.html
+++ /dev/null
@@ -1,578 +0,0 @@
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="LuaSocket: The UDP support">
7<meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support">
8<title>LuaSocket: UDP support</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
38<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<h2 id="udp">UDP</h2>
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
149
150<p class="name" id="close">
151connected:<b>close()</b><br>
152unconnected:<b>close()</b>
153</p>
154
155<p class="description">
156Closes a UDP object. The internal socket
157used by the object is closed and the local address to which the
158object was bound is made available to other applications. No
159further operations (except for further calls to the <tt>close</tt>
160method) are allowed on a closed socket.
161</p>
162
163<p class="note">
164Note: It is important to close all used sockets
165once they are not needed, since, in many systems, each socket uses
166a file descriptor, which are limited system resources.
167Garbage-collected objects are automatically closed before
168destruction, though.
169</p>
170
171<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
172
173<p class="name" id="getpeername">
174connected:<b>getpeername()</b>
175</p>
176
177<p class="description">
178Retrieves information about the peer
179associated with a connected UDP object.
180</p>
181
182
183<p class=return>
184Returns a string with the IP address of the peer, the
185port number that peer is using for the connection,
186and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
187In case of error, the method returns <b><tt>nil</tt></b>.
188</p>
189
190<p class="note">
191Note: It makes no sense to call this method on unconnected objects.
192</p>
193
194<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
195
196<p class="name" id="getsockname">
197connected:<b>getsockname()</b><br>
198unconnected:<b>getsockname()</b>
199</p>
200
201<p class="description">
202Returns the local address information associated to the object.
203</p>
204
205
206<p class=return>
207The method returns a string with local IP address, a number with
208the local port,
209and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
210In case of error, the method returns <b><tt>nil</tt></b>.
211</p>
212
213<p class="note">
214Note: UDP sockets are not bound to any address
215until the <a href="#setsockname"><tt>setsockname</tt></a> or the
216<a href="#sendto"><tt>sendto</tt></a> method is called for the
217first time (in which case it is bound to an ephemeral port and the
218wild-card address).
219</p>
220
221<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
222
223<p class="name" id="receive">
224connected:<b>receive(</b>[size]<b>)</b><br>
225unconnected:<b>receive(</b>[size]<b>)</b>
226</p>
227
228<p class="description">
229Receives a datagram from the UDP object. If
230the UDP object is connected, only datagrams coming from the peer
231are accepted. Otherwise, the returned datagram can come from any
232host.
233</p>
234
235<p class="parameters">
236The optional <tt>size</tt> parameter
237specifies the maximum size of the datagram to be retrieved. If
238there are more than <tt>size</tt> bytes available in the datagram,
239the excess bytes are discarded. If there are less then
240<tt>size</tt> bytes available in the current datagram, the
241available bytes are returned. If <tt>size</tt> is omitted, the
242maximum datagram size is used (which is currently limited by the
243implementation to 8192 bytes).
244</p>
245
246<p class="return">
247In case of success, the method returns the
248received datagram. In case of timeout, the method returns
249<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
250</p>
251
252<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
253
254<p class="name" id="receivefrom">
255unconnected:<b>receivefrom(</b>[size]<b>)</b>
256</p>
257
258<p class="description">
259Works exactly as the <a href="#receive"><tt>receive</tt></a>
260method, except it returns the IP
261address and port as extra return values (and is therefore slightly less
262efficient).
263</p>
264
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 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
300
301<p class="name" id="send">
302connected:<b>send(</b>datagram<b>)</b>
303</p>
304
305<p class="description">
306Sends a datagram to the UDP peer of a connected object.
307</p>
308
309<p class="parameters">
310<tt>Datagram</tt> is a string with the datagram contents.
311The maximum datagram size for UDP is 64K minus IP layer overhead.
312However datagrams larger than the link layer packet size will be
313fragmented, which may deteriorate performance and/or reliability.
314</p>
315
316<p class="return">
317If successful, the method returns 1. In case of
318error, the method returns <b><tt>nil</tt></b> followed by an error message.
319</p>
320
321<p class="note">
322Note: In UDP, the <tt>send</tt> method never blocks
323and the only way it can fail is if the underlying transport layer
324refuses to send a message to the specified address (i.e. no
325interface accepts the address).
326</p>
327
328<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
329
330<p class="name" id="sendto">
331unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
332</p>
333
334<p class="description">
335Sends a datagram to the specified IP address and port number.
336</p>
337
338<p class="parameters">
339<tt>Datagram</tt> is a string with the
340datagram contents.
341The maximum datagram size for UDP is 64K minus IP layer overhead.
342However datagrams larger than the link layer packet size will be
343fragmented, which may deteriorate performance and/or reliability.
344<tt>Ip</tt> is the IP address of the recipient.
345Host names are <em>not</em> allowed for performance reasons.
346
347<tt>Port</tt> is the port number at the recipient.
348</p>
349
350<p class="return">
351If successful, the method returns 1. In case of
352error, the method returns <b><tt>nil</tt></b> followed by an error message.
353</p>
354
355<p class="note">
356Note: In UDP, the <tt>send</tt> method never blocks
357and the only way it can fail is if the underlying transport layer
358refuses to send a message to the specified address (i.e. no
359interface accepts the address).
360</p>
361
362<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
363
364<p class="name" id="setpeername">
365connected:<b>setpeername(</b>'*'<b>)</b><br>
366unconnected:<b>setpeername(</b>address, port<b>)</b>
367</p>
368
369<p class="description">
370Changes the peer of a UDP object. This
371method turns an unconnected UDP object into a connected UDP
372object or vice versa.
373</p>
374
375<p class="description">
376For connected objects, outgoing datagrams
377will be sent to the specified peer, and datagrams received from
378other peers will be discarded by the OS. Connected UDP objects must
379use the <a href="#send"><tt>send</tt></a> and
380<a href="#receive"><tt>receive</tt></a> methods instead of
381<a href="#sendto"><tt>sendto</tt></a> and
382<a href="#receivefrom"><tt>receivefrom</tt></a>.
383</p>
384
385<p class="parameters">
386<tt>Address</tt> can be an IP address or a
387host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
388'<tt>*</tt>' and the object is connected, the peer association is
389removed and the object becomes an unconnected object again. In that
390case, the <tt>port</tt> argument is ignored.
391</p>
392
393<p class="return">
394In case of error the method returns
395<b><tt>nil</tt></b> followed by an error message. In case of success, the
396method returns 1.
397</p>
398
399<p class="note">
400Note: Since the address of the peer does not have
401to be passed to and from the OS, the use of connected UDP objects
402is recommended when the same peer is used for several transmissions
403and can result in up to 30% performance gains.
404</p>
405
406<p class=note>
407Note: Starting with LuaSocket 3.0, the host name resolution
408depends on whether the socket was created by <a
409href=#socket.udp><tt>socket.udp</tt></a> or <a
410href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
411the appropriate family are tried in succession until the
412first success or until the last failure.
413</p>
414
415<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
416
417<p class="name" id="setsockname">
418unconnected:<b>setsockname(</b>address, port<b>)</b>
419</p>
420
421<p class="description">
422Binds the UDP object to a local address.
423</p>
424
425<p class="parameters">
426<tt>Address</tt> can be an IP address or a
427host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
428all local interfaces using the constant <tt>INADDR_ANY</tt>. If
429<tt>port</tt> is 0, the system chooses an ephemeral port.
430</p>
431
432<p class="return">
433If successful, the method returns 1. In case of
434error, the method returns <b><tt>nil</tt></b> followed by an error
435message.
436</p>
437
438<p class="note">
439Note: This method can only be called before any
440datagram is sent through the UDP object, and only once. Otherwise,
441the system automatically binds the object to all local interfaces
442and chooses an ephemeral port as soon as the first datagram is
443sent. After the local address is set, either automatically by the
444system or explicitly by <tt>setsockname</tt>, it cannot be
445changed.
446</p>
447
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 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
517
518<p class="name" id="settimeout">
519connected:<b>settimeout(</b>value<b>)</b><br>
520unconnected:<b>settimeout(</b>value<b>)</b>
521</p>
522
523<p class="description">
524Changes the timeout values for the object. By default, the
525<a href="#receive"><tt>receive</tt></a> and
526<a href="#receivefrom"><tt>receivefrom</tt></a>
527operations are blocking. That is, any call to the methods will block
528indefinitely, until data arrives. The <tt>settimeout</tt> function defines
529a limit on the amount of time the functions can block. When a timeout is
530set and the specified amount of time has elapsed, the affected methods
531give up and fail with an error code.
532</p>
533
534<p class="parameters">
535The amount of time to wait is specified as
536the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
537<tt>value</tt> allows operations to block indefinitely. Negative
538timeout values have the same effect.
539</p>
540
541<p class="note">
542Note: In UDP, the <a href="#send"><tt>send</tt></a>
543and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
544datagram is just passed to the OS and the call returns
545immediately). Therefore, the <tt>settimeout</tt> method has no
546effect on them.
547</p>
548
549<p class="note">
550Note: The old <tt>timeout</tt> method is
551deprecated. The name has been changed for sake of uniformity, since
552all other method names already contained verbs making their
553imperative nature obvious.
554</p>
555
556<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
557
558<div class=footer>
559<hr>
560<center>
561<p class=bar>
562<a href="index.html">home</a> &middot;
563<a href="index.html#download">download</a> &middot;
564<a href="installation.html">installation</a> &middot;
565<a href="introduction.html">introduction</a> &middot;
566<a href="reference.html">reference</a>
567</p>
568<p>
569<small>
570Last modified by Diego Nehab on <br>
571Thu Apr 20 00:26:01 EDT 2006
572</small>
573</p>
574</center>
575</div>
576
577</body>
578</html>
diff --git a/doc/url.html b/doc/url.html
deleted file mode 100644
index 6ff673d..0000000
--- a/doc/url.html
+++ /dev/null
@@ -1,328 +0,0 @@
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="LuaSocket: URL manipulation">
7<meta name="keywords" content="Lua, LuaSocket, URL, Library, Link, Network, Support">
8<title>LuaSocket: URL support</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<!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id="url">URL</h2>
40
41<p>
42The <tt>url</tt> namespace provides functions to parse, protect,
43and build URLs, as well as functions to compose absolute URLs
44from base and relative URLs, according to
45<a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>.
46</p>
47
48<p>
49To obtain the <tt>url</tt> namespace, run:
50</p>
51
52<pre class=example>
53-- loads the URL module
54local url = require("socket.url")
55</pre>
56
57<p>
58An URL is defined by the following grammar:
59</p>
60
61<blockquote>
62<tt>
63&lt;url&gt; ::= [&lt;scheme&gt;:][//&lt;authority&gt;][/&lt;path&gt;][;&lt;params&gt;][?&lt;query&gt;][#&lt;fragment&gt;]<br>
64&lt;authority&gt; ::= [&lt;userinfo&gt;@]&lt;host&gt;[:&lt;port&gt;]<br>
65&lt;userinfo&gt; ::= &lt;user&gt;[:&lt;password&gt;]<br>
66&lt;path&gt; ::= {&lt;segment&gt;/}&lt;segment&gt;<br>
67</tt>
68</blockquote>
69
70<!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
71
72<p class=name id="absolute">
73url.<b>absolute(</b>base, relative<b>)</b>
74</p>
75
76<p class=description>
77Builds an absolute URL from a base URL and a relative URL.
78</p>
79
80<p class=parameters>
81<tt>Base</tt> is a string with the base URL or
82a parsed URL table. <tt>Relative</tt> is a
83string with the relative URL.
84</p>
85
86<p class=return>
87The function returns a string with the absolute URL.
88</p>
89
90<p class=note>
91Note: The rules that
92govern the composition are fairly complex, and are described in detail in
93<a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>.
94The example bellow should give an idea of what the rules are.
95</p>
96
97<pre class=example>
98http://a/b/c/d;p?q
99
100+
101
102g:h = g:h
103g = http://a/b/c/g
104./g = http://a/b/c/g
105g/ = http://a/b/c/g/
106/g = http://a/g
107//g = http://g
108?y = http://a/b/c/?y
109g?y = http://a/b/c/g?y
110#s = http://a/b/c/d;p?q#s
111g#s = http://a/b/c/g#s
112g?y#s = http://a/b/c/g?y#s
113;x = http://a/b/c/;x
114g;x = http://a/b/c/g;x
115g;x?y#s = http://a/b/c/g;x?y#s
116. = http://a/b/c/
117./ = http://a/b/c/
118.. = http://a/b/
119../ = http://a/b/
120../g = http://a/b/g
121../.. = http://a/
122../../ = http://a/
123../../g = http://a/g
124</pre>
125
126<!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
127
128<p class=name id="build">
129url.<b>build(</b>parsed_url<b>)</b>
130</p>
131
132<p class=description>
133Rebuilds an URL from its parts.
134</p>
135
136<p class=parameters>
137<tt>Parsed_url</tt> is a table with same components returned by
138<a href="#parse"><tt>parse</tt></a>.
139Lower level components, if specified,
140take precedence over high level components of the URL grammar.
141</p>
142
143<p class=return>
144The function returns a string with the built URL.
145</p>
146
147<!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
148
149<p class=name id="build_path">
150url.<b>build_path(</b>segments, unsafe<b>)</b>
151</p>
152
153<p class=description>
154Builds a <tt>&lt;path&gt;</tt> component from a list of
155<tt>&lt;segment&gt;</tt> parts.
156Before composition, any reserved characters found in a segment are escaped into
157their protected form, so that the resulting path is a valid URL path
158component.
159</p>
160
161<p class=parameters>
162<tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
163parts. If <tt>unsafe</tt> is anything but <b><tt>nil</tt></b>, reserved
164characters are left untouched.
165</p>
166
167<p class=return>
168The function returns a string with the
169built <tt>&lt;path&gt;</tt> component.
170</p>
171
172<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
173
174<p class=name id="escape">
175url.<b>escape(</b>content<b>)</b>
176</p>
177
178<p class=description>
179Applies the URL escaping content coding to a string
180Each byte is encoded as a percent character followed
181by the two byte hexadecimal representation of its integer
182value.
183</p>
184
185<p class=parameters>
186<tt>Content</tt> is the string to be encoded.
187</p>
188
189<p class=result>
190The function returns the encoded string.
191</p>
192
193<pre class=example>
194-- load url module
195url = require("socket.url")
196
197code = url.escape("/#?;")
198-- code = "%2f%23%3f%3b"
199</pre>
200
201<!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
202
203<p class=name id="parse">
204url.<b>parse(</b>url, default<b>)</b>
205</p>
206
207<p class=description>
208Parses an URL given as a string into a Lua table with its components.
209</p>
210
211<p class=parameters>
212<tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is
213present, it is used to store the parsed fields. Only fields present in the
214URL are overwritten. Therefore, this table can be used to pass default
215values for each field.
216</p>
217
218<p class=return>
219The function returns a table with all the URL components:
220</p>
221
222<blockquote><tt>
223parsed_url = {<br>
224&nbsp;&nbsp;url = <i>string</i>,<br>
225&nbsp;&nbsp;scheme = <i>string</i>,<br>
226&nbsp;&nbsp;authority = <i>string</i>,<br>
227&nbsp;&nbsp;path = <i>string</i>,<br>
228&nbsp;&nbsp;params = <i>string</i>,<br>
229&nbsp;&nbsp;query = <i>string</i>,<br>
230&nbsp;&nbsp;fragment = <i>string</i>,<br>
231&nbsp;&nbsp;userinfo = <i>string</i>,<br>
232&nbsp;&nbsp;host = <i>string</i>,<br>
233&nbsp;&nbsp;port = <i>string</i>,<br>
234&nbsp;&nbsp;user = <i>string</i>,<br>
235&nbsp;&nbsp;password = <i>string</i><br>
236}
237</tt></blockquote>
238
239<pre class=example>
240-- load url module
241url = require("socket.url")
242
243parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there")
244-- parsed_url = {
245-- scheme = "http",
246-- authority = "www.example.com",
247-- path = "/cgilua/index.lua"
248-- query = "a=2",
249-- fragment = "there",
250-- host = "www.puc-rio.br",
251-- }
252
253parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
254-- parsed_url = {
255-- scheme = "ftp",
256-- authority = "root:passwd@unsafe.org",
257-- path = "/pub/virus.exe",
258-- params = "type=i",
259-- userinfo = "root:passwd",
260-- host = "unsafe.org",
261-- user = "root",
262-- password = "passwd",
263-- }
264</pre>
265
266<!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
267
268<p class=name id="parse_path">
269url.<b>parse_path(</b>path<b>)</b>
270</p>
271
272<p class=description>
273Breaks a <tt>&lt;path&gt;</tt> URL component into all its
274<tt>&lt;segment&gt;</tt> parts.
275</p>
276
277<p class=description>
278<tt>Path</tt> is a string with the path to be parsed.
279</p>
280
281<p class=return>
282Since some characters are reserved in URLs, they must be escaped
283whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
284returning a list with all the parsed segments, the function removes
285escaping from all of them.
286</p>
287
288<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
289
290<p class=name id="unescape">
291url.<b>unescape(</b>content<b>)</b>
292</p>
293
294<p class=description>
295Removes the URL escaping content coding from a string.
296</p>
297
298<p class=parameters>
299<tt>Content</tt> is the string to be decoded.
300</p>
301
302<p class=return>
303The function returns the decoded string.
304</p>
305
306<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
307
308<div class=footer>
309<hr>
310<center>
311<p class=bar>
312<a href="index.html">home</a> &middot;
313<a href="index.html#down">download</a> &middot;
314<a href="installation.html">installation</a> &middot;
315<a href="introduction.html">introduction</a> &middot;
316<a href="reference.html">reference</a>
317</p>
318<p>
319<small>
320Last modified by Diego Nehab on <br>
321Thu Apr 20 00:26:05 EDT 2006
322</small>
323</p>
324</center>
325</div>
326
327</body>
328</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-04-03 18:20:39 +0000