aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
committerDiego Nehab <diego@tecgraf.puc-rio.br>2003-08-31 01:00:15 +0000
commit982781f1464c9b7a8133130433f83dbf1f59a2c0 (patch)
tree8f96f9e9fa1e6bef8b8356037986ddc18673cade
parent6789b83ff5c15296267f880d3b98cf8a1800c30a (diff)
downloadluasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.gz
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.tar.bz2
luasocket-982781f1464c9b7a8133130433f83dbf1f59a2c0.zip
LuaSocket 2.0 User's Manual.
Diffstat
-rw-r--r--doc/code.html202
-rw-r--r--doc/dns.html120
-rw-r--r--doc/ftp.html243
-rw-r--r--doc/http.html388
-rw-r--r--doc/index.html212
-rw-r--r--doc/introduction.html328
-rw-r--r--doc/luasocket.pngbin0 -> 11732 bytes
-rw-r--r--doc/reference.css40
-rw-r--r--doc/reference.html209
-rw-r--r--doc/smtp.html228
-rw-r--r--doc/stream.html173
-rw-r--r--doc/tcp.html415
-rw-r--r--doc/udp.html400
-rw-r--r--doc/url.html265
14 files changed, 3223 insertions, 0 deletions
diff --git a/doc/code.html b/doc/code.html
new file mode 100644
index 0000000..45fd21a
--- /dev/null
+++ b/doc/code.html
@@ -0,0 +1,202 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- code +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=code>Code</h2>
37
38<p>
39The <tt>code.lua</tt> module offers routines to convert back and forth
40some common types of content encoding, including Base 64 and URL
41escaping. Base 64 is described in
42<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2045.txt">RFC
432045</a>,
44URL escaping is described in
45<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
462396</a>.
47</p>
48
49<!-- base64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
50
51<p class=name id="base64">
52socket.code.<b>base64(</b>content, single<b>)</b>
53</p>
54
55<p class=description>
56Applies the Base 64 content coding to a string.
57</p>
58
59<p class=parameters>
60<tt>Content</tt> is the string to be encoded.
61If <tt>single</tt> is set to anything
62but <tt>nil</tt>, the output is returned as a single
63line, otherwise the function splits the content into 76 character long
64lines after encoding.
65</p>
66
67<p class=result>
68The function returns the encoded string.
69</p>
70
71<pre class=example>
72code = socket.code.base64("diego:password")
73-- code = "ZGllZ286cGFzc3dvcmQ="
74</pre>
75
76<!-- unbase64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
77
78<p class=name id="unbase64">
79socket.code.<b>unbase64(</b>content<b>)</b>
80</p>
81
82<p class=description>
83Removes the Base 64 content coding from a string.
84</p>
85
86<p class=parameters>
87<tt>Content</tt> is the string to be decoded.
88</p>
89
90<p class=result>
91The function returns the decoded string.
92</p>
93
94<!-- escape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
95
96<p class=name id="escape">
97socket.code.<b>escape(</b>content<b>)</b>
98</p>
99
100<p class=description>
101Applies the URL escaping content coding to a string
102Each byte is encoded as a percent character followed
103by the two byte hexadecimal representation of its integer
104value.
105</p>
106
107<p class=parameters>
108<tt>Content</tt> is the string to be encoded.
109</p>
110
111<p class=result>
112The function returns the encoded string.
113</p>
114
115<pre class=example>
116code = socket.code.escape("/#?;")
117-- code = "%2f%23%3f%3b"
118</pre>
119
120<!-- unescape +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
121
122<p class=name id="unescape">
123socket.code.<b>unescape(</b>content<b>)</b>
124</p>
125
126<p class=description>
127Removes the URL escaping content coding from a string.
128</p>
129
130<p class=parameters>
131<tt>Content</tt> is the string to be decoded.
132</p>
133
134<p class=return>
135The function returns the decoded string.
136</p>
137
138<!-- hexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id="hexa">
141socket.code.<b>hexa(</b>content<b>)</b>
142</p>
143
144<p class=description>
145Applies the hexadecimal content coding to a string.
146Each byte is encoded as the byte hexadecimal
147representation of its integer value. <p>
148</p>
149
150<p class=parameters>
151<tt>Content</tt> is the string to be encoded.
152</p>
153
154<p class=return>
155The function returns the encoded string.
156</p>
157
158<pre class=example>
159code = socket.code.hexa("\16\32\255")
160-- code = "1020ff"
161</pre>
162
163<!-- unhexa +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
164
165<p class=name id="unhexa">
166socket.code.<b>unhexa(</b>content<b>)</b>
167</p>
168
169<p class=description>
170Removes the hexadecimal content coding from a string.
171</p>
172
173<p class=parameters>
174<tt>Content</tt> is the string to be decoded.
175</p>
176
177<p class=return>
178The function returns the decoded string.
179</p>
180
181<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
182
183<div class=footer>
184<hr>
185<center>
186<p class=bar>
187<a href="home.html">home</a> &middot;
188<a href="home.html#down">download</a> &middot;
189<a href="introduction.html">introduction</a> &middot;
190<a href="reference.html">reference</a>
191</p>
192<p>
193<small>
194Last modified by Diego Nehab on <br>
195Sat Aug 9 01:00:41 PDT 2003
196</small>
197</p>
198</center>
199</div>
200
201</body>
202</html>
diff --git a/doc/dns.html b/doc/dns.html
new file mode 100644
index 0000000..6abf341
--- /dev/null
+++ b/doc/dns.html
@@ -0,0 +1,120 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=dns>DNS</h2>
37
38<p>
39The following functions can be used to convert between host names and IP
40addresses. Both functions return <em>all</em> information returned by the
41resolver in a table of the form:
42</p>
43
44<blockquote><tt>
45resolved = {<br>
46&nbsp;&nbsp;name = <i>canonic-name</i>,<br>
47&nbsp;&nbsp;alias = <i>alias-list</i>,<br>
48&nbsp;&nbsp;ip = <i>ip-address-list</i><br>
49}
50</tt> </blockquote>
51
52<p>
53Note that the <tt>alias</tt> list can be empty.
54</p>
55
56<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
57
58<p class=name id=tohostname>
59socket.dns.<b>tohostname()</b>
60</p>
61
62<p class=description>
63Converts from IP address to host name.
64</p>
65
66<p class=parameters>
67<tt>Address</tt> can be an IP address or host name.
68</p>
69
70<p class=return>
71The function a string with the canonic host name of the given
72<tt>address</tt>, followed by a table with all information returned by
73the resolver. In case of error, the function returns <tt>nil</tt>
74followed by an error message.
75</p>
76
77
78<!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
79
80<p class=name id=toip>
81socket.dns.<b>toip()</b>
82</p>
83
84<p class=description>
85Converts from host name to IP address.
86</p>
87
88<p class=parameters>
89<tt>Address</tt> can be an IP address or host name.
90</p>
91
92<p class=return>
93Returns a string with the first IP address found for <tt>address</tt>,
94followed by a table with all information returned by the resolver.
95In case of error, the function returns <tt>nil</tt> followed by an error
96message.
97</p>
98
99<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
100
101<div class=footer>
102<hr>
103<center>
104<p class=bar>
105<a href="home.html">home</a> &middot;
106<a href="home.html#down">download</a> &middot;
107<a href="introduction.html">introduction</a> &middot;
108<a href="reference.html">reference</a>
109</p>
110<p>
111<small>
112Last modified by Diego Nehab on <br>
113Sat Aug 9 01:00:41 PDT 2003
114</small>
115</p>
116</center>
117</div>
118
119</body>
120</html>
diff --git a/doc/ftp.html b/doc/ftp.html
new file mode 100644
index 0000000..8072afe
--- /dev/null
+++ b/doc/ftp.html
@@ -0,0 +1,243 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html>
2
3<head>
4<title>LuaSocket: Network support for the Lua language</title>
5<link rel="stylesheet" href="reference.css" type="text/css">
6</head>
7
8<body>
9
10<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
11
12<div class=header>
13<hr>
14<center>
15<table summary="LuaSocket logo">
16<tr><td align=center><a href="http://www.lua.org">
17<img border=0 alt="LuaSocket" src="luasocket.png">
18</a></td></tr>
19<tr><td align=center valign=top>Network support for the Lua language
20</td></tr>
21</table>
22<p class=bar>
23<a href="home.html">home</a> &middot;
24<a href="home.html#download">download</a> &middot;
25<a href="introduction.html">introduction</a> &middot;
26<a href="reference.html">reference</a>
27</p>
28</center>
29<hr>
30</div>
31
32<!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
33
34<h2 id=ftp>FTP</h2>
35
36<p>
37FTP (File Transfer Protocol) is a protocol used to transfer files
38between hosts. The module <tt>ftp.lua</tt> offers simple FTP support,
39allowing applications to download and upload files, and list directory
40contents. The implementation conforms to
41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc0959.txt">RFC 959</a>.
42</p>
43
44<p>
45URLs MUST conform to
46<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
471738</a>, that is, an URL is a string in the form:
48</p>
49
50<blockquote>
51<tt>
52[ftp://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;][<i>type</i>=a|i|d]</tt>
53</blockquote>
54
55<!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
56
57<p class=name id=get>
58socket.ftp.<b>get(</b>url<b>)</b><br>
59socket.ftp.<b>get{</b><br>
60&nbsp;&nbsp;url = <i>string</i>,<br>
61&nbsp;&nbsp;type = <i>string</i>,<br>
62&nbsp;&nbsp;user = <i>string</i>,<br>
63&nbsp;&nbsp;password = <i>string</i><br>
64<b>}</b>
65</p>
66
67<p class=description>
68Downloads an URL from a FTP server.
69</p>
70
71<p class=parameters>
72The function can be called either directly with a <tt>url</tt>
73or with a <em>request table</em>.
74Fields passed explicitly in the request table override those
75present in the <tt>url</tt>.
76</p>
77
78<p class=parameters>
79The parameter <tt>type</tt> accepts values '<tt>a</tt>' (ASCII, the
80default), '<tt>i</tt>' (binary) or '<tt>d</tt>' (directory listing) and
81determines the transfer type. If <tt>&lt;path&gt;</tt> ends with a
82'<tt>/</tt>' or <tt>type</tt> is '<tt>d</tt>', a directory listing of
83<tt>&lt;path&gt;</tt> is returned. If no <tt>user</tt> is provided in the
84<tt>url</tt> or explicitly, the function tries to log in as user
85'<tt>anonymous</tt>'.
86</p>
87
88<p class=return>
89If successful, the function returns
90the file content as a string. In case of error, the function returns
91<tt>nil</tt> and an error message describing the error.
92</p>
93
94<pre class=example>
95-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
96-- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
97f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
98
99-- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
100-- go to director "pub" and retrieve directory listing of directory "lua"
101f, e = socket.ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua;type=d")
102
103-- Log as user "diego", password "nehab", on server "ftp.tecgraf.puc-rio.br",
104-- go to directory "tec/luasocket/bin" and retrieve file "luasocket.exe"
105-- (actually, fails because of wrong password, of course)
106f, e = socket.ftp.get{
107 url = "ftp://ftp.tecgraf.puc-rio.br/tec/luasocket/bin/luasocket.exe",
108 user = "diego",
109 password = "nehab",
110 type = "i"
111}
112-- f returns nil, and e returns an appropriate error message
113</pre>
114
115<!-- get_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
116
117<p class=name id=get_cb>
118socket.ftp.<b>get_cb{</b><br>
119&nbsp;&nbsp;url = <i>string</i>,<br>
120&nbsp;&nbsp;type = <i>string</i>,<br>
121&nbsp;&nbsp;content_cb = <i>receive-callback</i>,<br>
122&nbsp;&nbsp;user = <i>string</i>,<br>
123&nbsp;&nbsp;password = <i>string</i><br>
124<b>}</b>
125</p>
126
127<p class=description>
128Same as <a href="#get"><tt>get</tt></a>, but the library returns
129the content of the downloaded file to the receive callback
130<tt>content_cb</tt>.
131</p>
132
133<p class=note>
134Note: for more information on callbacks, refer to
135<a href="stream.html#stream">Streaming with callbacks</a>.
136</p>
137
138<!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class=name id=put>
141socket.ftp.<b>put(</b>url, content<b>)</b><br>
142socket.ftp.<b>put{</b><br>
143&nbsp;&nbsp;url = <i>string</i>,<br>
144&nbsp;&nbsp;content = <i>string</i>,<br>
145&nbsp;&nbsp;type = <i>string</i>,<br>
146&nbsp;&nbsp;user = <i>string</i>,<br>
147&nbsp;&nbsp;password = <i>string</i><br>
148<b>}</b>
149</p>
150
151<p class=description>
152Upload a file to a FTP server.
153</p>
154
155<p class=parameters>
156The function can be called directly with a
157<tt>url</tt> and <tt>content</tt> parameters, or with a
158<em>request table</em>.
159Values passed explicitly in the request table override those present in
160the <tt>url</tt>. The parameter <tt>type</tt> accept values
161'<tt>a</tt>' (ASCII, the default) or '<tt>i</tt>' (binary) and
162determines the transfer type. If no <tt>user</tt> is provided, the
163function tries to log in as '<tt>anonymous</tt>'.
164</p>
165
166<p class=return>
167If successful, the function returns 1. In case of error, the
168function returns <tt>nil</tt> followed by a string describing the error.
169</p>
170
171<pre class=example>
172-- Log as user "anonymous" on server "ftp.free.org" and store file
173-- "hello" with contents "hello world!", using binary mode for the transfer
174r, e = socket.ftp.put("ftp://ftp.free.org/hello;type=i", "hello world!\n")
175
176-- Does exactly the same, but logging in as diego
177r, e = socket.ftp.put{
178 url = "ftp://ftp.free.org/hello",
179 type = "i",
180 user = "diego",
181 password = "nehab",
182 content = "hello world\n"
183}
184</pre>
185</blockquote>
186
187<!-- put_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
188
189<p class=name id=put_cb>
190socket.ftp.<b>put_cb{</b><br>
191&nbsp;&nbsp;url = <i>string</i>,<br>
192&nbsp;&nbsp;type = <i>string</i>,<br>
193&nbsp;&nbsp;content_cb = <i>send-callback</i>,<br>
194&nbsp;&nbsp;user = <i>string</i>,<br>
195&nbsp;&nbsp;password = <i>string</i><br>
196<b>}</b>
197</p>
198
199<p class=description>
200Same as <a href="#put"><tt>put</tt></a>, but the
201library obtains the contents of the file to be uploaded using the send
202callback <tt>content_cb</tt>.
203</p>
204
205<p class=note>
206Note: for more information on callbacks, refer to
207<a href="stream.html#stream">Streaming with callbacks</a>.
208</p>
209
210<pre class=example>
211-- Log as user "anonymous" on server "ftp.free.org" and store file
212-- "hello" with contents of the same file in the current directory,
213-- using binary mode for the transfer
214r, e = socket.ftp.put_cb{
215 url = "ftp://ftp.free.org/hello",
216 type = "i",
217 content_cb = socket.callback.send_file(io.open("hello", "r"))
218}
219</pre>
220</blockquote>
221
222<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
223
224<div class=footer>
225<hr>
226<center>
227<p class=bar>
228<a href="home.html">home</a> &middot;
229<a href="home.html#download">download</a> &middot;
230<a href="introduction.html">introduction</a> &middot;
231<a href="reference.html">reference</a>
232</p>
233<p>
234<small>
235Last modified by Diego Nehab on <br>
236Sat Aug 9 01:00:41 PDT 2003
237</small>
238</p>
239</center>
240</div>
241
242</body>
243</html>
diff --git a/doc/http.html b/doc/http.html
new file mode 100644
index 0000000..b7469a4
--- /dev/null
+++ b/doc/http.html
@@ -0,0 +1,388 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=http>HTTP</h2>
37
38<p>
39HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange
40information between web-browsers and servers. The <tt>http.lua</tt>
41module offers support for the client side of the HTTP protocol (i.e.,
42the facilities that would be used by a web-browser implementation). The
43implementation conforms to the HTTP/1.1 standard,
44<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
452616</a>.
46</p>
47
48<p>
49The module exports functions that provide HTTP functionality in different
50levels of abstraction, from a simple <a
51href="#get"><tt>get</tt></a>, to the generic, stream oriented
52<a href="#request_cb"> <tt>request_cb</tt></a>.
53</p>
54
55<p>
56URLs must conform to
57<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
581738</a>,
59that is, an URL is a string in the form:
60</p>
61
62<blockquote>
63<pre>
64[http://][&lt;user&gt;[:&lt;password&gt;]@]&lt;host&gt;[:&lt;port&gt;][/&lt;path&gt;]
65</pre>
66</blockquote>
67
68<p>
69MIME headers are represented as a Lua table in the form:
70</p>
71
72<blockquote>
73<table summary="MIME headers in Lua table">
74<tr><td><tt>
75headers = {<br>
76&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
77&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
78&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
79</tt></td></tr>
80<tr><td align=center><tt>
81&nbsp;&nbsp;...
82</tt></td></tr>
83<tr><td><tt>
84&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
85}
86</tt></td></tr>
87</table>
88</blockquote>
89
90<p>
91Field names are case insensitive (as specified by the standard) and all
92functions work with lowercase field names.
93Field values are left unmodified.
94</p>
95
96<p class=note>
97Note: MIME headers are independent of order. Therefore, there is no problem
98in representing them in a Lua table.
99</p>
100
101<!-- http.get +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
102
103<p class=name id=get>
104socket.http.<b>get(</b>url<b>)</b><br>
105socket.http.<b>get{</b><br>
106&nbsp;&nbsp;url = <i>string</i>,<br>
107&nbsp;&nbsp;headers = <i>header-table</i>,<br>
108&nbsp;&nbsp;user = <i>string</i>,<br>
109&nbsp;&nbsp;password = <i>string</i>,<br>
110&nbsp;&nbsp;stay = <i>bool</i>,<br>
111<b>}</b>
112</p>
113
114<p class=description>
115Performs the HTTP method <tt>GET</tt>.
116</p>
117
118<p class=parameters>
119The function can be
120called either directly with a <tt>url</tt> or with a <em>request table</em>.
121The use of a request table allows complete control over the components of
122the request. Values passed explicitly as fields of the request table
123override those given by the <tt>url</tt>. For a description of the fields,
124see the <a href=#request><tt>request</tt></a> function.
125</p>
126
127<p class=return>
128The function returns the response message body, the mime headers, the
129status code and an error message (if any). In case of failure, the
130function returns all information it managed to gather.
131</p>
132
133<p class=note>
134Note: The function is trivially implemented with the use of the
135<a href="#request"><tt>request</tt></a> function.
136</p>
137
138<pre class=example>
139-- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
140-- file from "/luasocket/http.html"
141b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/luasocket/http.html")
142
143-- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
144-- "~diego/auth/index.html". Fails because authentication is needed.
145b, h, c, e = socket.http.get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
146-- b returns some useless page telling about the denied access,
147-- h returns authentication information
148-- and c returns with value 401 (Authentication Required)
149
150-- tries to connect to server "wrong.host" to retrieve "/"
151-- and fails because the host does not exist.
152b, h, c, e = socket.http.get("http://wrong.host/")
153-- b, h, c are nil, and e returns with value "host not found"
154</pre>
155
156<!-- http.post ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
157
158<p class=name id=post>
159socket.http.<b>post(</b>url, body<b>)</b><br>
160socket.http.<b>post{</b><br>
161&nbsp;&nbsp; url = <i>string</i>,<br>
162&nbsp;&nbsp; headers = <i>header-table</i>,<br>
163&nbsp;&nbsp; body = <i>string</i>,<br>
164&nbsp;&nbsp; user = <i>string</i>,<br>
165&nbsp;&nbsp; password = <i>string</i>,<br>
166&nbsp;&nbsp; stay = <i>bool</i>,<br>
167<b>}</b>
168</p>
169
170<p class=description>
171Same as <a href="#get"><tt>get</tt></a>, except
172that the <tt>POST</tt> method is used and the request
173message <tt>body</tt> is sent along with the request.
174</p>
175
176<p class=note>
177Note: This function is also trivially implemented with the use of the
178<a href="#request"><tt>request</tt></a> function.
179</p>
180
181<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
182
183<p class=name id=request>
184socket.http.<b>request{</b><br>
185&nbsp;&nbsp;method = <i>string</i>,<br>
186&nbsp;&nbsp;url = <i>string</i>,<br>
187&nbsp;&nbsp;headers = <i>header-table</i>,<br>
188&nbsp;&nbsp;body = <i>string</i>,<br>
189&nbsp;&nbsp;user = <i>string</i>,<br>
190&nbsp;&nbsp;password = <i>string</i>,<br>
191&nbsp;&nbsp;stay = <i>string</i>,<br>
192<b>}</b>
193</p>
194
195<p class=description>
196Performs the generic HTTP request using.
197</p>
198
199<p class=parameters>
200The request uses <tt>method</tt> on <tt>url</tt>
201sending the request <tt>headers</tt> and request <tt>body</tt> in the
202request message. If authentication information is provided, the function
203uses the Basic Authentication Scheme (see <a href="#authentication">note</a>)
204to retrieve the document. <tt>User</tt> and <tt>password</tt> provided
205explicitly override those given by the <tt>url</tt>. The <tt>stay</tt>
206parameter, when set to anything but <tt>nil</tt>, prevents the function
207from automatically following 301 or 302 server redirect messages.
208</p>
209
210<p class=return>
211The function returns a table with all components of the response message
212it managed to retrieve. The response table has the following form:
213</p>
214
215<blockquote><tt>
216response = {<br>
217&nbsp;&nbsp;body = <i>string</i>,<br>
218&nbsp;&nbsp;headers = <i>header-table</i>,<br>
219&nbsp;&nbsp;status = <i>string</i>,<br>
220&nbsp;&nbsp;code = <i>number</i>,<br>
221&nbsp;&nbsp;error = <i>string</i><br>
222}
223</tt></blockquote>
224
225<p class=return>
226Even when there was failure (URL not found, for example), the
227function may succeed retrieving a message body (a web page informing the
228URL was not found or some other useless page). To make sure the
229operation was successful, check the returned status <tt>code</tt>. For
230a list of the possible values and their meanings, refer to <a
231href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
2322616</a>.
233</p>
234
235<pre class=example>
236-- Requests information about a document, without downloading it.
237-- Useful, for example, if you want to display a download gauge and need
238-- to know the size of the document in advance
239response = socket.http.request {
240 method = "HEAD",
241 url = "http://www.tecgraf.puc-rio.br/~diego"
242}
243-- Would return the following headers:
244-- response.headers = {
245-- date = "Tue, 18 Sep 2001 20:42:21 GMT",
246-- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)",
247-- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
248-- ["content-length"] = 15652,
249-- ["connection"] = "close",
250-- ["content-Type"] = "text/html"
251-- }
252</pre>
253</blockquote>
254
255<p class=note id=authentication>
256Note: Some URLs are protected by their
257servers from anonymous download. For those URLs, the server must receive
258some sort of authentication along with the request or it will deny
259download and return status "401&nbsp;Authentication Required".
260</p>
261
262<p class=note>
263The HTTP/1.1 standard defines two authentication methods: the Basic
264Authentication Scheme and the Digest Authentication Scheme, both
265explained in detail in
266<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2068.txt">RFC 2068</a>.
267</p>
268
269<p class=note>The Basic Authentication Scheme sends
270<tt>&lt;user&gt;</tt> and
271<tt>&lt;password&gt;</tt> unencrypted to the server and is therefore
272considered unsafe. Unfortunately, by the time of this implementation,
273the wide majority of servers and browsers support the Basic Scheme only.
274Therefore, this is the method used by the toolkit whenever
275authentication is required.
276</p>
277
278<pre class=example>
279-- Connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
280-- "~diego/auth/index.html", using the provided name and password to
281-- authenticate the request
282response = socket.http.request{
283 url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
284 user = "diego",
285 password = "password"
286}
287
288-- Alternatively, one could fill the appropriate header and authenticate
289-- the request directly.
290headers = {
291 authentication = "Basic " .. socket.code.base64("diego:password")
292}
293response = socket.http.request {
294 url = "http://www.tecgraf.puc-rio.br/~diego/auth/index.html",
295 headers = headers
296}
297</pre>
298
299<!-- request_cb +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
300
301<p class=name id=request_cb>
302socket.http.<b>request_cb(</b>request, response<b>)</b>
303</p>
304
305<p class=description>
306Performs the generic HTTP request.
307</p>
308
309<p class=parameters>
310The function receives two tables as parameters. The <tt>request</tt> table
311provides information about the request:
312</p>
313
314<blockquote><tt>
315request = {<br>
316&nbsp;&nbsp;method = <i>string</i>,<br>
317&nbsp;&nbsp;url = <i>string</i>,<br>
318&nbsp;&nbsp;headers = <i>header-table</i>,<br>
319&nbsp;&nbsp;body_cb = <i>send-callback</i>,<br>
320&nbsp;&nbsp;user = <i>string</i>,<br>
321&nbsp;&nbsp;password = <i>string</i>,<br>
322&nbsp;&nbsp;stay = <i>string</i>,<br>
323}</tt>
324</blockquote>
325
326<p class=parameters>
327The function uses the HTTP method specified in
328<tt>request.method</tt> on the URL <tt>request.url</tt>,
329sending <tt>request.headers</tt> along with the request. The request
330message body is sent via the send callback <tt>request.body_cb</tt>.
331If authentication information is provided, the function uses the Basic
332Authentication Scheme (see <a href="#authentication">note</a>) to
333retrieve the document. <tt>Request.user</tt> and
334<tt>request.password</tt> override those given by the
335<tt>request.url</tt>. The <tt>request.stay</tt> parameter, when set to
336anything but <tt>nil</tt>, prevents the function from automatically
337following 301 or 302 server redirect messages.
338</p>
339
340<p class=parameters>
341The <tt>response</tt> table specifies information about the desired
342response:
343</p>
344
345<blockquote><tt>
346response = {<br>
347&nbsp;&nbsp;body_cb = <i>receive-callback</i><br>
348}</tt>
349</blockquote>
350
351<p class=return>
352The function returns the same response table as that returned by the
353<tt>socket.http.request</tt> function, except the response message body is
354returned to the receive callback given by the
355<tt>response.body_cb</tt> field.
356</p>
357
358<p class=note>
359Note: For more information on callbacks, please refer to
360<a href="stream.html#stream">Streaming with callbacks</a>.
361</p>
362
363<p class=note>
364Note: Method names are case <em>sensitive</em>
365</p>
366
367<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
368
369<div class=footer>
370<hr>
371<center>
372<p class=bar>
373<a href="home.html">home</a> &middot;
374<a href="home.html#download">download</a> &middot;
375<a href="introduction.html">introduction</a> &middot;
376<a href="reference.html">reference</a>
377</p>
378<p>
379<small>
380Last modified by Diego Nehab on <br>
381Sat Aug 9 01:00:41 PDT 2003
382</small>
383</p>
384</center>
385</div>
386
387</body>
388</html>
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..46642d2
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,212 @@
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<title>LuaSocket: Network support for the Lua language </title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=whatis>What is LuaSocket?</h2>
37
38<p>
39LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library
40that is composed by two parts: a C layer that provides support for the TCP
41and UDP transport layers, and a set of Lua modules that add support for
42the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
43downloading files) protocols.
44</p>
45
46<p>
47Network support has been implemented so that it is both efficient and
48simple to use. LuaSocket can be used by any Lua application once it has
49been properly linked with and initialized by the interpreter running the
50Lua application. The code has been tested and runs well on several Windows
51and Unix platforms.
52</p>
53
54<p>
55The library is available under the same
56<a href="http://www.lua.org/copyright.html">
57terms and conditions</a> as the Lua language, the MIT license. The idea is
58that if you can use Lua in a project, you should also be able to use
59LuaSocket.
60</p>
61
62<p>
63Copyright &copy; 1999-2003 Tecgraf/PUC-Rio. All rights reserved. <br>
64Author: <A href="http://www.cs.princeton.edu/~diego">Diego Nehab</a>
65</p>
66
67<!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
68
69<h2 id=down>Download</h2>
70
71<p>
72LuaSocket version 2.0 alpha is now available for download! It is
73compatible with Lua&nbsp;5.0 and has been tested on
74Windows&nbsp;XP, Linux, and Mac OS X.
75</p>
76
77<p>
78The library can be downloaded in source code from the following links:
79</p>
80
81<blockquote>
82<p>
83<a href="luasocket-2.0-alpha.tar.gz">luasocket-2.0-alpha.tar.gz</a> <br>
84<a href="luasocket-2.0-alpha.zip">luasocket-2.0-alpha.zip</a>
85</p>
86</blockquote>
87
88<p>
89Besides the full C and Lua source code for the library, the distribution
90contains several examples, this user's manual and the test procedures.
91</p>
92
93<p>
94I am also providing a Windows binary for those that want to give
95LuaSocket a quick try:
96</p>
97
98<blockquote>
99<p>
100<a href="luasocket-2.0.exe">luasocket-2.0.exe</a>
101</p>
102</blockquote>
103
104<p>
105This binary has been compiled with the <tt>LUASOCKET_DEBUG</tt>
106option, and should be able to run the automatic test procedures.
107</p>
108
109<!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
110
111<h2 id=new>What's New</h2>
112
113<p>
114Most of the changes for 2.0 happened in the C layer, which
115has been almost completely rewritten. The code has been ported to Lua 5.0
116and greatly improved. There have also been some API changes
117that made the interface simpler and more consistent. Here are some of
118the changes that made it into version 2.0:
119</p>
120
121<ul>
122<li> Major C code rewrite. Code is modular and extensible. Hopefully, next
123 versions will include code for local domain sockets, file descriptors,
124 pipes (on Unix) and named pipes (on windows) as a bonus;
125
126<li> Following the Lua 5.0 trend, all functions provided by the library are
127 in the namespace <tt>socket</tt>. Functions such as
128 send/receive/timeout/close etc do not exist anymore as stand-alone
129 functions. They are now only available as methods of the appropriate
130 objects;
131
132<li> All functions return a non-nil value as first return value if successful.
133 All functions return whatever could be retrieved followed by error message
134 in case of error. The best way to check for errors is to check for the
135 presence of an error message;
136
137<li> UDP connected sockets can break association with peer by calling
138 <tt>setpeername</tt> with address '<tt>*</tt>';
139
140<li> TCP has been changed to become more uniform. First create an object,
141 then connect or bind if needed, and finally use I/O functions. The
142 <tt>socket.connect</tt> and <tt>socket.bind</tt> functions are still
143 provided for simplicity, but they just call <tt>socket.tcp</tt> followed
144 by the <tt>connect</tt> or <tt>bind</tt> methods;
145
146<li> Better error messages and parameter checking;
147
148<li> <tt>socket.sleep</tt> and <tt>socket.time</tt> are now part of the
149 library and are supported. They used to be available only when
150 LUASOCKET_DEBUG was defined, but it turns out they might be useful for
151 applications;
152
153<li> Socket options interface has been improved and TCP objects also
154 support socket options.
155
156</ul>
157
158<!-- incompatible +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
159
160<h3 id=incompatible>Incompatibilities with previous versions</h3>
161
162<ul>
163<li> The introduction of namespaces affects all programs that use LuaSocket,
164specially code that relies on global functions. These are no longer
165available. Note that even the support modules (<tt>http</tt>, <tt>smtp</tt>
166etc) have been moved to the namespace (i.e. <tt>socket.http</tt>,
167<tt>socket.smtp</tt> etc);
168
169<li> WARNING: The new <tt>send</tt>,
170<tt>sendto</tt>, <tt>setpeername</tt> and <tt>setsockname</tt>,
171<tt>ftp.put</tt>, <tt>ftp.put_cb</tt> return convention WILL break old code;
172
173<li> Interface to options has changed;
174
175<li> <tt>socket.select</tt> refuses tables that have anything that is not
176an object from the group <tt>select{able}</tt>. This includes even the
177'<tt>n</tt>' field. Silently ignoring objects was a source of bugs for Lua
178programs.
179</ul>
180
181<!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
182
183<h2 id=old>Old Versions</h2>
184
185<p>
186All previous versions of the LuaSocket library can be downloaded
187<a href="http://www.tecgraf.puc-rio.br/luasocket/old">here</a>. Although
188these versions are no longer supported, they are still available for
189those that have compatibility issues.
190</p>
191
192<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
193
194<div class=footer>
195<hr>
196<center>
197<p class=bar>
198<a href="home.html#down">download</a> &middot;
199<a href="introduction.html">introduction</a> &middot;
200<a href="reference.html">reference</a>
201</p>
202<p>
203<small>
204Last modified by Diego Nehab on <br>
205Sun Aug 10 01:36:26 PDT 2003
206</small>
207</p>
208</center>
209</div>
210
211</body>
212</html>
diff --git a/doc/introduction.html b/doc/introduction.html
new file mode 100644
index 0000000..7adf45b
--- /dev/null
+++ b/doc/introduction.html
@@ -0,0 +1,328 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2>Introduction</h2>
37
38<p>
39Communication in LuaSocket is performed via I/O objects. These can
40represent different network domains. Currently, support is
41provided for TCP and UDP, but there is work in progress to implement SSL,
42Local Domain, Pipes, File Descriptors etc. I/O objects provide a standard
43interface to I/O across different domains and operating systems.
44LuaSocket&nbsp;2.0 has been rewritten from scratch to simplify the future
45addition new domains.
46</p>
47
48<p>
49The LuaSocket API was designed with two goals in mind. First, users
50experienced with the C API to sockets should feel comfortable using LuaSocket.
51Second, the simplicity and the feel of the Lua language should be
52preserved. 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.
53</p>
54
55<p>
56One of the simplifications is the timeout control
57mechanism. As in C, all I/O operations are blocking by default. For
58example, the <a href=tcp.html#send><tt>send</tt></a>,
59<a href=tcp.html#receive><tt>receive</tt></a> and
60<a href=tcp.html#accept><tt>accept</tt></a> methods
61of the TCP domain will block the caller application until
62the operation is completed (if ever!). However, with a call to the
63<a href=tcp.html#settimeout><tt>settimeout</tt></a>
64method, an application can specify upper limits on
65the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
66the time LuaSocket can internally be blocked by any OS call (the
67"<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
68call might perform several OS calls, so that the two timeout values are
69<em>not</em> equivalent.
70</p>
71
72<p>
73Another important difference is the receive pattern capability.
74Applications can read data from stream domains (such as TCP)
75line by line, block by block, or until the connection is closed.
76All I/O reads are buffered and the performance differences between
77different receive patterns are negligible.
78</p>
79
80<p>
81Finally, the host name resolution is transparent, meaning that most
82functions and methods accept both IP addresses and host names. In case a
83host name is given, the library queries the system's resolver and
84tries the main returned IP address. Note that direct use of IP addresses
85is more efficient, of course. The
86<a href=dns.html#toip><tt>toip</tt></a>
87and <a href=dns.html#tohostname><tt>tohostname</tt></a>
88functions from the DNS module are provided to convert between host names and IP addresses.
89</p>
90
91<p>
92Previous versions of LuaSocket provided global functions for operating on
93I/O objects. To give the library a Lua 5.0 feel, these have been eliminated
94from LuaSocket 2.0. I/O operations are only available as methods of the
95corresponding I/O objects. Naturally, different I/O objects accept
96different operations. The core functionality for TCP and UDP objects is
97introduced in the following sections, following a few words about
98initialization.
99</p>
100
101<!-- initializing +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
102
103<h3>Initializing the library</h3>
104
105<p>
106Beginning with version 2.0 and following the Lua 5.0 trend, all LuaSocket
107functionality is defined inside a table (or rather a namespace) stored with
108the global name <tt>socket</tt>. To have this table created and its
109contents made available to a Lua script, the interpreter running the script
110must be linked to the LuaSocket library, and to whatever libraries the
111host OS requires for network access (Windows requires ws2_32.lib, for
112instance). LuaSocket is initialized in the
113Lua state given as the argument to the function
114<tt>luaopen_socket</tt>, the only C function exported by the library.
115After initialization, the scripts are free to use all LuaSocket API.
116</p>
117
118<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
119
120<h3 id=tcp>TCP</h3>
121
122<p>
123TCP (Transfer Control Protocol) is reliable stream protocol. In other
124words, applications communicating through TCP can send and receive data as
125an error free stream of bytes. Data is split in one end and
126reassembled transparently on the other end. There are no boundaries in
127the data transfers. The library allows users to read data from the
128sockets in several different granularity: patterns are available for
129lines, arbitrary sized blocks or "read up to connection closed", all with
130good performance.
131</p>
132
133<p>
134The library distinguishes three types of TCP sockets: master, client and server sockets.
135</p>
136
137<p>
138Master sockets are newly created TCP sockets returned by the function
139<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
140transformed into a server socket
141after it is associated with a <em>local</em> address by a call to the
142<a href=tcp.html#bind><tt>bind</tt></a> method. Conversely, it
143can be changed into a client socket with the method
144<a href=tcp.html#connect><tt>connect</tt></a>,
145that associates it with a <em>remote</em> address.
146</p>
147
148<p>
149On server sockets, applications can use the
150<a href=tcp.html#accept><tt>accept</tt></a> method
151to wait for a client connection. Once a connection is established, a
152client socket object is returned representing this connection. The
153other methods available for server socket objects are
154<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
155<a href=tcp.html#setoption><tt>setoption</tt></a>,
156<a href=tcp.html#settimeout><tt>settimeout</tt></a> and
157<a href=tcp.html#close><tt>close</tt></a>.
158</p>
159
160<p>
161Client sockets are used to exchange data between two applications over
162the Internet. Applications can call the methods
163<a href=tcp.html#send><tt>send</tt></a> and
164<a href=tcp.html#receive><tt>receive</tt></a>
165to send and receive data. The other methods
166available for client socket objects are
167<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
168<a href=tcp.html#getpeername><tt>getpeername</tt></a>,
169<a href=tcp.html#setoption><tt>setoption</tt></a>,
170<a href=tcp.html#settimeout><tt>settimeout</tt></a> and
171<a href=tcp.html#close><tt>close</tt></a>.
172</p>
173
174<p>
175Example:
176</p>
177<blockquote>
178<p>
179A simple echo server, using LuaSocket. The program binds to an ephemeral
180port (one that is chosen by the operating system) on the local host and
181awaits client connections on that port. When a connection is established,
182the program reads a line from the remote end and sends it back, closing
183the connection immediately after. You can test it using the telnet
184program.
185</p>
186
187<pre class=example>
188-- create a new TCP object
189server, err = socket.tcp()
190assert(server, err)
191-- bind it to the local host, at any port
192ret, err = server:bind("*", 0)
193assert(ret, err)
194-- find out which port the OS chose for us
195ip, port = server:getsockname()
196-- print a message informing what's up
197print("Please telnet to localhost on port " .. port)
198print("After connecting, you have 10s to enter a line to be echoed")
199-- loop forever waiting for clients
200while 1 do
201 -- wait for a conection from any client
202 client, err = server:accept()
203 -- make sure we don't block waiting for this client's line
204 client:settimeout(10)
205 -- receive the line
206 line, err = client:receive()
207 -- if there was no error, send it back to the client
208 if not err then
209 client:send(line .. "\n")
210 end
211 -- done with client, close the object
212 client:close()
213end
214</pre>
215</blockquote>
216
217<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
218
219<h3 id=udp>UDP</h3>
220
221<p>
222UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
223other words, applications communicating through UDP send and receive
224data as independent blocks, which are not guaranteed to reach the other
225end. Even when they do reach the other end, they are not guaranteed to be
226error free. Data transfers are atomic, one datagram at a time. Reading
227only part of a datagram discards the rest, so that the following read
228operation will act on the next datagram. The advantages are in
229simplicity (no connection setup) and performance (no error checking or
230error correction).
231</p>
232
233<p>
234An UDP socket object is created by the
235<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
236sockets do not need to be connected before use. The method
237<a href=udp.html#sendto><tt>sendto</tt></a>
238can be used immediately after creation to
239send a datagram to IP address and port. Host names are not allowed
240because performing name resolution for each packet would be forbiddingly
241slow. Methods
242<a href=udp.html#receive><tt>receive</tt></a> and
243<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
244can be used to retrieve datagrams, the latter returning the IP and port of
245the sender as extra return values (thus being slightly less
246efficient).
247</p>
248
249<p>
250When communication is performed repeatedly with a single peer, an
251application should call the
252<a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
253permanent partner. Methods
254<a href=udp.html#sendto><tt>sendto</tt></a> and
255<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
256can no longer be used, but the method
257<a href=udp.html#send><tt>send</tt></a> can be used to send data
258directly to the peer, and the method
259<a href=udp.html#receive><tt>receive</tt></a>
260will only return datagrams originating
261from that peer. There is about 30% performance gain due to this practice.
262</p>
263
264<p>
265To associate an UDP socket with a local address, an application calls the
266<a href=udp.html#setsockname><tt>setsockname</tt></a>
267method <em>before</em> sending any datagrams. Otherwise, the socket is
268automatically bound to an ephemeral address before the first data
269transmission and once bound the local address cannot be changed.
270The other methods available for UDP sockets are
271<a href=udp.html#getpeername><tt>getpeername</tt></a>,
272<a href=udp.html#getsockname><tt>getsockname</tt></a>,
273<a href=udp.html#settimeout><tt>settimeout</tt></a>,
274<a href=udp.html#setoption><tt>setoption</tt></a> and
275<a href=udp.html#close><tt>close</tt></a>.
276</p>
277
278<p>
279Example:
280</p>
281<blockquote>
282<p>
283A simple daytime client, using LuaSocket. The program connects to a remote
284server and tries to retrieve the daytime, printing the answer it got or an
285error message.
286</p>
287
288<pre class=example>
289host = "localhost" -- change here to the host you want to contact
290port = port or 13
291-- convert host name to ip address
292ip, err = socket.toip(host)
293assert(ip, err)
294-- create a new UDP object
295udp = socket.udp()
296-- contact daytime host
297nsent, err = udp:sendto("anything", ip, port)
298assert(not err, err)
299-- retrieve the answer
300dgram, err = udp:receive()
301assert(dgram, err)
302-- display to user
303print(dgram)
304</pre>
305</blockquote>
306
307<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
308
309<div class=footer>
310<hr>
311<center>
312<p class=bar>
313<a href="home.html">home</a> &middot;
314<a href="home.html#down">download</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>
321Sat Aug 9 01:00:41 PDT 2003
322</small>
323</p>
324</center>
325</div>
326
327</body>
328</html>
diff --git a/doc/luasocket.png b/doc/luasocket.png
new file mode 100644
index 0000000..d24a954
--- /dev/null
+++ b/doc/luasocket.png
Binary files differ
diff --git a/doc/reference.css b/doc/reference.css
new file mode 100644
index 0000000..4f17046
--- /dev/null
+++ b/doc/reference.css
@@ -0,0 +1,40 @@
1body {
2 margin-left: 1em;
3 margin-right: 1em;
4}
5
6body > * { margin-left: 1em; }
7
8div.header, div.footer { margin-left: 0em; }
9hr, h1, h2, h3, h4 { margin-left: 0em; }
10p.name { margin-left: 0em; }
11
12h2:first-letter, h2:first-letter, h3:first-letter { color: #00007f; }
13
14blockquote { margin-left: 3em; }
15
16a[href] { color: #00007f; }
17
18p.name {
19 font-size: large;
20 font-family: monospace;
21 padding-top: 1em;
22}
23
24pre.example {
25 background: #ccc;
26 font-size: small;
27 padding: 1em;
28}
29
30hr {
31 background: #00007f;
32 border: 0px;
33 height: 1px;
34}
35
36ul { list-style-type: disc; }
37
38table.index { border: 1px #00007f; }
39table.index td { text-align: left; vertical-align: top; }
40table.index ul { padding-top: 0em; margin-top: 0em; }
diff --git a/doc/reference.html b/doc/reference.html
new file mode 100644
index 0000000..39f6437
--- /dev/null
+++ b/doc/reference.html
@@ -0,0 +1,209 @@
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<title>LuaSocket: Network support for the Lua language </title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- reference +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2>Reference</h2>
37
38<!-- tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<table summary="TCP Index" class=index width=100%>
41<colgroup> <col width="50%"> <col width="50%"> </colgroup>
42<tr>
43<td><ul>
44<li><a href="tcp.html">TCP (socket.tcp)</a>
45 <ul>
46 <li><a href="tcp.html#accept">accept</a>
47 <li><a href="tcp.html#bind">bind</a>
48 <li><a href="tcp.html#close">close</a>
49 <li><a href="tcp.html#connect">connect</a>
50 <li><a href="tcp.html#getpeername">getpeername</a>
51 </ul>
52</ul></td>
53<td valign=top><ul>
54 <li><a href="tcp.html#getsockname">getsockname</a>
55 <li><a href="tcp.html#receive">receive</a>
56 <li><a href="tcp.html#send">send</a>
57 <li><a href="tcp.html#setoption">setoption</a>
58 <li><a href="tcp.html#settimeout">settimeout</a>
59</ul></td>
60</tr>
61</table>
62
63<hr>
64
65<!-- udp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
66
67<table summary="UDP Index" class=index width=100%>
68<colgroup> <col width="50%"> <col width="50%"> </colgroup>
69<tr>
70<td><ul>
71<li><a href="udp.html">UDP (socket.udp)</a>
72 <ul>
73 <li><a href="udp.html#close">close</a>
74 <li><a href="udp.html#getpeername">getpeername</a>
75 <li><a href="udp.html#getsockname">getsockname</a>
76 <li><a href="udp.html#receive">receive</a>
77 <li><a href="udp.html#receivefrom">receivefrom</a>
78 </ul>
79</ul></td>
80<td><ul>
81 <li><a href="udp.html#send">send</a>
82 <li><a href="udp.html#sendto">sendto</a>
83 <li><a href="udp.html#setpeername">setpeername</a>
84 <li><a href="udp.html#setsockname">setsockname</a>
85 <li><a href="udp.html#setoption">setoption</a>
86 <li><a href="udp.html#settimeout">settimeout</a>
87</ul></td>
88</tr>
89</table>
90
91<hr>
92
93<!-- http & ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
94
95<table summary="HTTP and FTP Index" class=index width=100% rules=cols>
96<colgroup> <col width="50%"> <col width="50%"> </colgroup>
97<tr>
98<td valign=top><ul>
99<li><a href="http.html">HTTP (socket.http)</a>
100 <ul>
101 <li><a href="http.html#get">get</a>
102 <li><a href="http.html#post">post</a>
103 <li><a href="http.html#request">request</a>
104 <li><a href="http.html#request_cb">request_cb</a>
105 </ul>
106</ul></td>
107<td valign=top><ul>
108<li><a href="ftp.html">FTP (socket.ftp)</a>
109 <ul>
110 <li><a href="ftp.html#get">get</a>
111 <li><a href="ftp.html#get_cb">get_cb</a>
112 <li><a href="ftp.html#put">put</a>
113 <li><a href="ftp.html#put_cb">put_cb</a>
114 </ul>
115</ul></td>
116</tr>
117</table>
118
119<hr>
120
121<!-- http & ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
122
123<table summary="Streaming Index" class=index width=100%>
124<colgroup> <col width="50%"> <col width="50%"> </colgroup>
125<tr><td valign=top><ul>
126<li><a href="stream.html">Streaming with Callbacks</a>
127 <ul>
128 <li><a href="stream.html#receive_cb">receive_cb</a>
129 <li><a href="stream.html#send_cb">send_cb</a>
130 </ul>
131</ul></td></tr>
132</table>
133
134<hr>
135
136<!-- smtp & dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
137
138<table summary="SMTP and DNS Index" class=index width=100% rules=cols>
139<colgroup> <col width="50%"> <col width="50%"> </colgroup>
140<tr>
141<td><ul>
142<li><a href="smtp.html">SMTP (socket.smtp)</a>
143 <ul>
144 <li> <a href="mod.html#mail">mail</a>
145 </ul>
146</ul></td>
147<td><ul>
148<li><a href="dns.html">DNS services (socket.dns)</a>
149 <ul>
150 <li><a href="dns.html#toip">toip</a>
151 <li><a href="dns.html#tohostname">tohostname</a>
152 </ul>
153</ul></td>
154</tr>
155</table>
156
157<hr>
158
159<!-- url & code ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
160
161<table summary="URL and Code Index" class=index width=100% rules=cols>
162<colgroup> <col width="50%"> <col width="50%"> </colgroup>
163<tr>
164<td valign=top><ul>
165<li><a href="url.html">URL (socket.url) </a>
166 <ul>
167 <li> <a href="url.html#absolute">absolute</a>
168 <li> <a href="url.html#build">build</a>
169 <li> <a href="url.html#build_path">build_path</a>
170 <li> <a href="url.html#parse">parse</a>
171 <li> <a href="url.html#parse_path">parse_path</a>
172 </ul>
173</ul></td>
174<td valign=top><ul>
175<li> <a href="code.html">Code (socket.code) </a>
176 <ul>
177 <li> <a href="code.html#base64">base64</a>
178 <li> <a href="code.html#unbase64">unbase64</a>
179 <li> <a href="code.html#escape">escape</a>
180 <li> <a href="code.html#unescape">unescape</a>
181 <li> <a href="code.html#hexa">hexa</a>
182 <li> <a href="code.html#unhexa">unhexa</a>
183 </ul>
184</ul></td>
185</tr>
186</table>
187
188<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
189
190<div class=footer>
191<hr>
192<center>
193<p class=bar>
194<a href="home.html">home</a> &middot;
195<a href="home.html#down">download</a> &middot;
196<a href="introduction.html">introduction</a> &middot;
197<a href="reference.html">reference</a>
198</p>
199<p>
200<small>
201Last modified by Diego Nehab on <br>
202Thu Sep 27 16:18:27 EST 2001
203</small>
204</p>
205</center>
206</div>
207
208</body>
209</html>
diff --git a/doc/smtp.html b/doc/smtp.html
new file mode 100644
index 0000000..3a30a07
--- /dev/null
+++ b/doc/smtp.html
@@ -0,0 +1,228 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=smtp>SMTP</h2>
37
38<p>
39The module <tt>smtp.lua</tt> provides functionality to send e-mail
40messages. The implementation conforms to the Simple Mail Transfer Protocol,
41<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>.
42The other RFC of interest in this implementation is
43<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>,
44which governs the Internet Message Format.
45
46</p>
47
48<p>
49MIME headers are represented as a Lua table in the form:
50</p>
51
52<blockquote>
53<table summary="MIME headers in Lua table">
54<tr><td><tt>
55headers = {<br>
56&nbsp;&nbsp;field-1-name = <i>field-1-value</i>,<br>
57&nbsp;&nbsp;field-2-name = <i>field-2-value</i>,<br>
58&nbsp;&nbsp;field-3-name = <i>field-3-value</i>,
59</tt></td></tr>
60<tr><td align=center><tt>
61&nbsp;&nbsp;...
62</tt></td></tr>
63<tr><td><tt>
64&nbsp;&nbsp;field-n-name = <i>field-n-value</i><br>
65}
66</tt></td></tr>
67</table>
68</blockquote>
69
70<p>
71Field names are case insensitive (as specified by the standard) and all
72functions work with lowercase field names.
73Field values are left unmodified.
74</p>
75
76<p class=note>
77Note: MIME headers are independent of order. Therefore, there is no problem
78in representing them in a Lua table.
79</p>
80
81<!-- mail +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
82
83<p class=name id=mail>
84socket.smtp.<b>mail{</b><br>
85&nbsp;&nbsp;from = <i>string</i>,<br>
86&nbsp;&nbsp;rcpt = <i>string</i> or <i>string-table</i>,<br>
87&nbsp;&nbsp;body = <i>string</i>,<br>
88&nbsp;&nbsp;headers = <i>headers-table</i>,<br>
89&nbsp;&nbsp;server = <i>string</i><br>
90<b>}</b>
91</p>
92
93<p class=description>
94Sends a message to a recipient list.
95</p>
96
97<p class=parameters>
98<tt>Rcpt</tt> is a Lua table with one entry for each recipient, or a string
99in case there is just one recipient.
100The sender is given by the e-mail address <tt>from</tt>.
101The message is composed by the optional MIME Headers <tt>headers</tt>
102and text <tt>body</tt>. The message is sent using the server
103<tt>server</tt>.
104</p>
105
106<p class=return>
107If successful, the function returns 1. Otherwise, the function returns
108<tt>nil</tt> followed by an error message.
109</p>
110
111<p class=note>
112Big note: There is a good deal of misconception with the use of the
113destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>',
114and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a
115'<tt>Bcc</tt>' header to your messages because it will probably do the
116exact opposite of what you expect.
117</p>
118
119<p class=note>
120Only recipients specified in the recipient list will receive a copy of the
121message. Each recipient of an SMTP mail message receives a copy of the
122message body along with the headers, and nothing more. The headers are
123considered as part of the message. The list of recipients is <em>not</em>
124part of the message.
125</p>
126
127<p class=note>
128<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>
129has two <em>important and short</em> sections, "3.6.3. Destination address
130fields" and "5. Security considerations", explaining the proper
131use of these headers. Here is a summary of what it says:
132</p>
133
134<ul>
135<li> <tt>To</tt>: contains the address(es) of the primary recipient(s)
136of the message;
137<li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of
138making a copy on a typewriter using carbon paper) contains the
139addresses of others who are to receive the message, though the
140content of the message may not be directed at them;
141<li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon
142Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message.
143</ul>
144
145<p class=note>
146The LuaSocket <tt>mail</tt> function does not interpret the headers you
147pass to, but it gives you full control over what is sent and to whom
148it is sent:
149</p>
150<ul>
151<li> If someone is to receive the message, the e-mail address <em>has</em>
152to be in the recipient list. This is the only parameter that controls who
153gets a copy of the message;
154<li> If there are multiple recipients, none of them will automatically
155know that someone else got that message. That is, the default behavior is
156similar to the <tt>Bcc</tt> field of popular e-mail clients;
157<li> It is up to you to add the <tt>To</tt> header with the list of primary
158recipients so that other recipients can see it;
159<li> It is also up to you to add the <tt>Cc</tt> header with the
160list of additional recipients so that everyone else sees it;
161<li> Adding a header <tt>Bcc</tt> is nonsense, unless it is
162empty. Otherwise, everyone receiving the message will see it and that is
163exactly what you <em>don't</em> want to happen!
164</ul>
165
166<p class=note>
167I hope this clarifies the issue. Otherwise, please refer to
168<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2821.txt">RFC 2821</a>
169and
170<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2822.txt">RFC 2822</a>.
171</p>
172
173<pre class=example>
174-- Connects to server "localhost" and sends a message to users
175-- "fulano@tecgraf.puc-rio.br", "beltrano@tecgraf.puc-rio.br",
176-- and "sicrano@tecgraf.puc-rio.br".
177-- Note that "fulano" is the primary recipient, "beltrano" receives a
178-- carbon copy and neither of them knows that "sicrano" received a blind
179-- carbon copy of the message.
180headers = {
181 to = "fulano@tecgraf.puc-rio.br",
182 cc = "beltrano@tecgraf.puc-rio.br",
183 subject = "LuaSocket test message"
184}
185
186from = "luasocket@tecgraf.puc-rio.br"
187
188rcpt = {
189 "fulano@tecgraf.puc-rio.br",
190 "beltrano@tecgraf.puc-rio.br",
191 "sicrano@tecgraf.puc-rio.br"
192}
193
194body = "This is a test message. Please ignore."
195
196server = "localhost"
197
198r, e = socket.smtp.mail{
199 from = from,
200 rcpt = rcpt,
201 headers = headers,
202 body = body,
203 server = server
204}
205</pre>
206
207<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
208
209<div class=footer>
210<hr>
211<center>
212<p class=bar>
213<a href="home.html">home</a> &middot;
214<a href="home.html#down">download</a> &middot;
215<a href="introduction.html">introduction</a> &middot;
216<a href="reference.html">reference</a>
217</p>
218<p>
219<small>
220Last modified by Diego Nehab on <br>
221Sat Aug 9 01:00:41 PDT 2003
222</small>
223</p>
224</center>
225</div>
226
227</body>
228</html>
diff --git a/doc/stream.html b/doc/stream.html
new file mode 100644
index 0000000..296ca2e
--- /dev/null
+++ b/doc/stream.html
@@ -0,0 +1,173 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=stream>Streaming with Callbacks</h2>
37
38<p>
39HTTP and FTP transfers sometimes involve large amounts of information.
40Sometimes an application needs to generate outgoing data in real time,
41or needs to process incoming information as it is being received. To
42address these problems, LuaSocket allows HTTP message bodies and FTP
43file contents to be received or sent through the callback mechanism
44outlined below.
45</p>
46
47<p>
48Instead of returning the entire contents of a FTP file or HTTP message
49body as strings to the Lua application, the library allows the user to
50provide a <em>receive callback</em> that will be called with successive
51chunks of data, as the data becomes available. Conversely, the <em>send
52callbacks</em> should be used when data needed by LuaSocket
53is generated incrementally by the application.
54</p>
55
56<!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
57
58<p class=name id=receive_cb>
59<b>receive_cb(</b>chunk, err<b>)</b>
60</p>
61
62<p class=description>
63The callback provided by the user will be repeatedly called by the
64library whenever new data is available. Each time it is called, the
65callback receives successive chunks of downloaded data.
66</p>
67
68<p class=parameters>
69<tt>Chunk</tt> contains the current chunk of data.
70When the transmission is over, the function is called with an
71empty string (i.e.&nbsp;<tt>""</tt>) as the <tt>chunk</tt>. If an error occurs, the
72function receives <tt>nil</tt> as <tt>chunk</tt> and an error message as
73<tt>err</tt>.
74</p>
75
76<p class=return>
77The callback can abort transmission by returning
78<tt>nil</tt> as its first return value. In that case, it can also return
79an error message. Any non-<tt>nil</tt> return value proceeds with the
80transmission.
81</p>
82
83<pre class=example>
84-- The implementation of socket.callback.receive_concat
85function Public.receive_concat(concat)
86 concat = concat or socket.concat.create()
87 local callback = function(chunk, err)
88 -- if not finished, add chunk
89 if chunk and chunk ~= "" then
90 concat:addstring(chunk)
91 return 1
92 end
93 end
94 return callback, concat
95end
96</pre>
97
98<!-- send_cb ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
99
100<p class=name>
101<b>send_cb()</b>
102</p>
103
104<p class=description>
105The callback provided by the user will be repeatedly called whenever the
106library needs more data to be sent.
107</p>
108
109<p class=return>
110Each time the callback is called, it
111should return the next part of the information the library is expecting,
112followed by the total number of bytes to be sent.
113The callback can abort
114the process at any time by returning <tt>nil</tt> followed by an
115optional error message.
116</p>
117
118
119<p class=note>
120Note: The need for the second return value comes from the fact that, with
121the HTTP protocol for instance, the library needs to know in advance the
122total number of bytes that will be sent.
123</p>
124
125<pre class=example>
126-- The implementation of socket.callback.send_file
127function Public.send_file(file)
128 local callback
129 -- if successfull, return the callback that reads from the file
130 if file then
131 -- get total size
132 local size = file:seek("end")
133 -- go back to start of file
134 file:seek("set")
135 callback = function()
136 -- send next block of data
137 local chunk = file:read(Public.BLOCKSIZE)
138 if not chunk then file:close() end
139 return chunk, size
140 end
141 -- else, return a callback that just aborts the transfer
142 else
143 callback = function()
144 -- just abort
145 return nil, "unable to open file"
146 end
147 end
148 return callback, file
149end
150</pre>
151
152<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
153
154<div class=footer>
155<hr>
156<center>
157<p class=bar>
158<a href="home.html">home</a> &middot;
159<a href="home.html#down">download</a> &middot;
160<a href="introduction.html">introduction</a> &middot;
161<a href="reference.html">reference</a>
162</p>
163<p>
164<small>
165Last modified by Diego Nehab on <br>
166Sat Aug 9 01:00:41 PDT 2003
167</small>
168</p>
169</center>
170</div>
171
172</body>
173</html>
diff --git a/doc/tcp.html b/doc/tcp.html
new file mode 100644
index 0000000..ecbedaa
--- /dev/null
+++ b/doc/tcp.html
@@ -0,0 +1,415 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=tcp>TCP</h2>
37
38<!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
39
40<p class=name id=socket.tcp>
41socket.<b>tcp()</b>
42</p>
43
44<p class=description>
45Creates and returns a TCP master object. A master object can
46be transformed into a server object with the method
47<a href=#bind><tt>bind</tt></a> or into a client object with the method
48<a href=#connect><tt>connect</tt></a>. The only other method
49supported by a master object is the <a href=#close><tt>close</tt></a>
50method.</p>
51
52<p class=return>
53In case of success, a new master object is returned. In case of error,
54<tt>nil</tt> is returned, followed by an error message.
55</p>
56
57<!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
58
59<p class=name id=accept>
60server:<b>accept()</b>
61</p>
62
63<p class=description>
64Waits for a remote connection on the server
65object and returns a client object representing that connection.
66</p>
67
68<p class=return>
69If a connection is successfully initiated, a client object is returned.
70If a timeout condition is met, the method returns <tt>nil</tt> followed
71by the error string '<tt>timeout</tt>'.
72</p>
73
74<p class=note>
75Note: calling <a href=misc.html#socket.select><tt>socket.select</tt></a>
76with a server object in
77the <tt>receive</tt> parameter before a call to <tt>accept</tt> does
78<em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a
79href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt>
80might block until <em>another</em> client shows up.
81</p>
82
83<!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
84
85<p class=name id=bind>
86master:<b>bind(</b>address, port [, backlog]<b>)</b>
87</p>
88
89<p class=description>
90Binds a master object to <tt>address</tt> and <tt>port</tt> on the
91local host, transforming it into a server object. Server
92objects support the
93<a href=#accept><tt>accept</tt></a>,
94<a href=#getsockname><tt>getsockname</tt></a>,
95<a href=#setoption><tt>setoption</tt></a>,
96<a href=#settimeout><tt>settimeout</tt></a>,
97and <a href=#close><tt>close</tt></a> methods.
98</p>
99
100<p class=parameters>
101<tt>Address</tt> can be an IP address or a host name.
102<tt>Port</tt> must be an integer number in the range [0..64K].
103If <tt>address</tt>
104is '<tt>*</tt>', the system binds to all local interfaces
105using the <tt>INADDR_ANY</tt> constant. If <tt>port</tt> is 0, the system automatically
106chooses an ephemeral port. The optional parameter <tt>backlog</tt>, which
107defaults to 1, specifies the number of client connections that can
108be queued waiting for service. If the queue is full and another client
109attempts connection, the connection is refused.
110</p>
111
112<p class=return>
113In case of success, the method returns 1. In case of error, the
114method returns <tt>nil</tt> followed by an error message.
115</p>
116
117<p class=note>
118Note: The function <tt>socket.bind</tt> is available and is a short
119for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>bind</tt> method.
120</p>
121
122<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
123
124<p class=name id=close>
125master:<b>close()</b><br>
126client:<b>close()</b><br>
127server:<b>close()</b>
128</p>
129
130<p class=description>
131Closes a TCP object. The internal socket used by the object is closed
132and the local address to which the object was
133bound is made available to other applications. No further operations
134(except for further calls to the <tt>close</tt> method) are allowed on
135a closed socket.
136</p>
137
138<p class=note>
139Note: It is important to close all used sockets once they are not
140needed, since, in many systems, each socket uses a file descriptor,
141which are limited system resources. Garbage-collected objects are
142automatically closed before destruction, though.
143</p>
144
145<!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
146
147<p class=name id=connect>
148master:<b>connect(</b>address, port<b>)</b>
149</p>
150
151<p class=description>
152Attempts to connect a master object to a remote host, transforming it into a
153client object. Client objects support methods
154<a href=#send><tt>send</tt></a>,
155<a href=#receive><tt>receive</tt></a>,
156<a href=#getsockname><tt>getsockname</tt></a>,
157<a href=#getpeername><tt>getpeername</tt></a>,
158<a href=#settimeout><tt>settimeout</tt></a>,
159and <a href=#close><tt>close</tt></a>.
160</p>
161
162<p class=parameters>
163<tt>Address</tt> can be an IP address or a host name.
164<tt>Port</tt> must be an integer number in the range [1..64K].
165</p>
166
167<p class=return>
168In case of error, the method returns <tt>nil</tt> followed by a string
169describing the error. In case of success, the method returns 1.
170</p>
171
172<p class=note>
173Note: The function <tt>socket.connect</tt> is available and is a short
174for <a href=#socket.tcp><tt>socket.tcp</tt></a> followed by the <tt>connect</tt> method.
175</p>
176
177<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
178
179<p class=name id=getpeername>
180client:<b>getpeername()</b>
181</p>
182
183<p class=description>
184Returns information about the remote side of a connected client object.
185</p>
186
187<p class=return>
188Returns a string with the IP address of the peer, followed by the
189port number that peer is using for the connection.
190In case of error, the method returns <tt>nil</tt>.
191</p>
192
193<p class=note>
194Note: It makes no sense to call this method on server objects.
195</p>
196
197<!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
198
199<p class=name id=getsockname>
200client:<b>getsockname()</b><br>
201server:<b>getsockname()</b>
202</p>
203
204<p class=description>
205Returns the local address information associated to the object.
206</p>
207
208<p class=return>
209The method returns a string with local IP address and a number with
210the port. In case of error, the method returns <tt>nil</tt>.
211</p>
212
213<p class=note>
214Note: Naturally, for a server object, the address and port returned are
215those passed to the <a href=#bind>bind</a> method. If the port value
216passed to bind was 0, the OS assigned ephemeral port is returned. For
217client objects, both the address and port are ephemeral and these are the
218values returned.
219</p>
220
221<!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
222
223<p class=name id=receive>
224client:<b>receive(</b>[pattern<sub>1</sub>, pattern<sub>2</sub>,
225... pattern<sub>N</sub>]<b>)</b>
226</p>
227
228<p class=description>
229Reads data from a client object, according to the specified <em>read
230patterns</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
231</p>
232
233<p class=parameters>
234The parameters <tt>pattern</tt><sub>1</sub>, <tt>pattern</tt><sub>2</sub>, ...
235<tt>pattern</tt><sub>N</sub> can be any of the following:
236</p>
237
238<ul>
239<li> '<tt>*a</tt>': reads from the socket until the connection is
240closed. No end-of-line translation is performed;
241<li> '<tt>*l</tt>': reads a line of text from the socket. The line is
242terminated by a LF character (ASCII&nbsp;10), optionally preceded by a
243CR character (ASCII&nbsp;13). The CR and LF characters are not included in
244the returned line. This is the default pattern;
245<li> <tt>number</tt>: causes the method to read <tt>number</tt> raw
246bytes from the socket.
247</ul>
248
249<p class=return>
250The method returns one value for each pattern, followed by a single
251error code that can be <tt>nil</tt> in case of success, the string
252'<tt>closed</tt>' in case the connection was closed before the
253transmission was completed or the string '<tt>timeout</tt>' in case
254there was a timeout during the operation.
255</p>
256
257<p class=note>
258Note: In case of error, the method always return everything it managed
259to download before the error condition was met.
260</p>
261
262<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
263
264<p class=name id=send>
265client:<b>send(</b>string<sub>1</sub> [,
266string<sub>2</sub>, ... string<sub>N</sub>]<b>)</b>
267</p>
268
269<p class=description>
270Sends data through client object.
271</p>
272
273<p class=parameters>
274All parameters should be strings. For small strings, it is always better to
275concatenate them in Lua (with the '<tt>..</tt>' operator) and pass the
276result to LuaSocket instead of passing several independent strings.
277</p>
278
279<p class=return>
280The method returns the number of bytes accepted by the transport layer,
281followed by an error code. The error code is <tt>nil</tt> if the operation
282completed with no errors, the string '<tt>closed</tt>' in case
283the connection was closed before the transmission was completed or the
284string '<tt>timeout</tt>' in case there was a timeout during the
285operation.
286</p>
287
288<p class=note>
289Note: The return values for the <tt>send</tt> method have been changed in
290LuaSocket 2.0! In previous versions, the method returned only the
291error message. Since returning <tt>nil</tt> in case of success goes
292against all other LuaSocket methods and functions, the
293<tt>send</tt> method been changed for the sake of uniformity.
294</p>
295
296<!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
297
298<p class=name id=setoption>
299client:<b>setoption(</b>option [, value]<b>)</b><br>
300server:<b>setoption(</b>option [, value]<b>)</b>
301</p>
302
303<p class=description>
304Sets options for the TCP object. Options are only needed by low-level or
305time-critical applications. You should only modify a an option if you
306are sure you need it.
307</p>
308
309<p class=parameters>
310<tt>Option</tt> is a string with the option name, and <tt>value</tt>
311depends on the option being set:
312
313<ul>
314<li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> disables the
315Nagle's algorithm for the connection;
316<li> '<tt>linger</tt>': Controls the action taken when unsent data are
317queued on socket and a close is performed. The value is a table with a
318boolean entry '<tt>on</tt>' and a numeric entry for the time interval
319'<tt>timeout</tt>' in seconds.
320 If the '<tt>on</tt>' field is set to <tt>true</tt>,
321the system will block the process on the close attempt until it is able to
322transmit the data or until '<tt>timeout</tt>' has passed. If '<tt>on</tt>'
323is <tt>false</tt> and a close is issued, the system will process the close
324in a manner that allows the process to continue as quickly as possible. I
325do not advise you to set this to anything other than zero.
326<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
327the periodic transmission of messages on a connected socket. Should the
328 connected party fail to respond to these messages, the connection is
329considered broken and processes using the socket are notified.
330</ul>
331
332<p class=return>
333The method returns 1 in case of success, or <tt>nil</tt> otherwise.
334</p>
335
336<p class=note>
337Note: The descriptions above come from the man pages.
338</p>
339
340<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
341
342<p class=name id=settimeout>
343client:<b>settimeout(</b>value [, mode]<b>)</b><br>
344server:<b>settimeout(</b>value [, mode]<b>)</b>
345</p>
346
347<p class=description>
348Changes the timeout values for the object. By default,
349all I/O operations are blocking. That is, any call to the methods
350<a href=#send><tt>send</tt></a>,
351<a href=#receive><tt>receive</tt></a>, and
352<a href=#accept><tt>accept</tt></a>
353will block indefinitely, until the operation completes. The
354<tt>settimeout</tt> method defines a limit on the amount of time the
355I/O methods can block. When a timeout is set and the specified amount of
356time has elapsed, the affected methods give up and fail with an error code.
357</p>
358
359<p class=parameters>
360The amount of time to wait is specified as the
361<tt>value</tt> parameter, in seconds. There are two timeout modes and
362both can be used together for fine tuning:
363</p>
364
365<ul>
366<li> '<tt>b</tt>': <em>block</em> timeout. Specifies the upper limit on
367the amount of time LuaSocket can be blocked by the operating system
368while waiting for completion of any single I/O operation. This is the
369default mode;</li>
370
371<li> '<tt>t</tt>': <em>total</em> timeout. Specifies the upper limit on
372the amount of time LuaSocket can block a Lua script before returning from
373a call.</li>
374</ul>
375
376<p class=parameters>
377The <tt>nil</tt> timeout <tt>value</tt> allows operations to block
378indefinitely. Negative timeout values have the same effect.
379</p>
380
381<p class=note>
382Note: although timeout values have millisecond precision in LuaSocket,
383large blocks can cause I/O functions not to respect timeout values due
384to the time the library takes to transfer blocks to and from the OS
385and to and from the Lua interpreter.
386</p>
387
388<p class=note>
389Note: The old <tt>timeout</tt> method is deprecated. The name has been
390changed for sake of uniformity, since all other method names already
391contained verbs making their imperative nature obvious.
392</p>
393
394<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
395
396<div class=footer>
397<hr>
398<center>
399<p class=bar>
400<a href="home.html">home</a> &middot;
401<a href="home.html#down">download</a> &middot;
402<a href="introduction.html">introduction</a> &middot;
403<a href="reference.html">reference</a>
404</p>
405<p>
406<small>
407Last modified by Diego Nehab on <br>
408Sat Aug 9 01:00:41 PDT 2003
409</small>
410</p>
411</center>
412</div>
413
414</body>
415</html>
diff --git a/doc/udp.html b/doc/udp.html
new file mode 100644
index 0000000..235c0c5
--- /dev/null
+++ b/doc/udp.html
@@ -0,0 +1,400 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2"http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5<title>LuaSocket: Network support for the Lua language</title>
6<link rel="stylesheet" href="reference.css" type="text/css">
7</head>
8<body>
9
10<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
11
12<div class=header>
13<hr>
14<center>
15<table summary="LuaSocket logo">
16<tr><td align=center><a href="http://www.lua.org">
17<img border=0 alt="LuaSocket" src="luasocket.png">
18</a></td></tr>
19<tr><td align=center valign=top>Network support for the Lua language
20</td></tr>
21</table>
22<p class=bar>
23<a href="home.html">home</a> &middot;
24<a href="home.html#download">download</a> &middot;
25<a href="introduction.html">introduction</a> &middot;
26<a href="reference.html">reference</a>
27</p>
28</center>
29<hr>
30</div>
31
32<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
33
34<p class="name" id="socket.udp">
35socket.<b>udp()</b>
36</p>
37
38<p class="description">
39Creates and returns an unconnected UDP object. Unconnected objects support the
40<a href="#sendto"><tt>sendto</tt></a>,
41<a href="#receive"><tt>receive</tt></a>,
42<a href="#receivefrom"><tt>receivefrom</tt></a>,
43<a href="#getsockname"><tt>getsockname</tt></a>,
44<a href="#setoption"><tt>setoption</tt></a>,
45<a href="#settimeout"><tt>settimeout</tt></a>,
46<a href="#setpeername"><tt>setpeername</tt></a>,
47<a href="#setsockname"><tt>setsockname</tt></a>, and
48<a href="#close"><tt>close</tt></a>.
49The <a href="#setpeername"><tt>setpeername</tt></a>
50is used to connect the object.
51</p>
52
53<p class="return">
54In case of success, a new unconnected UDP object
55returned. In case of error, <tt>nil</tt> is returned, followed by
56an error message.
57</p>
58
59<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
60
61<p class="name" id="close">
62connected:<b>close()</b><br>
63unconnected:<b>close()</b>
64</p>
65
66<p class="description">
67Closes a UDP object. The internal socket
68used by the object is closed and the local address to which the
69object was bound is made available to other applications. No
70further operations (except for further calls to the <tt>close</tt>
71method) are allowed on a closed socket.
72</p>
73
74<p class="note">
75Note: It is important to close all used sockets
76once they are not needed, since, in many systems, each socket uses
77a file descriptor, which are limited system resources.
78Garbage-collected objects are automatically closed before
79destruction, though.
80</p>
81
82<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
83
84<p class="name" id="getpeername">
85connected:<b>getpeername()</b>
86</p>
87
88<p class="description">
89Retrieves information about the peer
90associated with a connected UDP object.
91</p>
92
93<p class="return">
94Returns the IP address and port number of the peer.
95</p>
96
97<p class="note">
98Note: It makes no sense to call this method on unconnected objects.
99</p>
100
101<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
102
103<p class="name" id="getsockname">
104connected:<b>getsockname()</b><br>
105unconnected:<b>getsockname()</b>
106</p>
107
108<p class="description">
109Returns the local address information associated to the object.
110</p>
111
112<p class="return">
113The method returns a string with local IP
114address and a number with the port. In case of error, the method
115returns <tt>nil</tt>.
116</p>
117
118<p class="note">
119Note: UDP sockets are not bound to any address
120until the <a href="#setsockname"><tt>setsockname</tt></a> or the
121<a href="#sendto"><tt>sendto</tt></a> method is called for the
122first time (in which case it is bound to an ephemeral port and the
123wild-card address).
124</p>
125
126<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
127
128<p class="name" id="receive">
129connected:<b>receive(</b>[size]<b>)</b><br>
130unconnected:<b>receive(</b>[size]<b>)</b>
131</p>
132
133<p class="description">
134Receives a datagram from the UDP object. If
135the UDP object is connected, only datagrams coming from the peer
136are accepted. Otherwise, the returned datagram can come from any
137host.
138</p>
139
140<p class="parameters">
141The optional <tt>size</tt> parameter
142specifies the maximum size of the datagram to be retrieved. If
143there are more than <tt>size</tt> bytes available in the datagram,
144the excess bytes are discarded. If there are less then
145<tt>size</tt> bytes available in the current datagram, the
146available bytes are returned. If <tt>size</tt> is omitted, the
147maximum datagram size is used.
148</p>
149
150<p class="return">
151In case of success, the method return the
152received datagram. In case of timeout, the method returns
153<tt>nil</tt> followed by the string '<tt>timeout</tt>'.
154</p>
155
156<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
157
158<p class="name" id="receivefrom">
159unconnected:<b>receivefrom(</b>[size]<b>)</b>
160</p>
161
162<p class="description">
163Works exactly as the <a href="#receive"><tt>receive</tt></a>
164method, except it returns the IP
165address and port as extra return values (and is therefore slightly less
166efficient).
167</p>
168
169<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
170
171<p class="name" id="send">
172connected:<b>send(</b>datagram<b>)</b>
173</p>
174
175<p class="description">
176Sends a datagram to the UDP peer of a connected object.
177</p>
178
179<p class="parameters">
180<tt>Datagram</tt> is a string with the datagram contents.
181Beware that the maximum datagram size for UDP is 576 bytes.
182</p>
183
184<p class="return">
185If successful, the method returns 1. In case of
186error, the method returns <tt>nil</tt> followed by the
187'<tt>refused</tt>' message.
188</p>
189
190<p class="note">
191Note: In UDP, the <tt>send</tt> method never blocks
192and the only way it can fail is if the underlying transport layer
193refuses to send a message to the specified address (i.e. no
194interface accepts the address).
195</p>
196
197<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
198
199<p class="name" id="sendto">
200unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
201</p>
202
203<p class="description">
204Sends a datagram to the specified IP address and port number.
205</p>
206
207<p class="parameters">
208<tt>Datagram</tt> is a string with the
209datagram contents. Beware that the maximum datagram size for UDP is
210576 bytes. <tt>Ip</tt> is the IP address of the recipient. Host
211names are <em>not</em> allowed for performance reasons.
212<tt>Port</tt> is the port number at the recipient.
213</p>
214
215<p class="return">
216If successful, the method returns 1. In case of
217error, the method returns <tt>nil</tt> followed by the
218'<tt>refused</tt>' message.
219</p>
220
221<p class="note">
222Note: In UDP, the <tt>send</tt> method never blocks
223and the only way it can fail is if the underlying transport layer
224refuses to send a message to the specified address (i.e. no
225interface accepts the address).
226</p>
227
228<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
229
230<p class="name" id="setpeername">
231connected:<b>setpeername(</b>'*'<b>)</b><br>
232unconnected:<b>setpeername(</b>address, port<b>)</b>
233</p>
234
235<p class="description">
236Changes the peer of a UDP object. This
237method turns an unconnected UDP object into a connected UDP
238object or vice-versa.
239</p>
240
241<p class="description">
242For connected objects, outgoing datagrams
243will be sent to the specified peer, and datagrams received from
244other peers will be discarded by the OS. Connected UDP objects must
245use the <a href="#send"><tt>send</tt></a> and
246<a href="#receive"><tt>receive</tt></a> methods instead of
247<a href="#sendto"><tt>sendto</tt></a> and
248<a href="#receivefrom"><tt>receivefrom</tt></a>.
249</p>
250
251<p class="parameters">
252<tt>Address</tt> can be an IP address or a
253host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
254'<tt>*</tt>' and the object is connected, the peer association is
255removed and the object becomes an unconnected object again. In that
256case, the <tt>port</tt> argument is ignored.
257</p>
258
259<p class="return">
260In case of error the method returns
261<tt>nil</tt> followed by an error message. In case of success, the
262method returns 1.
263</p>
264
265<p class="note">
266Note: Since the address of the peer does not have
267to be passed to and from the OS, the use of connected UDP objects
268is recommended when the same peer is used for several transmissions
269and can result in up to 30% performance gains.
270</p>
271
272<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
273
274<p class="name" id="setsockname">
275unconnected:<b>setsockname(</b>address, port<b>)</b>
276</p>
277
278<p class="description">
279Binds the UDP object to a local address.
280</p>
281
282<p class="parameters">
283<tt>Address</tt> can be an IP address or a
284host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
285all local interfaces using the constant <tt>INADDR_ANY</tt>. If
286<tt>port</tt> is 0, the system chooses an ephemeral port.
287</p>
288
289<p class="return">
290If successful, the method returns 1. In case of
291error, the method returns <tt>nil</tt> followed by an error
292message.
293</p>
294
295<p class="note">
296Note: This method can only be called before any
297datagram is sent through the UDP object, and only once. Otherwise,
298the system automatically binds the object to all local interfaces
299and chooses an ephemeral port as soon as the first datagram is
300sent. After the local address is set, either automatically by the
301system or explicitly by <tt>setsockname</tt>, it cannot be
302changed.
303</p>
304
305<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
306
307<p class="name" id="setoption">
308connected:<b>setoption(</b>option [, value]<b>)</b><br>
309unconnected:<b>setoption(</b>option [, value]<b>)</b>
310</p>
311
312<p class="description">
313Sets options for the UDP object. Options are
314only needed by low-level or time-critical applications. You should
315only modify a an option if you are sure you need it.</p>
316<p class="parameters"><tt>Option</tt> is a string with the option
317name, and <tt>value</tt> depends on the option being set:
318</p>
319
320<ul>
321<li>'<tt>dontroute</tt>': Setting this option to <tt>true</tt>
322indicates that outgoing messages should bypass the standard routing
323facilities;</li>
324<li>'<tt>broadcast</tt>': Setting this option to <tt>true</tt>
325requests permission to send broadcast datagrams on the
326socket.</li>
327</ul>
328
329<p class="return">
330The method returns 1 in case of success, or
331<tt>nil</tt> followed by an error message otherwise.
332</p>
333
334<p class="note">
335Note: The descriptions above come from the man
336pages.
337</p>
338
339<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
340
341<p class="name" id="settimeout">
342connected:<b>settimeout(</b>value<b>)</b><br>
343unconnected:<b>settimeout(</b>value<b>)</b>
344</p>
345
346<p class="description">
347Changes the timeout values for the object. By default, the
348<a href="#receive"><tt>receive</tt></a> and
349<a href="#receivefrom"><tt>receivefrom</tt></a>
350operations are blocking. That is, any call to the methods will block
351indefinitely, until data arrives. The <tt>settimeout</tt> function defines
352a limit on the amount of time the functions can block. When a timeout is
353set and the specified amount of time has elapsed, the affected methods
354give up and fail with an error code.
355</p>
356
357<p class="parameters">
358The amount of time to wait is specified as
359the <tt>value</tt> parameter, in seconds. The <tt>nil</tt> timeout
360<tt>value</tt> allows operations to block indefinitely. Negative
361timeout values have the same effect.
362</p>
363
364<p class="note">
365Note: In UDP, the <a href="#send"><tt>send</tt></a>
366and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
367datagram is just passed to the OS and the call returns
368immediately). Therefore, the <tt>settimeout</tt> method has no
369effect on them.
370</p>
371
372<p class="note">
373Note: The old <tt>timeout</tt> method is
374deprecated. The name has been changed for sake of uniformity, since
375all other method names already contained verbs making their
376imperative nature obvious.
377</p>
378
379<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
380
381<div class=footer>
382<hr>
383<center>
384<p class=bar>
385<a href="home.html">home</a> &middot;
386<a href="home.html#download">download</a> &middot;
387<a href="introduction.html">introduction</a> &middot;
388<a href="reference.html">reference</a>
389</p>
390<p>
391<small>
392Last modified by Diego Nehab on <br>
393Sat Aug 9 01:00:41 PDT 2003
394</small>
395</p>
396</center>
397</div>
398
399</body>
400</html>
diff --git a/doc/url.html b/doc/url.html
new file mode 100644
index 0000000..e67ea13
--- /dev/null
+++ b/doc/url.html
@@ -0,0 +1,265 @@
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<title>LuaSocket: Network support for the Lua language</title>
7<link rel="stylesheet" href="reference.css" type="text/css">
8</head>
9
10<body>
11
12<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
13
14<div class=header>
15<hr>
16<center>
17<table summary="LuaSocket logo">
18<tr><td align=center><a href="http://www.lua.org">
19<img border=0 alt="LuaSocket" src="luasocket.png">
20</a></td></tr>
21<tr><td align=center valign=top>Network support for the Lua language
22</td></tr>
23</table>
24<p class=bar>
25<a href="home.html">home</a> &middot;
26<a href="home.html#download">download</a> &middot;
27<a href="introduction.html">introduction</a> &middot;
28<a href="reference.html">reference</a>
29</p>
30</center>
31<hr>
32</div>
33
34<!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
35
36<h2 id=url>URL</h2>
37
38<p>
39The module <tt>url.lua</tt> provides functions to parse, protect,
40and build URLs, as well as functions to compose absolute URLs
41from base and relative URLs, according to
42<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC
432396</a>.
44</p>
45
46<p>
47An URL is defined by the following grammar:
48</p>
49
50<blockquote>
51<tt>
52&lt;url&gt; ::= [&lt;scheme&gt;:][//&lt;authority&gt;][/&lt;path&gt;][;&lt;params&gt;][?&lt;query&gt;][#&lt;fragment&gt;]<br>
53&lt;authority&gt; ::= [&lt;userinfo&gt;@]&lt;host&gt;[:&lt;port&gt;]<br>
54&lt;userinfo&gt; ::= &lt;user&gt;[:&lt;password&gt;]<br>
55&lt;path&gt; ::= {&lt;segment&gt;/}&lt;segment&gt;<br>
56</tt>
57</blockquote>
58
59<!-- absolute +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
60
61<p class=name id=absolute>
62socket.url.<b>absolute(</b>base, relative<b>)</b>
63</p>
64
65<p class=description>
66Builds an absolute URL from a base URL and a relative URL.
67</p>
68
69<p class=parameters>
70<tt>Base</tt> is a string with the base URL and <tt>relative</tt> is a
71string with the relative URL.
72</p>
73
74<p class=return>
75The function returns a string with the absolute URL.
76</p>
77
78<p class=note>
79Note: The rules that
80govern the composition are fairly complex, and are described in detail in
81<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2396.txt">RFC 2396</a>.
82The example bellow should give an idea of what are the rules.
83</p>
84
85<pre class=example>
86http://a/b/c/d;p?q
87
88+
89
90g:h = g:h
91g = http://a/b/c/g
92./g = http://a/b/c/g
93g/ = http://a/b/c/g/
94/g = http://a/g
95//g = http://g
96?y = http://a/b/c/?y
97g?y = http://a/b/c/g?y
98#s = http://a/b/c/d;p?q#s
99g#s = http://a/b/c/g#s
100g?y#s = http://a/b/c/g?y#s
101;x = http://a/b/c/;x
102g;x = http://a/b/c/g;x
103g;x?y#s = http://a/b/c/g;x?y#s
104. = http://a/b/c/
105./ = http://a/b/c/
106.. = http://a/b/
107../ = http://a/b/
108../g = http://a/b/g
109../.. = http://a/
110../../ = http://a/
111../../g = http://a/g
112</pre>
113
114<!-- build ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
115
116<p class=name id=build>
117socket.url.<b>build(</b>parsed_url<b>)</b>
118</p>
119
120<p class=description>
121Rebuilds an URL from its parts.
122</p>
123
124<p class=parameters>
125<tt>Parsed_url</tt> is a table with same components returned by
126<a href="#parse"><tt>parse</tt></a>.
127Lower level components, if specified,
128take precedence over hight level components of the URL grammar.
129</p>
130
131<p class=return>
132The function returns a string with the built URL.
133</p>
134
135<!-- build_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
136
137<p class=name id=build_path>
138socket.url.<b>build_path(</b>segments, unsafe<b>)</b>
139</p>
140
141<p class=description>
142Builds a <tt>&lt;path&gt;</tt> component from a list of
143<tt>&lt;segment&gt;</tt> parts.
144Before composition, any reserved characters found in a segment are escaped into
145their protected form, so that the resulting path is a valid URL path
146component.
147</p>
148
149<p class=parameters>
150<tt>Segments</tt> is a list of strings with the <tt>&lt;segment&gt;</tt>
151parts. If <tt>unsafe</tt> is anything but <tt>nil</tt>, reserved
152characters are left untouched.
153</p>
154
155<p class=return>
156The function returns a string with the
157built <tt>&lt;path&gt;</tt> component.
158</p>
159
160<!-- parse ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
161
162<p class=name id=parse>
163socket.url.<b>parse(</b>url, default<b>)</b>
164</p>
165
166<p class=description>
167Parses an URL given as a string into a Lua table with its components.
168</p>
169
170<p class=parameters>
171<tt>Url</tt> is the URL to be parsed. If the <tt>default</tt> table is
172present, it is used to store the parsed fields. Only fields present in the
173URL are overwritten. Therefore, this table can be used to pass default
174values for each field.
175</p>
176
177<p class=return>
178The function returns a table with all the URL components:
179</p>
180
181<blockquote><tt>
182parsed_url = {<br>
183&nbsp;&nbsp;url = <i>string</i>,<br>
184&nbsp;&nbsp;scheme = <i>string</i>,<br>
185&nbsp;&nbsp;authority = <i>string</i>,<br>
186&nbsp;&nbsp;path = <i>string</i>,<br>
187&nbsp;&nbsp;params = <i>string</i>,<br>
188&nbsp;&nbsp;query = <i>string</i>,<br>
189&nbsp;&nbsp;fragment = <i>string</i>,<br>
190&nbsp;&nbsp;userinfo = <i>string</i>,<br>
191&nbsp;&nbsp;host = <i>string</i>,<br>
192&nbsp;&nbsp;port = <i>string</i>,<br>
193&nbsp;&nbsp;user = <i>string</i>,<br>
194&nbsp;&nbsp;password = <i>string</i><br>
195}
196</tt></blockquote>
197
198<pre class=example>
199parsed_url = socket.url.parse("http://www.puc-rio.br/~diego/index.lua?a=2#there")
200-- parsed_url = {
201-- scheme = "http",
202-- authority = "www.puc-rio.br",
203-- path = "/~diego/index.lua"
204-- query = "a=2",
205-- fragment = "there",
206-- host = "www.puc-rio.br",
207-- }
208
209parsed_url = socket.url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
210-- parsed_url = {
211-- scheme = "ftp",
212-- authority = "root:passwd@unsafe.org",
213-- path = "/pub/virus.exe",
214-- params = "type=i",
215-- userinfo = "root:passwd",
216-- host = "unsafe.org",
217-- user = "root",
218-- password = "passwd",
219-- }
220</pre>
221
222<!-- parse_path +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
223
224<p class=name id=parse_path>
225socket.url.<b>parse_path(</b>path<b>)</b>
226</p>
227
228<p class=description>
229Breaks a <tt>&lt;path&gt;</tt> URL component into all its
230<tt>&lt;segment&gt;</tt> parts.
231</p>
232
233<p class=description>
234<tt>Path</tt> is a string with the path to be parsed.
235</p>
236
237<p class=return>
238Since some characters are reserved in URLs, they must be escaped
239whenever present in a <tt>&lt;path&gt;</tt> component. Therefore, before
240returning a list with all the parsed segments, the function unescapes all
241of them.
242</p>
243
244<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
245
246<div class=footer>
247<hr>
248<center>
249<p class=bar>
250<a href="home.html">home</a> &middot;
251<a href="home.html#down">download</a> &middot;
252<a href="introduction.html">introduction</a> &middot;
253<a href="reference.html">reference</a>
254</p>
255<p>
256<small>
257Last modified by Diego Nehab on <br>
258Sat Aug 9 01:00:41 PDT 2003
259</small>
260</p>
261</center>
262</div>
263
264</body>
265</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-26 09:52:36 +0000