diff options
| -rw-r--r-- | doc/dns.html | 78 | ||||
| -rw-r--r-- | doc/ftp.html | 122 | ||||
| -rw-r--r-- | doc/http.html | 142 | ||||
| -rw-r--r-- | doc/index.html | 140 | ||||
| -rw-r--r-- | doc/ltn12.html | 200 | ||||
| -rw-r--r-- | doc/mime.html | 302 | ||||
| -rw-r--r-- | doc/reference.html | 22 | ||||
| -rw-r--r-- | doc/smtp.html | 191 | ||||
| -rw-r--r-- | doc/socket.html | 256 | ||||
| -rw-r--r-- | doc/tcp.html | 325 | ||||
| -rw-r--r-- | doc/udp.html | 94 |
11 files changed, 938 insertions, 934 deletions
diff --git a/doc/dns.html b/doc/dns.html index c4a0472..56ce3ba 100644 --- a/doc/dns.html +++ b/doc/dns.html | |||
| @@ -1,4 +1,4 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| @@ -13,22 +13,22 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| 30 | <a href="introduction.html">introduction</a> · | 30 | <a href="introduction.html">introduction</a> · |
| 31 | <a href="reference.html">reference</a> | 31 | <a href="reference.html">reference</a> |
| 32 | </p> | 32 | </p> |
| 33 | </center> | 33 | </center> |
| 34 | <hr> | 34 | <hr> |
| @@ -36,14 +36,14 @@ | |||
| 36 | 36 | ||
| 37 | <!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 37 | <!-- dns ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 38 | 38 | ||
| 39 | <h2 id=dns>DNS</h2> | 39 | <h2 id="dns">DNS</h2> |
| 40 | 40 | ||
| 41 | <p> | 41 | <p> |
| 42 | IPv4 name resolution functions | 42 | IPv4 name resolution functions |
| 43 | <a href=#toip><tt>dns.toip</tt></a> | 43 | <a href="#toip"><tt>dns.toip</tt></a> |
| 44 | and | 44 | and |
| 45 | <a href=#tohostname><tt>dns.tohostname</tt></a> | 45 | <a href="#tohostname"><tt>dns.tohostname</tt></a> |
| 46 | return <em>all</em> information obtained from | 46 | return <em>all</em> information obtained from |
| 47 | the resolver in a table of the form: | 47 | the resolver in a table of the form: |
| 48 | </p> | 48 | </p> |
| 49 | 49 | ||
| @@ -60,10 +60,10 @@ Note that the <tt>alias</tt> list can be empty. | |||
| 60 | </p> | 60 | </p> |
| 61 | 61 | ||
| 62 | <p> | 62 | <p> |
| 63 | The more general name resolution function | 63 | The more general name resolution function |
| 64 | <a href=#getaddrinfo><tt>dns.getaddrinfo</tt></a>, which | 64 | <a href="#getaddrinfo"><tt>dns.getaddrinfo</tt></a>, which |
| 65 | supports both IPv6 and IPv4, | 65 | supports both IPv6 and IPv4, |
| 66 | returns <em>all</em> information obtained from | 66 | returns <em>all</em> information obtained from |
| 67 | the resolver in a table of the form: | 67 | the resolver in a table of the form: |
| 68 | </p> | 68 | </p> |
| 69 | 69 | ||
| @@ -88,82 +88,82 @@ addresses, and <tt>"inet6"</tt> for IPv6 addresses. | |||
| 88 | 88 | ||
| 89 | <!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 89 | <!-- getaddrinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 90 | 90 | ||
| 91 | <p class=name id=getaddrinfo> | 91 | <p class="name" id="getaddrinfo"> |
| 92 | socket.dns.<b>getaddrinfo(</b>address<b>)</b> | 92 | socket.dns.<b>getaddrinfo(</b>address<b>)</b> |
| 93 | </p> | 93 | </p> |
| 94 | 94 | ||
| 95 | <p class=description> | 95 | <p class="description"> |
| 96 | Converts from host name to address. | 96 | Converts from host name to address. |
| 97 | </p> | 97 | </p> |
| 98 | 98 | ||
| 99 | <p class=parameters> | 99 | <p class="parameters"> |
| 100 | <tt>Address</tt> can be an IPv4 or IPv6 address or host name. | 100 | <tt>Address</tt> can be an IPv4 or IPv6 address or host name. |
| 101 | </p> | 101 | </p> |
| 102 | 102 | ||
| 103 | <p class=return> | 103 | <p class="return"> |
| 104 | The function returns a table with all information returned by | 104 | The function returns a table with all information returned by |
| 105 | the resolver. In case of error, the function returns <b><tt>nil</tt></b> | 105 | the resolver. In case of error, the function returns <b><tt>nil</tt></b> |
| 106 | followed by an error message. | 106 | followed by an error message. |
| 107 | </p> | 107 | </p> |
| 108 | 108 | ||
| 109 | <!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 109 | <!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 110 | 110 | ||
| 111 | <p class=name id=gethostname> | 111 | <p class="name" id="gethostname"> |
| 112 | socket.dns.<b>gethostname()</b> | 112 | socket.dns.<b>gethostname()</b> |
| 113 | </p> | 113 | </p> |
| 114 | 114 | ||
| 115 | <p class=description> | 115 | <p class="description"> |
| 116 | Returns the standard host name for the machine as a string. | 116 | Returns the standard host name for the machine as a string. |
| 117 | </p> | 117 | </p> |
| 118 | 118 | ||
| 119 | <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 119 | <!-- tohostname +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 120 | 120 | ||
| 121 | <p class=name id=tohostname> | 121 | <p class="name" id="tohostname"> |
| 122 | socket.dns.<b>tohostname(</b>address<b>)</b> | 122 | socket.dns.<b>tohostname(</b>address<b>)</b> |
| 123 | </p> | 123 | </p> |
| 124 | 124 | ||
| 125 | <p class=description> | 125 | <p class="description"> |
| 126 | Converts from IPv4 address to host name. | 126 | Converts from IPv4 address to host name. |
| 127 | </p> | 127 | </p> |
| 128 | 128 | ||
| 129 | <p class=parameters> | 129 | <p class="parameters"> |
| 130 | <tt>Address</tt> can be an IP address or host name. | 130 | <tt>Address</tt> can be an IP address or host name. |
| 131 | </p> | 131 | </p> |
| 132 | 132 | ||
| 133 | <p class=return> | 133 | <p class="return"> |
| 134 | The function returns a string with the canonic host name of the given | 134 | The function returns a string with the canonic host name of the given |
| 135 | <tt>address</tt>, followed by a table with all information returned by | 135 | <tt>address</tt>, followed by a table with all information returned by |
| 136 | the resolver. In case of error, the function returns <b><tt>nil</tt></b> | 136 | the resolver. In case of error, the function returns <b><tt>nil</tt></b> |
| 137 | followed by an error message. | 137 | followed by an error message. |
| 138 | </p> | 138 | </p> |
| 139 | 139 | ||
| 140 | <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 140 | <!-- toip +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 141 | 141 | ||
| 142 | <p class=name id=toip> | 142 | <p class="name" id="toip"> |
| 143 | socket.dns.<b>toip(</b>address<b>)</b> | 143 | socket.dns.<b>toip(</b>address<b>)</b> |
| 144 | </p> | 144 | </p> |
| 145 | 145 | ||
| 146 | <p class=description> | 146 | <p class="description"> |
| 147 | Converts from host name to IPv4 address. | 147 | Converts from host name to IPv4 address. |
| 148 | </p> | 148 | </p> |
| 149 | 149 | ||
| 150 | <p class=parameters> | 150 | <p class="parameters"> |
| 151 | <tt>Address</tt> can be an IP address or host name. | 151 | <tt>Address</tt> can be an IP address or host name. |
| 152 | </p> | 152 | </p> |
| 153 | 153 | ||
| 154 | <p class=return> | 154 | <p class="return"> |
| 155 | Returns a string with the first IP address found for <tt>address</tt>, | 155 | Returns a string with the first IP address found for <tt>address</tt>, |
| 156 | followed by a table with all information returned by the resolver. | 156 | followed by a table with all information returned by the resolver. |
| 157 | In case of error, the function returns <b><tt>nil</tt></b> followed by an error | 157 | In case of error, the function returns <b><tt>nil</tt></b> followed by an error |
| 158 | message. | 158 | message. |
| 159 | </p> | 159 | </p> |
| 160 | 160 | ||
| 161 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 161 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 162 | 162 | ||
| 163 | <div class=footer> | 163 | <div class="footer"> |
| 164 | <hr> | 164 | <hr> |
| 165 | <center> | 165 | <center> |
| 166 | <p class=bar> | 166 | <p class="bar"> |
| 167 | <a href="index.html">home</a> · | 167 | <a href="index.html">home</a> · |
| 168 | <a href="index.html#down">download</a> · | 168 | <a href="index.html#down">download</a> · |
| 169 | <a href="installation.html">installation</a> · | 169 | <a href="installation.html">installation</a> · |
diff --git a/doc/ftp.html b/doc/ftp.html index 091c88f..7f7da2e 100644 --- a/doc/ftp.html +++ b/doc/ftp.html | |||
| @@ -1,5 +1,5 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| 5 | <head> | 5 | <head> |
| @@ -13,22 +13,22 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| 30 | <a href="introduction.html">introduction</a> · | 30 | <a href="introduction.html">introduction</a> · |
| 31 | <a href="reference.html">reference</a> | 31 | <a href="reference.html">reference</a> |
| 32 | </p> | 32 | </p> |
| 33 | </center> | 33 | </center> |
| 34 | <hr> | 34 | <hr> |
| @@ -36,7 +36,7 @@ | |||
| 36 | 36 | ||
| 37 | <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 37 | <!-- ftp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 38 | 38 | ||
| 39 | <h2 id=ftp>FTP</h2> | 39 | <h2 id="ftp">FTP</h2> |
| 40 | 40 | ||
| 41 | <p> | 41 | <p> |
| 42 | FTP (File Transfer Protocol) is a protocol used to transfer files | 42 | FTP (File Transfer Protocol) is a protocol used to transfer files |
| @@ -50,28 +50,28 @@ High level functions are provided supporting the most common operations. | |||
| 50 | These high level functions are implemented on top of a lower level | 50 | These high level functions are implemented on top of a lower level |
| 51 | interface. Using the low-level interface, users can easily create their | 51 | interface. Using the low-level interface, users can easily create their |
| 52 | own functions to access <em>any</em> operation supported by the FTP | 52 | own functions to access <em>any</em> operation supported by the FTP |
| 53 | protocol. For that, check the implementation. | 53 | protocol. For that, check the implementation. |
| 54 | </p> | 54 | </p> |
| 55 | 55 | ||
| 56 | <p> | 56 | <p> |
| 57 | To really benefit from this module, a good understanding of | 57 | To really benefit from this module, a good understanding of |
| 58 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> | 58 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> |
| 59 | LTN012, Filters sources and sinks</a> is necessary. | 59 | LTN012, Filters sources and sinks</a> is necessary. |
| 60 | </p> | 60 | </p> |
| 61 | 61 | ||
| 62 | <p> | 62 | <p> |
| 63 | To obtain the <tt>ftp</tt> namespace, run: | 63 | To obtain the <tt>ftp</tt> namespace, run: |
| 64 | </p> | 64 | </p> |
| 65 | 65 | ||
| 66 | <pre class=example> | 66 | <pre class="example"> |
| 67 | -- loads the FTP module and any libraries it requires | 67 | -- loads the FTP module and any libraries it requires |
| 68 | local ftp = require("socket.ftp") | 68 | local ftp = require("socket.ftp") |
| 69 | </pre> | 69 | </pre> |
| 70 | 70 | ||
| 71 | <p> | 71 | <p> |
| 72 | URLs MUST conform to | 72 | URLs MUST conform to |
| 73 | <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, | 73 | <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, |
| 74 | that is, an URL is a string in the form: | 74 | that is, an URL is a string in the form: |
| 75 | </p> | 75 | </p> |
| 76 | 76 | ||
| 77 | <blockquote> | 77 | <blockquote> |
| @@ -81,19 +81,19 @@ that is, an URL is a string in the form: | |||
| 81 | 81 | ||
| 82 | <p> | 82 | <p> |
| 83 | The following constants in the namespace can be set to control the default behavior of | 83 | The following constants in the namespace can be set to control the default behavior of |
| 84 | the FTP module: | 84 | the FTP module: |
| 85 | </p> | 85 | </p> |
| 86 | 86 | ||
| 87 | <ul> | 87 | <ul> |
| 88 | <li> <tt>PASSWORD</tt>: default anonymous password. | 88 | <li> <tt>PASSWORD</tt>: default anonymous password.</li> |
| 89 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; | 89 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li> |
| 90 | <li> <tt>USER</tt>: default anonymous user; | 90 | <li> <tt>USER</tt>: default anonymous user;</li> |
| 91 | </ul> | 91 | </ul> |
| 92 | 92 | ||
| 93 | 93 | ||
| 94 | <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 94 | <!-- ftp.get ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 95 | 95 | ||
| 96 | <p class=name id=get> | 96 | <p class="name" id="get"> |
| 97 | ftp.<b>get(</b>url<b>)</b><br> | 97 | ftp.<b>get(</b>url<b>)</b><br> |
| 98 | ftp.<b>get{</b><br> | 98 | ftp.<b>get{</b><br> |
| 99 | host = <i>string</i>,<br> | 99 | host = <i>string</i>,<br> |
| @@ -109,19 +109,19 @@ ftp.<b>get{</b><br> | |||
| 109 | <b>}</b> | 109 | <b>}</b> |
| 110 | </p> | 110 | </p> |
| 111 | 111 | ||
| 112 | <p class=description> | 112 | <p class="description"> |
| 113 | The <tt>get</tt> function has two forms. The simple form has fixed | 113 | The <tt>get</tt> function has two forms. The simple form has fixed |
| 114 | functionality: it downloads the contents of a URL and returns it as a | 114 | functionality: it downloads the contents of a URL and returns it as a |
| 115 | string. The generic form allows a <em>lot</em> more control, as explained | 115 | string. The generic form allows a <em>lot</em> more control, as explained |
| 116 | below. | 116 | below. |
| 117 | </p> | 117 | </p> |
| 118 | 118 | ||
| 119 | <p class=parameters> | 119 | <p class="parameters"> |
| 120 | If the argument of the <tt>get</tt> function is a table, the function | 120 | If the argument of the <tt>get</tt> function is a table, the function |
| 121 | expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of | 121 | expects at least the fields <tt>host</tt>, <tt>sink</tt>, and one of |
| 122 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes | 122 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes |
| 123 | precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is | 123 | precedence). <tt>Host</tt> is the server to connect to. <tt>Sink</tt> is |
| 124 | the <em>simple</em> | 124 | the <em>simple</em> |
| 125 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 125 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 126 | sink that will receive the downloaded data. <tt>Argument</tt> or | 126 | sink that will receive the downloaded data. <tt>Argument</tt> or |
| 127 | <tt>path</tt> give the target path to the resource in the server. The | 127 | <tt>path</tt> give the target path to the resource in the server. The |
| @@ -129,28 +129,28 @@ optional arguments are the following: | |||
| 129 | </p> | 129 | </p> |
| 130 | <ul> | 130 | <ul> |
| 131 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for | 131 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for |
| 132 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; | 132 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li> |
| 133 | <li><tt>command</tt>: The FTP command used to obtain data. Defaults to | 133 | <li><tt>command</tt>: The FTP command used to obtain data. Defaults to |
| 134 | "<tt>retr</tt>", but see example below; | 134 | "<tt>retr</tt>", but see example below;</li> |
| 135 | <li><tt>port</tt>: The port to used for the control connection. Defaults to 21; | 135 | <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li> |
| 136 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or | 136 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or |
| 137 | "<tt>a</tt>". Defaults to whatever is the server default; | 137 | "<tt>a</tt>". Defaults to whatever is the server default;</li> |
| 138 | <li><tt>step</tt>: | 138 | <li><tt>step</tt>: |
| 139 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 139 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 140 | pump step function used to pass data from the | 140 | pump step function used to pass data from the |
| 141 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; | 141 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li> |
| 142 | <li><tt>create</tt>: An optional function to be used instead of | 142 | <li><tt>create</tt>: An optional function to be used instead of |
| 143 | <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. | 143 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> |
| 144 | </ul> | 144 | </ul> |
| 145 | 145 | ||
| 146 | <p class=return> | 146 | <p class="return"> |
| 147 | If successful, the simple version returns the URL contents as a | 147 | If successful, the simple version returns the URL contents as a |
| 148 | string, and the generic function returns 1. In case of error, both | 148 | string, and the generic function returns 1. In case of error, both |
| 149 | functions return <b><tt>nil</tt></b> and an error message describing the | 149 | functions return <b><tt>nil</tt></b> and an error message describing the |
| 150 | error. | 150 | error. |
| 151 | </p> | 151 | </p> |
| 152 | 152 | ||
| 153 | <pre class=example> | 153 | <pre class="example"> |
| 154 | -- load the ftp support | 154 | -- load the ftp support |
| 155 | local ftp = require("socket.ftp") | 155 | local ftp = require("socket.ftp") |
| 156 | 156 | ||
| @@ -159,7 +159,7 @@ local ftp = require("socket.ftp") | |||
| 159 | f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") | 159 | f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i") |
| 160 | </pre> | 160 | </pre> |
| 161 | 161 | ||
| 162 | <pre class=example> | 162 | <pre class="example"> |
| 163 | -- load needed modules | 163 | -- load needed modules |
| 164 | local ftp = require("socket.ftp") | 164 | local ftp = require("socket.ftp") |
| 165 | local ltn12 = require("ltn12") | 165 | local ltn12 = require("ltn12") |
| @@ -178,7 +178,7 @@ end | |||
| 178 | 178 | ||
| 179 | <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 179 | <!-- put ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 180 | 180 | ||
| 181 | <p class=name id=put> | 181 | <p class="name" id="put"> |
| 182 | ftp.<b>put(</b>url, content<b>)</b><br> | 182 | ftp.<b>put(</b>url, content<b>)</b><br> |
| 183 | ftp.<b>put{</b><br> | 183 | ftp.<b>put{</b><br> |
| 184 | host = <i>string</i>,<br> | 184 | host = <i>string</i>,<br> |
| @@ -194,57 +194,57 @@ ftp.<b>put{</b><br> | |||
| 194 | <b>}</b> | 194 | <b>}</b> |
| 195 | </p> | 195 | </p> |
| 196 | 196 | ||
| 197 | <p class=description> | 197 | <p class="description"> |
| 198 | The <tt>put</tt> function has two forms. The simple form has fixed | 198 | The <tt>put</tt> function has two forms. The simple form has fixed |
| 199 | functionality: it uploads a string of content into a URL. The generic form | 199 | functionality: it uploads a string of content into a URL. The generic form |
| 200 | allows a <em>lot</em> more control, as explained below. | 200 | allows a <em>lot</em> more control, as explained below. |
| 201 | </p> | 201 | </p> |
| 202 | 202 | ||
| 203 | <p class=parameters> | 203 | <p class="parameters"> |
| 204 | If the argument of the <tt>put</tt> function is a table, the function | 204 | If the argument of the <tt>put</tt> function is a table, the function |
| 205 | expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of | 205 | expects at least the fields <tt>host</tt>, <tt>source</tt>, and one of |
| 206 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes | 206 | <tt>argument</tt> or <tt>path</tt> (<tt>argument</tt> takes |
| 207 | precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is | 207 | precedence). <tt>Host</tt> is the server to connect to. <tt>Source</tt> is |
| 208 | the <em>simple</em> | 208 | the <em>simple</em> |
| 209 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 209 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 210 | source that will provide the contents to be uploaded. | 210 | source that will provide the contents to be uploaded. |
| 211 | <tt>Argument</tt> or | 211 | <tt>Argument</tt> or |
| 212 | <tt>path</tt> give the target path to the resource in the server. The | 212 | <tt>path</tt> give the target path to the resource in the server. The |
| 213 | optional arguments are the following: | 213 | optional arguments are the following: |
| 214 | </p> | 214 | </p> |
| 215 | <ul> | 215 | <ul> |
| 216 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for | 216 | <li><tt>user</tt>, <tt>password</tt>: User name and password used for |
| 217 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>"; | 217 | authentication. Defaults to "<tt>ftp:anonymous@anonymous.org</tt>";</li> |
| 218 | <li><tt>command</tt>: The FTP command used to send data. Defaults to | 218 | <li><tt>command</tt>: The FTP command used to send data. Defaults to |
| 219 | "<tt>stor</tt>", but see example below; | 219 | "<tt>stor</tt>", but see example below;</li> |
| 220 | <li><tt>port</tt>: The port to used for the control connection. Defaults to 21; | 220 | <li><tt>port</tt>: The port to used for the control connection. Defaults to 21;</li> |
| 221 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or | 221 | <li><tt>type</tt>: The transfer mode. Can take values "<tt>i</tt>" or |
| 222 | "<tt>a</tt>". Defaults to whatever is the server default; | 222 | "<tt>a</tt>". Defaults to whatever is the server default;</li> |
| 223 | <li><tt>step</tt>: | 223 | <li><tt>step</tt>: |
| 224 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 224 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 225 | pump step function used to pass data from the | 225 | pump step function used to pass data from the |
| 226 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function; | 226 | server to the sink. Defaults to the LTN12 <tt>pump.step</tt> function;</li> |
| 227 | <li><tt>create</tt>: An optional function to be used instead of | 227 | <li><tt>create</tt>: An optional function to be used instead of |
| 228 | <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. | 228 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> |
| 229 | </ul> | 229 | </ul> |
| 230 | 230 | ||
| 231 | <p class=return> | 231 | <p class="return"> |
| 232 | Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error | 232 | Both functions return 1 if successful, or <b><tt>nil</tt></b> and an error |
| 233 | message describing the reason for failure. | 233 | message describing the reason for failure. |
| 234 | </p> | 234 | </p> |
| 235 | 235 | ||
| 236 | <pre class=example> | 236 | <pre class="example"> |
| 237 | -- load the ftp support | 237 | -- load the ftp support |
| 238 | local ftp = require("socket.ftp") | 238 | local ftp = require("socket.ftp") |
| 239 | 239 | ||
| 240 | -- Log as user "fulano" on server "ftp.example.com", | 240 | -- Log as user "fulano" on server "ftp.example.com", |
| 241 | -- using password "silva", and store a file "README" with contents | 241 | -- using password "silva", and store a file "README" with contents |
| 242 | -- "wrong password, of course" | 242 | -- "wrong password, of course" |
| 243 | f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", | 243 | f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", |
| 244 | "wrong password, of course") | 244 | "wrong password, of course") |
| 245 | </pre> | 245 | </pre> |
| 246 | 246 | ||
| 247 | <pre class=example> | 247 | <pre class="example"> |
| 248 | -- load the ftp support | 248 | -- load the ftp support |
| 249 | local ftp = require("socket.ftp") | 249 | local ftp = require("socket.ftp") |
| 250 | local ltn12 = require("ltn12") | 250 | local ltn12 = require("ltn12") |
| @@ -253,7 +253,7 @@ local ltn12 = require("ltn12") | |||
| 253 | -- using password "silva", and append to the remote file "LOG", sending the | 253 | -- using password "silva", and append to the remote file "LOG", sending the |
| 254 | -- contents of the local file "LOCAL-LOG" | 254 | -- contents of the local file "LOCAL-LOG" |
| 255 | f, e = ftp.put{ | 255 | f, e = ftp.put{ |
| 256 | host = "ftp.example.com", | 256 | host = "ftp.example.com", |
| 257 | user = "fulano", | 257 | user = "fulano", |
| 258 | password = "silva", | 258 | password = "silva", |
| 259 | command = "appe", | 259 | command = "appe", |
| @@ -265,15 +265,15 @@ f, e = ftp.put{ | |||
| 265 | 265 | ||
| 266 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 266 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 267 | 267 | ||
| 268 | <div class=footer> | 268 | <div class="footer"> |
| 269 | <hr> | 269 | <hr> |
| 270 | <center> | 270 | <center> |
| 271 | <p class=bar> | 271 | <p class="bar"> |
| 272 | <a href="index.html">home</a> · | 272 | <a href="index.html">home</a> · |
| 273 | <a href="index.html#download">download</a> · | 273 | <a href="index.html#download">download</a> · |
| 274 | <a href="installation.html">installation</a> · | 274 | <a href="installation.html">installation</a> · |
| 275 | <a href="introduction.html">introduction</a> · | 275 | <a href="introduction.html">introduction</a> · |
| 276 | <a href="reference.html">reference</a> | 276 | <a href="reference.html">reference</a> |
| 277 | </p> | 277 | </p> |
| 278 | <p> | 278 | <p> |
| 279 | <small> | 279 | <small> |
diff --git a/doc/http.html b/doc/http.html index 78f785a..52b8a30 100644 --- a/doc/http.html +++ b/doc/http.html | |||
| @@ -1,10 +1,10 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| 5 | <head> | 5 | <head> |
| 6 | <meta name="description" content="LuaSocket: HTTP support"> | 6 | <meta name="description" content="LuaSocket: HTTP support"> |
| 7 | <meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> | 7 | <meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support"> |
| 8 | <title>LuaSocket: HTTP support</title> | 8 | <title>LuaSocket: HTTP support</title> |
| 9 | <link rel="stylesheet" href="reference.css" type="text/css"> | 9 | <link rel="stylesheet" href="reference.css" type="text/css"> |
| 10 | </head> | 10 | </head> |
| @@ -13,22 +13,22 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="introduction.html">introduction</a> · | 29 | <a href="introduction.html">introduction</a> · |
| 30 | <a href="introduction.html">introduction</a> · | 30 | <a href="introduction.html">introduction</a> · |
| 31 | <a href="reference.html">reference</a> | 31 | <a href="reference.html">reference</a> |
| 32 | </p> | 32 | </p> |
| 33 | </center> | 33 | </center> |
| 34 | <hr> | 34 | <hr> |
| @@ -36,12 +36,12 @@ | |||
| 36 | 36 | ||
| 37 | <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 37 | <!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 38 | 38 | ||
| 39 | <h2 id="http">HTTP</h2> | 39 | <h2 id="http">HTTP</h2> |
| 40 | 40 | ||
| 41 | <p> | 41 | <p> |
| 42 | HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange | 42 | HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange |
| 43 | information between web-browsers and servers. The <tt>http</tt> | 43 | information between web-browsers and servers. The <tt>http</tt> |
| 44 | namespace offers full support for the client side of the HTTP | 44 | namespace offers full support for the client side of the HTTP |
| 45 | protocol (i.e., | 45 | protocol (i.e., |
| 46 | the facilities that would be used by a web-browser implementation). The | 46 | the facilities that would be used by a web-browser implementation). The |
| 47 | implementation conforms to the HTTP/1.1 standard, | 47 | implementation conforms to the HTTP/1.1 standard, |
| @@ -50,16 +50,16 @@ implementation conforms to the HTTP/1.1 standard, | |||
| 50 | 50 | ||
| 51 | <p> | 51 | <p> |
| 52 | The module exports functions that provide HTTP functionality in different | 52 | The module exports functions that provide HTTP functionality in different |
| 53 | levels of abstraction. From the simple | 53 | levels of abstraction. From the simple |
| 54 | string oriented requests, through generic | 54 | string oriented requests, through generic |
| 55 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code. | 55 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code. |
| 56 | </p> | 56 | </p> |
| 57 | 57 | ||
| 58 | <p> | 58 | <p> |
| 59 | To obtain the <tt>http</tt> namespace, run: | 59 | To obtain the <tt>http</tt> namespace, run: |
| 60 | </p> | 60 | </p> |
| 61 | 61 | ||
| 62 | <pre class=example> | 62 | <pre class="example"> |
| 63 | -- loads the HTTP module and any libraries it requires | 63 | -- loads the HTTP module and any libraries it requires |
| 64 | local http = require("socket.http") | 64 | local http = require("socket.http") |
| 65 | </pre> | 65 | </pre> |
| @@ -67,12 +67,12 @@ local http = require("socket.http") | |||
| 67 | <p> | 67 | <p> |
| 68 | URLs must conform to | 68 | URLs must conform to |
| 69 | <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, | 69 | <a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738</a>, |
| 70 | that is, an URL is a string in the form: | 70 | that is, an URL is a string in the form: |
| 71 | </p> | 71 | </p> |
| 72 | 72 | ||
| 73 | <blockquote> | 73 | <blockquote> |
| 74 | <pre> | 74 | <pre> |
| 75 | [http://][<user>[:<password>]@]<host>[:<port>][/<path>] | 75 | [http://][<user>[:<password>]@]<host>[:<port>][/<path>] |
| 76 | </pre> | 76 | </pre> |
| 77 | </blockquote> | 77 | </blockquote> |
| 78 | 78 | ||
| @@ -97,34 +97,34 @@ headers = {<br> | |||
| 97 | <p> | 97 | <p> |
| 98 | Field names are case insensitive (as specified by the standard) and all | 98 | Field names are case insensitive (as specified by the standard) and all |
| 99 | functions work with lowercase field names (but see | 99 | functions work with lowercase field names (but see |
| 100 | <a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). | 100 | <a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>). |
| 101 | Field values are left unmodified. | 101 | Field values are left unmodified. |
| 102 | </p> | 102 | </p> |
| 103 | 103 | ||
| 104 | <p class=note> | 104 | <p class="note"> |
| 105 | Note: MIME headers are independent of order. Therefore, there is no problem | 105 | Note: MIME headers are independent of order. Therefore, there is no problem |
| 106 | in representing them in a Lua table. | 106 | in representing them in a Lua table. |
| 107 | </p> | 107 | </p> |
| 108 | 108 | ||
| 109 | <p> | 109 | <p> |
| 110 | The following constants can be set to control the default behavior of | 110 | The following constants can be set to control the default behavior of |
| 111 | the HTTP module: | 111 | the HTTP module: |
| 112 | </p> | 112 | </p> |
| 113 | 113 | ||
| 114 | <ul> | 114 | <ul> |
| 115 | <li> <tt>PROXY</tt>: default proxy used for connections; | 115 | <li> <tt>PROXY</tt>: default proxy used for connections;</li> |
| 116 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations; | 116 | <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li> |
| 117 | <li> <tt>USERAGENT</tt>: default user agent reported to server. | 117 | <li> <tt>USERAGENT</tt>: default user agent reported to server.</li> |
| 118 | </ul> | 118 | </ul> |
| 119 | 119 | ||
| 120 | <p class=note id="post"> | 120 | <p class="note"> |
| 121 | Note: These constants are global. Changing them will also | 121 | Note: These constants are global. Changing them will also |
| 122 | change the behavior other code that might be using LuaSocket. | 122 | change the behavior other code that might be using LuaSocket. |
| 123 | </p> | 123 | </p> |
| 124 | 124 | ||
| 125 | <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 125 | <!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 126 | 126 | ||
| 127 | <p class=name id="request"> | 127 | <p class="name" id="request"> |
| 128 | http.<b>request(</b>url [, body]<b>)</b><br> | 128 | http.<b>request(</b>url [, body]<b>)</b><br> |
| 129 | http.<b>request{</b><br> | 129 | http.<b>request{</b><br> |
| 130 | url = <i>string</i>,<br> | 130 | url = <i>string</i>,<br> |
| @@ -140,26 +140,26 @@ http.<b>request{</b><br> | |||
| 140 | <b>}</b> | 140 | <b>}</b> |
| 141 | </p> | 141 | </p> |
| 142 | 142 | ||
| 143 | <p class=description> | 143 | <p class="description"> |
| 144 | The request function has two forms. The simple form downloads | 144 | The request function has two forms. The simple form downloads |
| 145 | a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based | 145 | a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based |
| 146 | on strings. The generic form performs any HTTP method and is | 146 | on strings. The generic form performs any HTTP method and is |
| 147 | <a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based. | 147 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based. |
| 148 | </p> | 148 | </p> |
| 149 | 149 | ||
| 150 | <p class=parameters> | 150 | <p class="parameters"> |
| 151 | If the first argument of the <tt>request</tt> function is a string, it | 151 | If the first argument of the <tt>request</tt> function is a string, it |
| 152 | should be an <tt>url</tt>. In that case, if a <tt>body</tt> | 152 | should be an <tt>url</tt>. In that case, if a <tt>body</tt> |
| 153 | is provided as a string, the function will perform a <tt>POST</tt> method | 153 | is provided as a string, the function will perform a <tt>POST</tt> method |
| 154 | in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the | 154 | in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the |
| 155 | <tt>url</tt> | 155 | <tt>url</tt> |
| 156 | </p> | 156 | </p> |
| 157 | 157 | ||
| 158 | <p class=parameters> | 158 | <p class="parameters"> |
| 159 | If the first argument is instead a table, the most important fields are | 159 | If the first argument is instead a table, the most important fields are |
| 160 | the <tt>url</tt> and the <em>simple</em> | 160 | the <tt>url</tt> and the <em>simple</em> |
| 161 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 161 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 162 | <tt>sink</tt> that will receive the downloaded content. | 162 | <tt>sink</tt> that will receive the downloaded content. |
| 163 | Any part of the <tt>url</tt> can be overridden by including | 163 | Any part of the <tt>url</tt> can be overridden by including |
| 164 | the appropriate field in the request table. | 164 | the appropriate field in the request table. |
| 165 | If authentication information is provided, the function | 165 | If authentication information is provided, the function |
| @@ -169,49 +169,51 @@ function discards the downloaded data. The optional parameters are the | |||
| 169 | following: | 169 | following: |
| 170 | </p> | 170 | </p> |
| 171 | <ul> | 171 | <ul> |
| 172 | <li><tt>method</tt>: The HTTP request method. Defaults to "GET"; | 172 | <li><tt>method</tt>: The HTTP request method. Defaults to "GET";</li> |
| 173 | <li><tt>headers</tt>: Any additional HTTP headers to send with the request; | 173 | <li><tt>headers</tt>: Any additional HTTP headers to send with the request;</li> |
| 174 | <li><tt>source</tt>: <em>simple</em> | 174 | <li><tt>source</tt>: <em>simple</em> |
| 175 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 175 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 176 | source to provide the request body. If there | 176 | source to provide the request body. If there |
| 177 | is a body, you need to provide an appropriate "<tt>content-length</tt>" | 177 | is a body, you need to provide an appropriate "<tt>content-length</tt>" |
| 178 | request header field, or the function will attempt to send the body as | 178 | request header field, or the function will attempt to send the body as |
| 179 | "<tt>chunked</tt>" (something few servers support). Defaults to the empty source; | 179 | "<tt>chunked</tt>" (something few servers support). Defaults to the empty source;</li> |
| 180 | <li><tt>step</tt>: | 180 | <li><tt>step</tt>: |
| 181 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 181 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 182 | pump step function used to move data. | 182 | pump step function used to move data. |
| 183 | Defaults to the LTN12 <tt>pump.step</tt> function. | 183 | Defaults to the LTN12 <tt>pump.step</tt> function.</li> |
| 184 | <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy; | 184 | <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;</li> |
| 185 | <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the | 185 | <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the |
| 186 | function from automatically following 301 or 302 server redirect messages; | 186 | function from automatically following 301 or 302 server redirect messages;</li> |
| 187 | <li><tt>create</tt>: An optional function to be used instead of | 187 | <li><tt>create</tt>: An optional function to be used instead of |
| 188 | <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. | 188 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> |
| 189 | <li><tt>maxredirects</tt>: An optional number specifying the maximum number of redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean <tt>false</tt> value means no maximum (unlimited). | 189 | <li><tt>maxredirects</tt>: An optional number specifying the maximum number of |
| 190 | redirects to follow. Defaults to <tt>5</tt> if not specified. A boolean | ||
| 191 | <tt>false</tt> value means no maximum (unlimited).</li> | ||
| 190 | </ul> | 192 | </ul> |
| 191 | 193 | ||
| 192 | <p class=return> | 194 | <p class="return"> |
| 193 | In case of failure, the function returns <tt><b>nil</b></tt> followed by an | 195 | In case of failure, the function returns <tt><b>nil</b></tt> followed by an |
| 194 | error message. If successful, the simple form returns the response | 196 | error message. If successful, the simple form returns the response |
| 195 | body as a string, followed by the response status code, the response | 197 | body as a string, followed by the response status code, the response |
| 196 | headers and the response status line. The generic function returns the same | 198 | headers and the response status line. The generic function returns the same |
| 197 | information, except the first return value is just the number 1 (the body | 199 | information, except the first return value is just the number 1 (the body |
| 198 | goes to the <tt>sink</tt>). | 200 | goes to the <tt>sink</tt>). |
| 199 | </p> | 201 | </p> |
| 200 | 202 | ||
| 201 | <p class=return> | 203 | <p class="return"> |
| 202 | Even when the server fails to provide the contents of the requested URL (URL not found, for example), | 204 | Even when the server fails to provide the contents of the requested URL (URL not found, for example), |
| 203 | it usually returns a message body (a web page informing the | 205 | it usually returns a message body (a web page informing the |
| 204 | URL was not found or some other useless page). To make sure the | 206 | URL was not found or some other useless page). To make sure the |
| 205 | operation was successful, check the returned status <tt>code</tt>. For | 207 | operation was successful, check the returned status <tt>code</tt>. For |
| 206 | a list of the possible values and their meanings, refer to <a | 208 | a list of the possible values and their meanings, refer to <a |
| 207 | href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. | 209 | href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>. |
| 208 | </p> | 210 | </p> |
| 209 | 211 | ||
| 210 | <p class=description> | 212 | <p class="description"> |
| 211 | Here are a few examples with the simple interface: | 213 | Here are a few examples with the simple interface: |
| 212 | </p> | 214 | </p> |
| 213 | 215 | ||
| 214 | <pre class=example> | 216 | <pre class="example"> |
| 215 | -- load the http module | 217 | -- load the http module |
| 216 | local io = require("io") | 218 | local io = require("io") |
| 217 | local http = require("socket.http") | 219 | local http = require("socket.http") |
| @@ -219,15 +221,15 @@ local ltn12 = require("ltn12") | |||
| 219 | 221 | ||
| 220 | -- connect to server "www.cs.princeton.edu" and retrieves this manual | 222 | -- connect to server "www.cs.princeton.edu" and retrieves this manual |
| 221 | -- file from "~diego/professional/luasocket/http.html" and print it to stdout | 223 | -- file from "~diego/professional/luasocket/http.html" and print it to stdout |
| 222 | http.request{ | 224 | http.request{ |
| 223 | url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", | 225 | url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", |
| 224 | sink = ltn12.sink.file(io.stdout) | 226 | sink = ltn12.sink.file(io.stdout) |
| 225 | } | 227 | } |
| 226 | 228 | ||
| 227 | -- connect to server "www.example.com" and tries to retrieve | 229 | -- connect to server "www.example.com" and tries to retrieve |
| 228 | -- "/private/index.html". Fails because authentication is needed. | 230 | -- "/private/index.html". Fails because authentication is needed. |
| 229 | b, c, h = http.request("http://www.example.com/private/index.html") | 231 | b, c, h = http.request("http://www.example.com/private/index.html") |
| 230 | -- b returns some useless page telling about the denied access, | 232 | -- b returns some useless page telling about the denied access, |
| 231 | -- h returns authentication information | 233 | -- h returns authentication information |
| 232 | -- and c returns with value 401 (Authentication Required) | 234 | -- and c returns with value 401 (Authentication Required) |
| 233 | 235 | ||
| @@ -237,11 +239,11 @@ r, e = http.request("http://wrong.host/") | |||
| 237 | -- r is nil, and e returns with value "host not found" | 239 | -- r is nil, and e returns with value "host not found" |
| 238 | </pre> | 240 | </pre> |
| 239 | 241 | ||
| 240 | <p class=description> | 242 | <p class="description"> |
| 241 | And here is an example using the generic interface: | 243 | And here is an example using the generic interface: |
| 242 | </p> | 244 | </p> |
| 243 | 245 | ||
| 244 | <pre class=example> | 246 | <pre class="example"> |
| 245 | -- load the http module | 247 | -- load the http module |
| 246 | http = require("socket.http") | 248 | http = require("socket.http") |
| 247 | 249 | ||
| @@ -263,7 +265,7 @@ r, c, h = http.request { | |||
| 263 | -- } | 265 | -- } |
| 264 | </pre> | 266 | </pre> |
| 265 | 267 | ||
| 266 | <p class=note id="post"> | 268 | <p class="note" id="post"> |
| 267 | Note: When sending a POST request, simple interface adds a | 269 | Note: When sending a POST request, simple interface adds a |
| 268 | "<tt>Content-type: application/x-www-form-urlencoded</tt>" | 270 | "<tt>Content-type: application/x-www-form-urlencoded</tt>" |
| 269 | header to the request. This is the type used by | 271 | header to the request. This is the type used by |
| @@ -271,21 +273,21 @@ HTML forms. If you need another type, use the generic | |||
| 271 | interface. | 273 | interface. |
| 272 | </p> | 274 | </p> |
| 273 | 275 | ||
| 274 | <p class=note id="authentication"> | 276 | <p class="note" id="authentication"> |
| 275 | Note: Some URLs are protected by their | 277 | Note: Some URLs are protected by their |
| 276 | servers from anonymous download. For those URLs, the server must receive | 278 | servers from anonymous download. For those URLs, the server must receive |
| 277 | some sort of authentication along with the request or it will deny | 279 | some sort of authentication along with the request or it will deny |
| 278 | download and return status "401 Authentication Required". | 280 | download and return status "401 Authentication Required". |
| 279 | </p> | 281 | </p> |
| 280 | 282 | ||
| 281 | <p class=note> | 283 | <p class="note"> |
| 282 | The HTTP/1.1 standard defines two authentication methods: the Basic | 284 | The HTTP/1.1 standard defines two authentication methods: the Basic |
| 283 | Authentication Scheme and the Digest Authentication Scheme, both | 285 | Authentication Scheme and the Digest Authentication Scheme, both |
| 284 | explained in detail in | 286 | explained in detail in |
| 285 | <a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>. | 287 | <a href="http://www.ietf.org/rfc/rfc2068.txt">RFC 2068</a>. |
| 286 | </p> | 288 | </p> |
| 287 | 289 | ||
| 288 | <p class=note>The Basic Authentication Scheme sends | 290 | <p class="note">The Basic Authentication Scheme sends |
| 289 | <tt><user></tt> and | 291 | <tt><user></tt> and |
| 290 | <tt><password></tt> unencrypted to the server and is therefore | 292 | <tt><password></tt> unencrypted to the server and is therefore |
| 291 | considered unsafe. Unfortunately, by the time of this implementation, | 293 | considered unsafe. Unfortunately, by the time of this implementation, |
| @@ -294,7 +296,7 @@ Therefore, this is the method used by the toolkit whenever | |||
| 294 | authentication is required. | 296 | authentication is required. |
| 295 | </p> | 297 | </p> |
| 296 | 298 | ||
| 297 | <pre class=example> | 299 | <pre class="example"> |
| 298 | -- load required modules | 300 | -- load required modules |
| 299 | http = require("socket.http") | 301 | http = require("socket.http") |
| 300 | mime = require("mime") | 302 | mime = require("mime") |
| @@ -314,15 +316,15 @@ r, c = http.request { | |||
| 314 | 316 | ||
| 315 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 317 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 316 | 318 | ||
| 317 | <div class=footer> | 319 | <div class="footer"> |
| 318 | <hr> | 320 | <hr> |
| 319 | <center> | 321 | <center> |
| 320 | <p class=bar> | 322 | <p class="bar"> |
| 321 | <a href="index.html">home</a> · | 323 | <a href="index.html">home</a> · |
| 322 | <a href="index.html#download">download</a> · | 324 | <a href="index.html#download">download</a> · |
| 323 | <a href="installation.html">installation</a> · | 325 | <a href="installation.html">installation</a> · |
| 324 | <a href="introduction.html">introduction</a> · | 326 | <a href="introduction.html">introduction</a> · |
| 325 | <a href="reference.html">reference</a> | 327 | <a href="reference.html">reference</a> |
| 326 | </p> | 328 | </p> |
| 327 | <p> | 329 | <p> |
| 328 | <small> | 330 | <small> |
diff --git a/doc/index.html b/doc/index.html index 7d81b41..e92b4d4 100644 --- a/doc/index.html +++ b/doc/index.html | |||
| @@ -1,4 +1,4 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| @@ -13,22 +13,22 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| 30 | <a href="introduction.html">introduction</a> · | 30 | <a href="introduction.html">introduction</a> · |
| 31 | <a href="reference.html">reference</a> | 31 | <a href="reference.html">reference</a> |
| 32 | </p> | 32 | </p> |
| 33 | </center> | 33 | </center> |
| 34 | <hr> | 34 | <hr> |
| @@ -36,13 +36,13 @@ | |||
| 36 | 36 | ||
| 37 | <!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 37 | <!-- whatis +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 38 | 38 | ||
| 39 | <h2 id=whatis>What is LuaSocket?</h2> | 39 | <h2 id="whatis">What is LuaSocket?</h2> |
| 40 | 40 | ||
| 41 | <p> | 41 | <p> |
| 42 | LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library | 42 | LuaSocket is a <a href="http://www.lua.org">Lua</a> extension library |
| 43 | that is composed by two parts: a C core that provides support for the TCP | 43 | that is composed by two parts: a C core that provides support for the TCP |
| 44 | and UDP transport layers, and a set of Lua modules that add support for | 44 | and UDP transport layers, and a set of Lua modules that add support for |
| 45 | functionality commonly needed by applications that deal with the Internet. | 45 | functionality commonly needed by applications that deal with the Internet. |
| 46 | </p> | 46 | </p> |
| 47 | 47 | ||
| 48 | <p> | 48 | <p> |
| @@ -52,43 +52,43 @@ properly initialized by the interpreter in use. The code has been tested | |||
| 52 | and runs well on several Windows and UNIX platforms. </p> | 52 | and runs well on several Windows and UNIX platforms. </p> |
| 53 | 53 | ||
| 54 | <p> | 54 | <p> |
| 55 | Among the support modules, the most commonly used implement the | 55 | Among the support modules, the most commonly used implement the |
| 56 | <a href=smtp.html>SMTP</a> | 56 | <a href="smtp.html">SMTP</a> |
| 57 | (sending e-mails), | 57 | (sending e-mails), |
| 58 | <a href=http.html>HTTP</a> | 58 | <a href="http.html">HTTP</a> |
| 59 | (WWW access) and | 59 | (WWW access) and |
| 60 | <a href=ftp.html>FTP</a> | 60 | <a href="ftp.html">FTP</a> |
| 61 | (uploading and downloading files) client | 61 | (uploading and downloading files) client |
| 62 | protocols. These provide a very natural and generic interface to the | 62 | protocols. These provide a very natural and generic interface to the |
| 63 | functionality defined by each protocol. | 63 | functionality defined by each protocol. |
| 64 | In addition, you will find that the | 64 | In addition, you will find that the |
| 65 | <a href=mime.html>MIME</a> (common encodings), | 65 | <a href="mime.html">MIME</a> (common encodings), |
| 66 | <a href=url.html>URL</a> | 66 | <a href="url.html">URL</a> |
| 67 | (anything you could possible want to do with one) and | 67 | (anything you could possible want to do with one) and |
| 68 | <a href=ltn12.html>LTN12</a> | 68 | <a href="ltn12.html">LTN12</a> |
| 69 | (filters, sinks, sources and pumps) modules can be very handy. | 69 | (filters, sinks, sources and pumps) modules can be very handy. |
| 70 | </p> | 70 | </p> |
| 71 | 71 | ||
| 72 | <p> | 72 | <p> |
| 73 | The library is available under the same | 73 | The library is available under the same |
| 74 | <a href="http://www.lua.org/copyright.html"> | 74 | <a href="http://www.lua.org/copyright.html"> |
| 75 | terms and conditions</a> as the Lua language, the MIT license. The idea is | 75 | terms and conditions</a> as the Lua language, the MIT license. The idea is |
| 76 | that if you can use Lua in a project, you should also be able to use | 76 | that if you can use Lua in a project, you should also be able to use |
| 77 | LuaSocket. | 77 | LuaSocket. |
| 78 | </p> | 78 | </p> |
| 79 | 79 | ||
| 80 | <p> | 80 | <p> |
| 81 | Copyright © 1999-2013 Diego Nehab. All rights reserved. <br> | 81 | Copyright © 1999-2013 Diego Nehab. All rights reserved. <br> |
| 82 | Author: <A href="http://www.impa.br/~diego">Diego Nehab</a> | 82 | Author: <a href="http://www.impa.br/~diego">Diego Nehab</a> |
| 83 | </p> | 83 | </p> |
| 84 | 84 | ||
| 85 | <!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 85 | <!-- download +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 86 | 86 | ||
| 87 | <h2 id=download>Download</h2> | 87 | <h2 id="download">Download</h2> |
| 88 | 88 | ||
| 89 | <p> | 89 | <p> |
| 90 | LuaSocket version 3.0-rc1 is now available for download! | 90 | LuaSocket version 3.0-rc1 is now available for download! |
| 91 | It is compatible with Lua 5.1 and 5.2, and has | 91 | It is compatible with Lua 5.1 and 5.2, and has |
| 92 | been tested on Windows XP, Linux, and Mac OS X. Chances | 92 | been tested on Windows XP, Linux, and Mac OS X. Chances |
| 93 | are it works well on most UNIX distributions and Windows flavors. | 93 | are it works well on most UNIX distributions and Windows flavors. |
| 94 | </p> | 94 | </p> |
| @@ -96,19 +96,19 @@ are it works well on most UNIX distributions and Windows flavors. | |||
| 96 | <p> | 96 | <p> |
| 97 | The current version of the library can be found at | 97 | The current version of the library can be found at |
| 98 | the <a href="https://github.com/diegonehab/luasocket">LuaSocket | 98 | the <a href="https://github.com/diegonehab/luasocket">LuaSocket |
| 99 | project page</a> on GitHub. Besides the full C and Lua source code | 99 | project page</a> on GitHub. Besides the full C and Lua source code |
| 100 | for the library, the distribution contains several examples, | 100 | for the library, the distribution contains several examples, |
| 101 | this user's manual and basic test procedures. | 101 | this user's manual and basic test procedures. |
| 102 | </p> | 102 | </p> |
| 103 | 103 | ||
| 104 | <p> Take a look at the <a | 104 | <p> Take a look at the <a |
| 105 | href=installation.html>installation</a> section of the | 105 | href="installation.html">installation</a> section of the |
| 106 | manual to find out how to properly install the library. | 106 | manual to find out how to properly install the library. |
| 107 | </p> | 107 | </p> |
| 108 | 108 | ||
| 109 | <!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 109 | <!-- thanks +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 110 | 110 | ||
| 111 | <h2 id=thanks>Special thanks</h2> | 111 | <h2 id="thanks">Special thanks</h2> |
| 112 | 112 | ||
| 113 | <p> | 113 | <p> |
| 114 | This marks the first release of LuaSocket that | 114 | This marks the first release of LuaSocket that |
| @@ -118,85 +118,85 @@ convinced me it was time for a release including IPv6 and | |||
| 118 | Lua 5.2 support. It was more work than we anticipated. | 118 | Lua 5.2 support. It was more work than we anticipated. |
| 119 | Special thanks to Sam Roberts, Florian Zeitz, and Paul | 119 | Special thanks to Sam Roberts, Florian Zeitz, and Paul |
| 120 | Aurich, Liam Devine, Alexey Melnichuk, and everybody else | 120 | Aurich, Liam Devine, Alexey Melnichuk, and everybody else |
| 121 | that has helped bring this library back to life. | 121 | that has helped bring this library back to life. |
| 122 | </p> | 122 | </p> |
| 123 | 123 | ||
| 124 | <!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 124 | <!-- whatsnew +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 125 | 125 | ||
| 126 | <h2 id=new>What's New</h2> | 126 | <h2 id="new">What's New</h2> |
| 127 | 127 | ||
| 128 | <p> | 128 | <p> |
| 129 | Main changes for LuaSocket 3.0-rc1 are IPv6 support | 129 | Main changes for LuaSocket 3.0-rc1 are IPv6 support |
| 130 | and Lua 5.2 compatibility. | 130 | and Lua 5.2 compatibility. |
| 131 | </p> | 131 | </p> |
| 132 | 132 | ||
| 133 | <ul> | 133 | <ul> |
| 134 | <li> Added: Compatible with Lua 5.2 | 134 | <li> Added: Compatible with Lua 5.2</li> |
| 135 | <ul> | 135 | <ul> |
| 136 | <li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>, | 136 | <li> Note that unless you define <tt>LUA_COMPAT_MODULE</tt>, |
| 137 | package tables will <em>not</em> be exported as globals! | 137 | package tables will <em>not</em> be exported as globals!</li> |
| 138 | </ul> | 138 | </ul> |
| 139 | <li> Added: IPv6 support; | 139 | <li> Added: IPv6 support;</li> |
| 140 | <ul> | 140 | <ul> |
| 141 | <li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses; | 141 | <li> <tt>Socket.connect</tt> and <tt>socket.bind</tt> support IPv6 addresses;</li> |
| 142 | <li> <tt>Getpeername</tt> and <tt>getsockname</tt> support | 142 | <li> <tt>Getpeername</tt> and <tt>getsockname</tt> support |
| 143 | IPv6 addresses, and return the socket family as a third value; | 143 | IPv6 addresses, and return the socket family as a third value;</li> |
| 144 | <li> URL module updated to support IPv6 host names; | 144 | <li> URL module updated to support IPv6 host names;</li> |
| 145 | <li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions; | 145 | <li> New <tt>socket.tcp6</tt> and <tt>socket.udp6</tt> functions;</li> |
| 146 | <li> New <tt>socket.dns.getaddrinfo</tt> and | 146 | <li> New <tt>socket.dns.getaddrinfo</tt> and |
| 147 | <tt>socket.dns.getnameinfo</tt> functions; | 147 | <tt>socket.dns.getnameinfo</tt> functions;</li> |
| 148 | </ul> | 148 | </ul> |
| 149 | <li> Added: <tt>getoption</tt> method; | 149 | <li> Added: <tt>getoption</tt> method;</li> |
| 150 | <li> Fixed: <tt>url.unescape</tt> was returning additional values; | 150 | <li> Fixed: <tt>url.unescape</tt> was returning additional values;</li> |
| 151 | <li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>, | 151 | <li> Fixed: <tt>mime.qp</tt>, <tt>mime.unqp</tt>, |
| 152 | <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could | 152 | <tt>mime.b64</tt>, and <tt>mime.unb64</tt> could |
| 153 | mistaking their own stack slots for functions arguments; | 153 | mistaking their own stack slots for functions arguments;</li> |
| 154 | <li> Fixed: Receiving zero-length datagram is now possible; | 154 | <li> Fixed: Receiving zero-length datagram is now possible;</li> |
| 155 | <li> Improved: Hidden all internal library symbols; | 155 | <li> Improved: Hidden all internal library symbols;</li> |
| 156 | <li> Improved: Better error messages; | 156 | <li> Improved: Better error messages;</li> |
| 157 | <li> Improved: Better documentation of socket options. | 157 | <li> Improved: Better documentation of socket options.</li> |
| 158 | <li> Fixed: manual sample of HTTP authentication now uses correct | 158 | <li> Fixed: manual sample of HTTP authentication now uses correct |
| 159 | "authorization" header (Alexandre Ittner); | 159 | "authorization" header (Alexandre Ittner);</li> |
| 160 | <li> Fixed: failure on bind() was destroying the socket (Sam Roberts); | 160 | <li> Fixed: failure on bind() was destroying the socket (Sam Roberts);</li> |
| 161 | <li> Fixed: receive() returns immediatelly if prefix can satisfy | 161 | <li> Fixed: receive() returns immediatelly if prefix can satisfy |
| 162 | bytes requested (M Joonas Pihlaja); | 162 | bytes requested (M Joonas Pihlaja);</li> |
| 163 | <li> Fixed: multicast didn't work on Windows, or anywhere | 163 | <li> Fixed: multicast didn't work on Windows, or anywhere |
| 164 | else for that matter (Herbert Leuwer, Adrian Sietsma); | 164 | else for that matter (Herbert Leuwer, Adrian Sietsma);</li> |
| 165 | <li> Fixed: select() now reports an error when called with more | 165 | <li> Fixed: select() now reports an error when called with more |
| 166 | sockets than FD_SETSIZE (Lorenzo Leonini); | 166 | sockets than FD_SETSIZE (Lorenzo Leonini);</li> |
| 167 | <li> Fixed: manual links to home.html changed to index.html | 167 | <li> Fixed: manual links to home.html changed to index.html |
| 168 | (Robert Hahn); | 168 | (Robert Hahn);</li> |
| 169 | <li> Fixed: mime.unb64() would return an empty string on results that started | 169 | <li> Fixed: mime.unb64() would return an empty string on results that started |
| 170 | with a null character (Robert Raschke); | 170 | with a null character (Robert Raschke);</li> |
| 171 | <li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray); | 171 | <li> Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);</li> |
| 172 | <li> Fixed: calling sleep() with negative numbers could | 172 | <li> Fixed: calling sleep() with negative numbers could |
| 173 | block forever, wasting CPU. Now it returns immediately (MPB); | 173 | block forever, wasting CPU. Now it returns immediately (MPB);</li> |
| 174 | <li> Improved: FTP commands are now sent in upper case to | 174 | <li> Improved: FTP commands are now sent in upper case to |
| 175 | help buggy servers (Anders Eurenius); | 175 | help buggy servers (Anders Eurenius);</li> |
| 176 | <li> Improved: known headers now sent in canonic | 176 | <li> Improved: known headers now sent in canonic |
| 177 | capitalization to help buggy servers (Joseph Stewart); | 177 | capitalization to help buggy servers (Joseph Stewart);</li> |
| 178 | <li> Improved: Clarified tcp:receive() in the manual (MPB); | 178 | <li> Improved: Clarified tcp:receive() in the manual (MPB);</li> |
| 179 | <li> Improved: Decent makefiles (LHF). | 179 | <li> Improved: Decent makefiles (LHF).</li> |
| 180 | <li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei). | 180 | <li> Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).</li> |
| 181 | </ul> | 181 | </ul> |
| 182 | 182 | ||
| 183 | <!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 183 | <!-- old ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 184 | 184 | ||
| 185 | <h2 id=old>Old Versions</h2> | 185 | <h2 id="old">Old Versions</h2> |
| 186 | 186 | ||
| 187 | <p> | 187 | <p> |
| 188 | All previous versions of the LuaSocket library can be downloaded <a | 188 | All previous versions of the LuaSocket library can be downloaded <a |
| 189 | href="http://www.impa.br/~diego/software/luasocket/old"> | 189 | href="http://www.impa.br/~diego/software/luasocket/old"> |
| 190 | here</a>. Although these versions are no longer supported, they are | 190 | here</a>. Although these versions are no longer supported, they are |
| 191 | still available for those that have compatibility issues. | 191 | still available for those that have compatibility issues. |
| 192 | </p> | 192 | </p> |
| 193 | 193 | ||
| 194 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 194 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 195 | 195 | ||
| 196 | <div class=footer> | 196 | <div class="footer"> |
| 197 | <hr> | 197 | <hr> |
| 198 | <center> | 198 | <center> |
| 199 | <p class=bar> | 199 | <p class="bar"> |
| 200 | <a href="index.html#download">download</a> · | 200 | <a href="index.html#download">download</a> · |
| 201 | <a href="installation.html">installation</a> · | 201 | <a href="installation.html">installation</a> · |
| 202 | <a href="introduction.html">introduction</a> · | 202 | <a href="introduction.html">introduction</a> · |
diff --git a/doc/ltn12.html b/doc/ltn12.html index ee2502f..fe3e3a0 100644 --- a/doc/ltn12.html +++ b/doc/ltn12.html | |||
| @@ -1,4 +1,4 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| @@ -14,22 +14,22 @@ Pump, Support, Library"> | |||
| 14 | 14 | ||
| 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 16 | 16 | ||
| 17 | <div class=header> | 17 | <div class="header"> |
| 18 | <hr> | 18 | <hr> |
| 19 | <center> | 19 | <center> |
| 20 | <table summary="LuaSocket logo"> | 20 | <table summary="LuaSocket logo"> |
| 21 | <tr><td align=center><a href="http://www.lua.org"> | 21 | <tr><td align="center"><a href="http://www.lua.org"> |
| 22 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 22 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 23 | </a></td></tr> | 23 | </a></td></tr> |
| 24 | <tr><td align=center valign=top>Network support for the Lua language | 24 | <tr><td align="center" valign="top">Network support for the Lua language |
| 25 | </td></tr> | 25 | </td></tr> |
| 26 | </table> | 26 | </table> |
| 27 | <p class=bar> | 27 | <p class="bar"> |
| 28 | <a href="index.html">home</a> · | 28 | <a href="index.html">home</a> · |
| 29 | <a href="index.html#download">download</a> · | 29 | <a href="index.html#download">download</a> · |
| 30 | <a href="installation.html">installation</a> · | 30 | <a href="installation.html">installation</a> · |
| 31 | <a href="introduction.html">introduction</a> · | 31 | <a href="introduction.html">introduction</a> · |
| 32 | <a href="reference.html">reference</a> | 32 | <a href="reference.html">reference</a> |
| 33 | </p> | 33 | </p> |
| 34 | </center> | 34 | </center> |
| 35 | <hr> | 35 | <hr> |
| @@ -37,7 +37,7 @@ Pump, Support, Library"> | |||
| 37 | 37 | ||
| 38 | <!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 38 | <!-- ltn12 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 39 | 39 | ||
| 40 | <h2 id=ltn12>LTN12</h2> | 40 | <h2 id="ltn12">LTN12</h2> |
| 41 | 41 | ||
| 42 | <p> The <tt>ltn12</tt> namespace implements the ideas described in | 42 | <p> The <tt>ltn12</tt> namespace implements the ideas described in |
| 43 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> | 43 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> |
| @@ -46,11 +46,11 @@ functions. Please refer to the LTN for a deeper explanation of the | |||
| 46 | functionality provided by this module. | 46 | functionality provided by this module. |
| 47 | </p> | 47 | </p> |
| 48 | 48 | ||
| 49 | <p> | 49 | <p> |
| 50 | To obtain the <tt>ltn12</tt> namespace, run: | 50 | To obtain the <tt>ltn12</tt> namespace, run: |
| 51 | </p> | 51 | </p> |
| 52 | 52 | ||
| 53 | <pre class=example> | 53 | <pre class="example"> |
| 54 | -- loads the LTN21 module | 54 | -- loads the LTN21 module |
| 55 | local ltn12 = require("ltn12") | 55 | local ltn12 = require("ltn12") |
| 56 | </pre> | 56 | </pre> |
| @@ -61,32 +61,32 @@ local ltn12 = require("ltn12") | |||
| 61 | 61 | ||
| 62 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 62 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 63 | 63 | ||
| 64 | <p class=name id="filter.chain"> | 64 | <p class="name" id="filter.chain"> |
| 65 | ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> | 65 | ltn12.filter.<b>chain(</b>filter<sub>1</sub>, filter<sub>2</sub> |
| 66 | [, ... filter<sub>N</sub>]<b>)</b> | 66 | [, ... filter<sub>N</sub>]<b>)</b> |
| 67 | </p> | 67 | </p> |
| 68 | 68 | ||
| 69 | <p class=description> | 69 | <p class="description"> |
| 70 | Returns a filter that passes all data it receives through each of a | 70 | Returns a filter that passes all data it receives through each of a |
| 71 | series of given filters. | 71 | series of given filters. |
| 72 | </p> | 72 | </p> |
| 73 | 73 | ||
| 74 | <p class=parameters> | 74 | <p class="parameters"> |
| 75 | <tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple | 75 | <tt>Filter<sub>1</sub></tt> to <tt>filter<sub>N</sub></tt> are simple |
| 76 | filters. | 76 | filters. |
| 77 | </p> | 77 | </p> |
| 78 | 78 | ||
| 79 | <p class=return> | 79 | <p class="return"> |
| 80 | The function returns the chained filter. | 80 | The function returns the chained filter. |
| 81 | </p> | 81 | </p> |
| 82 | 82 | ||
| 83 | <p class=note> | 83 | <p class="note"> |
| 84 | The nesting of filters can be arbitrary. For instance, the useless filter | 84 | The nesting of filters can be arbitrary. For instance, the useless filter |
| 85 | below doesn't do anything but return the data that was passed to it, | 85 | below doesn't do anything but return the data that was passed to it, |
| 86 | unaltered. | 86 | unaltered. |
| 87 | </p> | 87 | </p> |
| 88 | 88 | ||
| 89 | <pre class=example> | 89 | <pre class="example"> |
| 90 | -- load required modules | 90 | -- load required modules |
| 91 | local ltn12 = require("ltn12") | 91 | local ltn12 = require("ltn12") |
| 92 | local mime = require("mime") | 92 | local mime = require("mime") |
| @@ -102,26 +102,26 @@ id = ltn12.filter.chain( | |||
| 102 | 102 | ||
| 103 | <!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 103 | <!-- cycle ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 104 | 104 | ||
| 105 | <p class=name id="filter.cycle"> | 105 | <p class="name" id="filter.cycle"> |
| 106 | ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b> | 106 | ltn12.filter.<b>cycle(</b>low [, ctx, extra]<b>)</b> |
| 107 | </p> | 107 | </p> |
| 108 | 108 | ||
| 109 | <p class=description> | 109 | <p class="description"> |
| 110 | Returns a high-level filter that cycles though a low-level filter by | 110 | Returns a high-level filter that cycles though a low-level filter by |
| 111 | passing it each chunk and updating a context between calls. | 111 | passing it each chunk and updating a context between calls. |
| 112 | </p> | 112 | </p> |
| 113 | 113 | ||
| 114 | <p class=parameters> | 114 | <p class="parameters"> |
| 115 | <tt>Low</tt> is the low-level filter to be cycled, | 115 | <tt>Low</tt> is the low-level filter to be cycled, |
| 116 | <tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra | 116 | <tt>ctx</tt> is the initial context and <tt>extra</tt> is any extra |
| 117 | argument the low-level filter might take. | 117 | argument the low-level filter might take. |
| 118 | </p> | 118 | </p> |
| 119 | 119 | ||
| 120 | <p class=return> | 120 | <p class="return"> |
| 121 | The function returns the high-level filter. | 121 | The function returns the high-level filter. |
| 122 | </p> | 122 | </p> |
| 123 | 123 | ||
| 124 | <pre class=example> | 124 | <pre class="example"> |
| 125 | -- load the ltn12 module | 125 | -- load the ltn12 module |
| 126 | local ltn12 = require("ltn12") | 126 | local ltn12 = require("ltn12") |
| 127 | 127 | ||
| @@ -137,15 +137,15 @@ end | |||
| 137 | 137 | ||
| 138 | <!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 138 | <!-- all ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 139 | 139 | ||
| 140 | <p class=name id="pump.all"> | 140 | <p class="name" id="pump.all"> |
| 141 | ltn12.pump.<b>all(</b>source, sink<b>)</b> | 141 | ltn12.pump.<b>all(</b>source, sink<b>)</b> |
| 142 | </p> | 142 | </p> |
| 143 | 143 | ||
| 144 | <p class=description> | 144 | <p class="description"> |
| 145 | Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. | 145 | Pumps <em>all</em> data from a <tt>source</tt> to a <tt>sink</tt>. |
| 146 | </p> | 146 | </p> |
| 147 | 147 | ||
| 148 | <p class=return> | 148 | <p class="return"> |
| 149 | If successful, the function returns a value that evaluates to | 149 | If successful, the function returns a value that evaluates to |
| 150 | <b><tt>true</tt></b>. In case | 150 | <b><tt>true</tt></b>. In case |
| 151 | of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. | 151 | of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. |
| @@ -153,15 +153,15 @@ of error, the function returns a <b><tt>false</tt></b> value, followed by an err | |||
| 153 | 153 | ||
| 154 | <!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 154 | <!-- step +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 155 | 155 | ||
| 156 | <p class=name id="pump.step"> | 156 | <p class="name" id="pump.step"> |
| 157 | ltn12.pump.<b>step(</b>source, sink<b>)</b> | 157 | ltn12.pump.<b>step(</b>source, sink<b>)</b> |
| 158 | </p> | 158 | </p> |
| 159 | 159 | ||
| 160 | <p class=description> | 160 | <p class="description"> |
| 161 | Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. | 161 | Pumps <em>one</em> chunk of data from a <tt>source</tt> to a <tt>sink</tt>. |
| 162 | </p> | 162 | </p> |
| 163 | 163 | ||
| 164 | <p class=return> | 164 | <p class="return"> |
| 165 | If successful, the function returns a value that evaluates to | 165 | If successful, the function returns a value that evaluates to |
| 166 | <b><tt>true</tt></b>. In case | 166 | <b><tt>true</tt></b>. In case |
| 167 | of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. | 167 | of error, the function returns a <b><tt>false</tt></b> value, followed by an error message. |
| @@ -173,52 +173,52 @@ of error, the function returns a <b><tt>false</tt></b> value, followed by an err | |||
| 173 | 173 | ||
| 174 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 174 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 175 | 175 | ||
| 176 | <p class=name id="sink.chain"> | 176 | <p class="name" id="sink.chain"> |
| 177 | ltn12.sink.<b>chain(</b>filter, sink<b>)</b> | 177 | ltn12.sink.<b>chain(</b>filter, sink<b>)</b> |
| 178 | </p> | 178 | </p> |
| 179 | 179 | ||
| 180 | <p class=description> | 180 | <p class="description"> |
| 181 | Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>. | 181 | Creates and returns a new sink that passes data through a <tt>filter</tt> before sending it to a given <tt>sink</tt>. |
| 182 | </p> | 182 | </p> |
| 183 | 183 | ||
| 184 | <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 184 | <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 185 | 185 | ||
| 186 | <p class=name id="sink.error"> | 186 | <p class="name" id="sink.error"> |
| 187 | ltn12.sink.<b>error(</b>message<b>)</b> | 187 | ltn12.sink.<b>error(</b>message<b>)</b> |
| 188 | </p> | 188 | </p> |
| 189 | 189 | ||
| 190 | <p class=description> | 190 | <p class="description"> |
| 191 | Creates and returns a sink that aborts transmission with the error | 191 | Creates and returns a sink that aborts transmission with the error |
| 192 | <tt>message</tt>. | 192 | <tt>message</tt>. |
| 193 | </p> | 193 | </p> |
| 194 | 194 | ||
| 195 | <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 195 | <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 196 | 196 | ||
| 197 | <p class=name id="sink.file"> | 197 | <p class="name" id="sink.file"> |
| 198 | ltn12.sink.<b>file(</b>handle, message<b>)</b> | 198 | ltn12.sink.<b>file(</b>handle, message<b>)</b> |
| 199 | </p> | 199 | </p> |
| 200 | 200 | ||
| 201 | <p class=description> | 201 | <p class="description"> |
| 202 | Creates a sink that sends data to a file. | 202 | Creates a sink that sends data to a file. |
| 203 | </p> | 203 | </p> |
| 204 | 204 | ||
| 205 | <p class=parameters> | 205 | <p class="parameters"> |
| 206 | <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, | 206 | <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, |
| 207 | <tt>message</tt> should give the reason for failure. | 207 | <tt>message</tt> should give the reason for failure. |
| 208 | </p> | 208 | </p> |
| 209 | 209 | ||
| 210 | <p class=return> | 210 | <p class="return"> |
| 211 | The function returns a sink that sends all data to the given <tt>handle</tt> | 211 | The function returns a sink that sends all data to the given <tt>handle</tt> |
| 212 | and closes the file when done, or a sink that aborts the transmission with | 212 | and closes the file when done, or a sink that aborts the transmission with |
| 213 | the error <tt>message</tt> | 213 | the error <tt>message</tt> |
| 214 | </p> | 214 | </p> |
| 215 | 215 | ||
| 216 | <p class=note> | 216 | <p class="note"> |
| 217 | In the following example, notice how the prototype is designed to | 217 | In the following example, notice how the prototype is designed to |
| 218 | fit nicely with the <tt>io.open</tt> function. | 218 | fit nicely with the <tt>io.open</tt> function. |
| 219 | </p> | 219 | </p> |
| 220 | 220 | ||
| 221 | <pre class=example> | 221 | <pre class="example"> |
| 222 | -- load the ltn12 module | 222 | -- load the ltn12 module |
| 223 | local ltn12 = require("ltn12") | 223 | local ltn12 = require("ltn12") |
| 224 | 224 | ||
| @@ -231,45 +231,45 @@ ltn12.pump.all( | |||
| 231 | 231 | ||
| 232 | <!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 232 | <!-- null +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 233 | 233 | ||
| 234 | <p class=name id="sink.null"> | 234 | <p class="name" id="sink.null"> |
| 235 | ltn12.sink.<b>null()</b> | 235 | ltn12.sink.<b>null()</b> |
| 236 | </p> | 236 | </p> |
| 237 | 237 | ||
| 238 | <p class=description> | 238 | <p class="description"> |
| 239 | Returns a sink that ignores all data it receives. | 239 | Returns a sink that ignores all data it receives. |
| 240 | </p> | 240 | </p> |
| 241 | 241 | ||
| 242 | <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 242 | <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 243 | 243 | ||
| 244 | <p class=name id="sink.simplify"> | 244 | <p class="name" id="sink.simplify"> |
| 245 | ltn12.sink.<b>simplify(</b>sink<b>)</b> | 245 | ltn12.sink.<b>simplify(</b>sink<b>)</b> |
| 246 | </p> | 246 | </p> |
| 247 | 247 | ||
| 248 | <p class=description> | 248 | <p class="description"> |
| 249 | Creates and returns a simple sink given a fancy <tt>sink</tt>. | 249 | Creates and returns a simple sink given a fancy <tt>sink</tt>. |
| 250 | </p> | 250 | </p> |
| 251 | 251 | ||
| 252 | <!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 252 | <!-- table ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 253 | 253 | ||
| 254 | <p class=name id="sink.table"> | 254 | <p class="name" id="sink.table"> |
| 255 | ltn12.sink.<b>table(</b>[table]<b>)</b> | 255 | ltn12.sink.<b>table(</b>[table]<b>)</b> |
| 256 | </p> | 256 | </p> |
| 257 | 257 | ||
| 258 | <p class=description> | 258 | <p class="description"> |
| 259 | Creates a sink that stores all chunks in a table. The chunks can later be | 259 | Creates a sink that stores all chunks in a table. The chunks can later be |
| 260 | efficiently concatenated into a single string. | 260 | efficiently concatenated into a single string. |
| 261 | </p> | 261 | </p> |
| 262 | 262 | ||
| 263 | <p class=parameters> | 263 | <p class="parameters"> |
| 264 | <tt>Table</tt> is used to hold the chunks. If | 264 | <tt>Table</tt> is used to hold the chunks. If |
| 265 | <tt><b>nil</b></tt>, the function creates its own table. | 265 | <tt><b>nil</b></tt>, the function creates its own table. |
| 266 | </p> | 266 | </p> |
| 267 | 267 | ||
| 268 | <p class=return> | 268 | <p class="return"> |
| 269 | The function returns the sink and the table used to store the chunks. | 269 | The function returns the sink and the table used to store the chunks. |
| 270 | </p> | 270 | </p> |
| 271 | 271 | ||
| 272 | <pre class=example> | 272 | <pre class="example"> |
| 273 | -- load needed modules | 273 | -- load needed modules |
| 274 | local http = require("socket.http") | 274 | local http = require("socket.http") |
| 275 | local ltn12 = require("ltn12") | 275 | local ltn12 = require("ltn12") |
| @@ -291,89 +291,89 @@ end | |||
| 291 | 291 | ||
| 292 | <!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 292 | <!-- cat ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 293 | 293 | ||
| 294 | <p class=name id="source.cat"> | 294 | <p class="name" id="source.cat"> |
| 295 | ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ..., | 295 | ltn12.source.<b>cat(</b>source<sub>1</sub> [, source<sub>2</sub>, ..., |
| 296 | source<sub>N</sub>]<b>)</b> | 296 | source<sub>N</sub>]<b>)</b> |
| 297 | </p> | 297 | </p> |
| 298 | 298 | ||
| 299 | <p class=description> | 299 | <p class="description"> |
| 300 | Creates a new source that produces the concatenation of the data produced | 300 | Creates a new source that produces the concatenation of the data produced |
| 301 | by a number of sources. | 301 | by a number of sources. |
| 302 | </p> | 302 | </p> |
| 303 | 303 | ||
| 304 | <p class=parameters> | 304 | <p class="parameters"> |
| 305 | <tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original | 305 | <tt>Source<sub>1</sub></tt> to <tt>source<sub>N</sub></tt> are the original |
| 306 | sources. | 306 | sources. |
| 307 | </p> | 307 | </p> |
| 308 | 308 | ||
| 309 | <p class=return> | 309 | <p class="return"> |
| 310 | The function returns the new source. | 310 | The function returns the new source. |
| 311 | </p> | 311 | </p> |
| 312 | 312 | ||
| 313 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 313 | <!-- chain ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 314 | 314 | ||
| 315 | <p class=name id="source.chain"> | 315 | <p class="name" id="source.chain"> |
| 316 | ltn12.source.<b>chain(</b>source, filter<b>)</b> | 316 | ltn12.source.<b>chain(</b>source, filter<b>)</b> |
| 317 | </p> | 317 | </p> |
| 318 | 318 | ||
| 319 | <p class=description> | 319 | <p class="description"> |
| 320 | Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> | 320 | Creates a new <tt>source</tt> that passes data through a <tt>filter</tt> |
| 321 | before returning it. | 321 | before returning it. |
| 322 | </p> | 322 | </p> |
| 323 | 323 | ||
| 324 | <p class=return> | 324 | <p class="return"> |
| 325 | The function returns the new source. | 325 | The function returns the new source. |
| 326 | </p> | 326 | </p> |
| 327 | 327 | ||
| 328 | <!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 328 | <!-- empty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 329 | 329 | ||
| 330 | <p class=name id="source.empty"> | 330 | <p class="name" id="source.empty"> |
| 331 | ltn12.source.<b>empty()</b> | 331 | ltn12.source.<b>empty()</b> |
| 332 | </p> | 332 | </p> |
| 333 | 333 | ||
| 334 | <p class=description> | 334 | <p class="description"> |
| 335 | Creates and returns an empty source. | 335 | Creates and returns an empty source. |
| 336 | </p> | 336 | </p> |
| 337 | 337 | ||
| 338 | <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 338 | <!-- error ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 339 | 339 | ||
| 340 | <p class=name id="source.error"> | 340 | <p class="name" id="source.error"> |
| 341 | ltn12.source.<b>error(</b>message<b>)</b> | 341 | ltn12.source.<b>error(</b>message<b>)</b> |
| 342 | </p> | 342 | </p> |
| 343 | 343 | ||
| 344 | <p class=description> | 344 | <p class="description"> |
| 345 | Creates and returns a source that aborts transmission with the error | 345 | Creates and returns a source that aborts transmission with the error |
| 346 | <tt>message</tt>. | 346 | <tt>message</tt>. |
| 347 | </p> | 347 | </p> |
| 348 | 348 | ||
| 349 | <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 349 | <!-- file +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 350 | 350 | ||
| 351 | <p class=name id="source.file"> | 351 | <p class="name" id="source.file"> |
| 352 | ltn12.source.<b>file(</b>handle, message<b>)</b> | 352 | ltn12.source.<b>file(</b>handle, message<b>)</b> |
| 353 | </p> | 353 | </p> |
| 354 | 354 | ||
| 355 | <p class=description> | 355 | <p class="description"> |
| 356 | Creates a source that produces the contents of a file. | 356 | Creates a source that produces the contents of a file. |
| 357 | </p> | 357 | </p> |
| 358 | 358 | ||
| 359 | <p class=parameters> | 359 | <p class="parameters"> |
| 360 | <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, | 360 | <tt>Handle</tt> is a file handle. If <tt>handle</tt> is <tt><b>nil</b></tt>, |
| 361 | <tt>message</tt> should give the reason for failure. | 361 | <tt>message</tt> should give the reason for failure. |
| 362 | </p> | 362 | </p> |
| 363 | 363 | ||
| 364 | <p class=return> | 364 | <p class="return"> |
| 365 | The function returns a source that reads chunks of data from | 365 | The function returns a source that reads chunks of data from |
| 366 | given <tt>handle</tt> and returns it to the user, | 366 | given <tt>handle</tt> and returns it to the user, |
| 367 | closing the file when done, or a source that aborts the transmission with | 367 | closing the file when done, or a source that aborts the transmission with |
| 368 | the error <tt>message</tt> | 368 | the error <tt>message</tt> |
| 369 | </p> | 369 | </p> |
| 370 | 370 | ||
| 371 | <p class=note> | 371 | <p class="note"> |
| 372 | In the following example, notice how the prototype is designed to | 372 | In the following example, notice how the prototype is designed to |
| 373 | fit nicely with the <tt>io.open</tt> function. | 373 | fit nicely with the <tt>io.open</tt> function. |
| 374 | </p> | 374 | </p> |
| 375 | 375 | ||
| 376 | <pre class=example> | 376 | <pre class="example"> |
| 377 | -- load the ltn12 module | 377 | -- load the ltn12 module |
| 378 | local ltn12 = require("ltn12") | 378 | local ltn12 = require("ltn12") |
| 379 | 379 | ||
| @@ -386,41 +386,41 @@ ltn12.pump.all( | |||
| 386 | 386 | ||
| 387 | <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 387 | <!-- simplify +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 388 | 388 | ||
| 389 | <p class=name id="source.simplify"> | 389 | <p class="name" id="source.simplify"> |
| 390 | ltn12.source.<b>simplify(</b>source<b>)</b> | 390 | ltn12.source.<b>simplify(</b>source<b>)</b> |
| 391 | </p> | 391 | </p> |
| 392 | 392 | ||
| 393 | <p class=description> | 393 | <p class="description"> |
| 394 | Creates and returns a simple source given a fancy <tt>source</tt>. | 394 | Creates and returns a simple source given a fancy <tt>source</tt>. |
| 395 | </p> | 395 | </p> |
| 396 | 396 | ||
| 397 | <!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 397 | <!-- string +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 398 | 398 | ||
| 399 | <p class=name id="source.string"> | 399 | <p class="name" id="source.string"> |
| 400 | ltn12.source.<b>string(</b>string<b>)</b> | 400 | ltn12.source.<b>string(</b>string<b>)</b> |
| 401 | </p> | 401 | </p> |
| 402 | 402 | ||
| 403 | <p class=description> | 403 | <p class="description"> |
| 404 | Creates and returns a source that produces the contents of a | 404 | Creates and returns a source that produces the contents of a |
| 405 | <tt>string</tt>, chunk by chunk. | 405 | <tt>string</tt>, chunk by chunk. |
| 406 | </p> | 406 | </p> |
| 407 | 407 | ||
| 408 | <!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 408 | <!-- table +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 409 | 409 | ||
| 410 | <p class=name id="source.table"> | 410 | <p class="name" id="source.table"> |
| 411 | ltn12.source.<b>table(</b>table<b>)</b> | 411 | ltn12.source.<b>table(</b>table<b>)</b> |
| 412 | </p> | 412 | </p> |
| 413 | 413 | ||
| 414 | <p class=description> | 414 | <p class="description"> |
| 415 | Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless. | 415 | Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1. The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless. |
| 416 | </p> | 416 | </p> |
| 417 | 417 | ||
| 418 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 418 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 419 | 419 | ||
| 420 | <div class=footer> | 420 | <div class="footer"> |
| 421 | <hr> | 421 | <hr> |
| 422 | <center> | 422 | <center> |
| 423 | <p class=bar> | 423 | <p class="bar"> |
| 424 | <a href="index.html">home</a> · | 424 | <a href="index.html">home</a> · |
| 425 | <a href="index.html#down">download</a> · | 425 | <a href="index.html#down">download</a> · |
| 426 | <a href="installation.html">installation</a> · | 426 | <a href="installation.html">installation</a> · |
diff --git a/doc/mime.html b/doc/mime.html index 8cb3507..ff4d8e8 100644 --- a/doc/mime.html +++ b/doc/mime.html | |||
| @@ -1,10 +1,10 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| 5 | <head> | 5 | <head> |
| 6 | <meta name="description" content="LuaSocket: MIME support"> | 6 | <meta name="description" content="LuaSocket: MIME support"> |
| 7 | <meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support"> | 7 | <meta name="keywords" content="Lua, LuaSocket, MIME, Library, Support"> |
| 8 | <title>LuaSocket: MIME module</title> | 8 | <title>LuaSocket: MIME module</title> |
| 9 | <link rel="stylesheet" href="reference.css" type="text/css"> | 9 | <link rel="stylesheet" href="reference.css" type="text/css"> |
| 10 | </head> | 10 | </head> |
| @@ -13,22 +13,22 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| 30 | <a href="introduction.html">introduction</a> · | 30 | <a href="introduction.html">introduction</a> · |
| 31 | <a href="reference.html">reference</a> | 31 | <a href="reference.html">reference</a> |
| 32 | </p> | 32 | </p> |
| 33 | </center> | 33 | </center> |
| 34 | <hr> | 34 | <hr> |
| @@ -36,14 +36,14 @@ | |||
| 36 | 36 | ||
| 37 | <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 37 | <!-- mime +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 38 | 38 | ||
| 39 | <h2 id=mime>MIME</h2> | 39 | <h2 id="mime">MIME</h2> |
| 40 | 40 | ||
| 41 | <p> | 41 | <p> |
| 42 | The <tt>mime</tt> namespace offers filters that apply and remove common | 42 | The <tt>mime</tt> namespace offers filters that apply and remove common |
| 43 | content transfer encodings, such as Base64 and Quoted-Printable. | 43 | content transfer encodings, such as Base64 and Quoted-Printable. |
| 44 | It also provides functions to break text into lines and change | 44 | It also provides functions to break text into lines and change |
| 45 | the end-of-line convention. | 45 | the end-of-line convention. |
| 46 | MIME is described mainly in | 46 | MIME is described mainly in |
| 47 | <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>, | 47 | <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>, |
| 48 | <a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>, | 48 | <a href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>, |
| 49 | <a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>, | 49 | <a href="http://www.ietf.org/rfc/rfc2047.txt">2047</a>, |
| @@ -52,17 +52,17 @@ MIME is described mainly in | |||
| 52 | </p> | 52 | </p> |
| 53 | 53 | ||
| 54 | <p> | 54 | <p> |
| 55 | All functionality provided by the MIME module | 55 | All functionality provided by the MIME module |
| 56 | follows the ideas presented in | 56 | follows the ideas presented in |
| 57 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> | 57 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> |
| 58 | LTN012, Filters sources and sinks</a>. | 58 | LTN012, Filters sources and sinks</a>. |
| 59 | </p> | 59 | </p> |
| 60 | 60 | ||
| 61 | <p> | 61 | <p> |
| 62 | To obtain the <tt>mime</tt> namespace, run: | 62 | To obtain the <tt>mime</tt> namespace, run: |
| 63 | </p> | 63 | </p> |
| 64 | 64 | ||
| 65 | <pre class=example> | 65 | <pre class="example"> |
| 66 | -- loads the MIME module and everything it requires | 66 | -- loads the MIME module and everything it requires |
| 67 | local mime = require("mime") | 67 | local mime = require("mime") |
| 68 | </pre> | 68 | </pre> |
| @@ -70,60 +70,60 @@ local mime = require("mime") | |||
| 70 | 70 | ||
| 71 | <!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 71 | <!-- High-level +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 72 | 72 | ||
| 73 | <h3 id=high>High-level filters</h3> | 73 | <h3 id="high">High-level filters</h3> |
| 74 | 74 | ||
| 75 | 75 | ||
| 76 | <!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 76 | <!-- decode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 77 | 77 | ||
| 78 | <p class=name id="decode"> | 78 | <p class="name" id="decode"> |
| 79 | mime.<b>decode(</b>"base64"<b>)</b><br> | 79 | mime.<b>decode(</b>"base64"<b>)</b><br> |
| 80 | mime.<b>decode(</b>"quoted-printable"<b>)</b> | 80 | mime.<b>decode(</b>"quoted-printable"<b>)</b> |
| 81 | </p> | 81 | </p> |
| 82 | 82 | ||
| 83 | <p class=description> | 83 | <p class="description"> |
| 84 | Returns a filter that decodes data from a given transfer content | 84 | Returns a filter that decodes data from a given transfer content |
| 85 | encoding. | 85 | encoding. |
| 86 | </p> | 86 | </p> |
| 87 | 87 | ||
| 88 | <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 88 | <!-- encode +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 89 | 89 | ||
| 90 | <p class=name id="encode"> | 90 | <p class="name" id="encode"> |
| 91 | mime.<b>encode(</b>"base64"<b>)</b><br> | 91 | mime.<b>encode(</b>"base64"<b>)</b><br> |
| 92 | mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b> | 92 | mime.<b>encode(</b>"quoted-printable" [, mode]<b>)</b> |
| 93 | </p> | 93 | </p> |
| 94 | 94 | ||
| 95 | <p class=description> | 95 | <p class="description"> |
| 96 | Returns a filter that encodes data according to a given transfer content | 96 | Returns a filter that encodes data according to a given transfer content |
| 97 | encoding. | 97 | encoding. |
| 98 | </p> | 98 | </p> |
| 99 | 99 | ||
| 100 | <p class=parameters> | 100 | <p class="parameters"> |
| 101 | In the Quoted-Printable case, the user can specify whether the data is | 101 | In the Quoted-Printable case, the user can specify whether the data is |
| 102 | textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or | 102 | textual or binary, by passing the <tt>mode</tt> strings "<tt>text</tt>" or |
| 103 | "<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>". | 103 | "<tt>binary</tt>". <tt>Mode</tt> defaults to "<tt>text</tt>". |
| 104 | </p> | 104 | </p> |
| 105 | 105 | ||
| 106 | <p class=note> | 106 | <p class="note"> |
| 107 | Although both transfer content encodings specify a limit for the line | 107 | Although both transfer content encodings specify a limit for the line |
| 108 | length, the encoding filters do <em>not</em> break text into lines (for | 108 | length, the encoding filters do <em>not</em> break text into lines (for |
| 109 | added flexibility). | 109 | added flexibility). |
| 110 | Below is a filter that converts binary data to the Base64 transfer content | 110 | Below is a filter that converts binary data to the Base64 transfer content |
| 111 | encoding and breaks it into lines of the correct size. | 111 | encoding and breaks it into lines of the correct size. |
| 112 | </p> | 112 | </p> |
| 113 | 113 | ||
| 114 | <pre class=example> | 114 | <pre class="example"> |
| 115 | base64 = ltn12.filter.chain( | 115 | base64 = ltn12.filter.chain( |
| 116 | mime.encode("base64"), | 116 | mime.encode("base64"), |
| 117 | mime.wrap("base64") | 117 | mime.wrap("base64") |
| 118 | ) | 118 | ) |
| 119 | </pre> | 119 | </pre> |
| 120 | 120 | ||
| 121 | <p class=note> | 121 | <p class="note"> |
| 122 | Note: Text data <em>has</em> to be converted to canonic form | 122 | Note: Text data <em>has</em> to be converted to canonic form |
| 123 | <em>before</em> being encoded. | 123 | <em>before</em> being encoded. |
| 124 | </p> | 124 | </p> |
| 125 | 125 | ||
| 126 | <pre class=example> | 126 | <pre class="example"> |
| 127 | base64 = ltn12.filter.chain( | 127 | base64 = ltn12.filter.chain( |
| 128 | mime.normalize(), | 128 | mime.normalize(), |
| 129 | mime.encode("base64"), | 129 | mime.encode("base64"), |
| @@ -133,77 +133,77 @@ base64 = ltn12.filter.chain( | |||
| 133 | 133 | ||
| 134 | <!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 134 | <!-- normalize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 135 | 135 | ||
| 136 | <p class=name id="normalize"> | 136 | <p class="name" id="normalize"> |
| 137 | mime.<b>normalize(</b>[marker]<b>)</b> | 137 | mime.<b>normalize(</b>[marker]<b>)</b> |
| 138 | </p> | 138 | </p> |
| 139 | 139 | ||
| 140 | <p class=description> | 140 | <p class="description"> |
| 141 | Converts most common end-of-line markers to a specific given marker. | 141 | Converts most common end-of-line markers to a specific given marker. |
| 142 | </p> | 142 | </p> |
| 143 | 143 | ||
| 144 | <p class=parameters> | 144 | <p class="parameters"> |
| 145 | <tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic | 145 | <tt>Marker</tt> is the new marker. It defaults to CRLF, the canonic |
| 146 | end-of-line marker defined by the MIME standard. | 146 | end-of-line marker defined by the MIME standard. |
| 147 | </p> | 147 | </p> |
| 148 | 148 | ||
| 149 | <p class=return> | 149 | <p class="return"> |
| 150 | The function returns a filter that performs the conversion. | 150 | The function returns a filter that performs the conversion. |
| 151 | </p> | 151 | </p> |
| 152 | 152 | ||
| 153 | <p class=note> | 153 | <p class="note"> |
| 154 | Note: There is no perfect solution to this problem. Different end-of-line | 154 | Note: There is no perfect solution to this problem. Different end-of-line |
| 155 | markers are an evil that will probably plague developers forever. | 155 | markers are an evil that will probably plague developers forever. |
| 156 | This function, however, will work perfectly for text created with any of | 156 | This function, however, will work perfectly for text created with any of |
| 157 | the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), | 157 | the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), |
| 158 | or the DOS (CRLF) conventions. Even if the data has mixed end-of-line | 158 | or the DOS (CRLF) conventions. Even if the data has mixed end-of-line |
| 159 | markers, the function will still work well, although it doesn't | 159 | markers, the function will still work well, although it doesn't |
| 160 | guarantee that the number of empty lines will be correct. | 160 | guarantee that the number of empty lines will be correct. |
| 161 | </p> | 161 | </p> |
| 162 | 162 | ||
| 163 | <!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 163 | <!-- stuff +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 164 | 164 | ||
| 165 | <p class=name id="stuff"> | 165 | <p class="name" id="stuff"> |
| 166 | mime.<b>stuff()</b><br> | 166 | mime.<b>stuff()</b><br> |
| 167 | </p> | 167 | </p> |
| 168 | 168 | ||
| 169 | <p class=description> | 169 | <p class="description"> |
| 170 | Creates and returns a filter that performs stuffing of SMTP messages. | 170 | Creates and returns a filter that performs stuffing of SMTP messages. |
| 171 | </p> | 171 | </p> |
| 172 | 172 | ||
| 173 | <p class=note> | 173 | <p class="note"> |
| 174 | Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function | 174 | Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function |
| 175 | uses this filter automatically. You don't need to chain it with your | 175 | uses this filter automatically. You don't need to chain it with your |
| 176 | source, or apply it to your message body. | 176 | source, or apply it to your message body. |
| 177 | </p> | 177 | </p> |
| 178 | 178 | ||
| 179 | <!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 179 | <!-- wrap +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 180 | 180 | ||
| 181 | <p class=name id="wrap"> | 181 | <p class="name" id="wrap"> |
| 182 | mime.<b>wrap(</b>"text" [, length]<b>)</b><br> | 182 | mime.<b>wrap(</b>"text" [, length]<b>)</b><br> |
| 183 | mime.<b>wrap(</b>"base64"<b>)</b><br> | 183 | mime.<b>wrap(</b>"base64"<b>)</b><br> |
| 184 | mime.<b>wrap(</b>"quoted-printable"<b>)</b> | 184 | mime.<b>wrap(</b>"quoted-printable"<b>)</b> |
| 185 | </p> | 185 | </p> |
| 186 | 186 | ||
| 187 | <p class=description> | 187 | <p class="description"> |
| 188 | Returns a filter that breaks data into lines. | 188 | Returns a filter that breaks data into lines. |
| 189 | </p> | 189 | </p> |
| 190 | 190 | ||
| 191 | <p class=parameters> | 191 | <p class="parameters"> |
| 192 | The "<tt>text</tt>" line-wrap filter simply breaks text into lines by | 192 | The "<tt>text</tt>" line-wrap filter simply breaks text into lines by |
| 193 | inserting CRLF end-of-line markers at appropriate positions. | 193 | inserting CRLF end-of-line markers at appropriate positions. |
| 194 | <tt>Length</tt> defaults 76. | 194 | <tt>Length</tt> defaults 76. |
| 195 | The "<tt>base64</tt>" line-wrap filter works just like the default | 195 | The "<tt>base64</tt>" line-wrap filter works just like the default |
| 196 | "<tt>text</tt>" line-wrap filter with default length. | 196 | "<tt>text</tt>" line-wrap filter with default length. |
| 197 | The function can also wrap "<tt>quoted-printable</tt>" lines, taking care | 197 | The function can also wrap "<tt>quoted-printable</tt>" lines, taking care |
| 198 | not to break lines in the middle of an escaped character. In that case, the | 198 | not to break lines in the middle of an escaped character. In that case, the |
| 199 | line length is fixed at 76. | 199 | line length is fixed at 76. |
| 200 | </p> | 200 | </p> |
| 201 | 201 | ||
| 202 | <p class=note> | 202 | <p class="note"> |
| 203 | For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following: | 203 | For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following: |
| 204 | </p> | 204 | </p> |
| 205 | 205 | ||
| 206 | <pre class=example> | 206 | <pre class="example"> |
| 207 | qp = ltn12.filter.chain( | 207 | qp = ltn12.filter.chain( |
| 208 | mime.normalize(), | 208 | mime.normalize(), |
| 209 | mime.encode("quoted-printable"), | 209 | mime.encode("quoted-printable"), |
| @@ -211,155 +211,155 @@ qp = ltn12.filter.chain( | |||
| 211 | ) | 211 | ) |
| 212 | </pre> | 212 | </pre> |
| 213 | 213 | ||
| 214 | <p class=note> | 214 | <p class="note"> |
| 215 | Note: To break into lines with a different end-of-line convention, apply | 215 | Note: To break into lines with a different end-of-line convention, apply |
| 216 | a normalization filter after the line break filter. | 216 | a normalization filter after the line break filter. |
| 217 | </p> | 217 | </p> |
| 218 | 218 | ||
| 219 | <!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 219 | <!-- Low-level ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 220 | 220 | ||
| 221 | <h3 id=low>Low-level filters</h3> | 221 | <h3 id="low">Low-level filters</h3> |
| 222 | 222 | ||
| 223 | <!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 223 | <!-- b64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 224 | 224 | ||
| 225 | <p class=name id="b64"> | 225 | <p class="name" id="b64"> |
| 226 | A, B = mime.<b>b64(</b>C [, D]<b>)</b> | 226 | A, B = mime.<b>b64(</b>C [, D]<b>)</b> |
| 227 | </p> | 227 | </p> |
| 228 | 228 | ||
| 229 | <p class=description> | 229 | <p class="description"> |
| 230 | Low-level filter to perform Base64 encoding. | 230 | Low-level filter to perform Base64 encoding. |
| 231 | </p> | 231 | </p> |
| 232 | 232 | ||
| 233 | <p class=description> | 233 | <p class="description"> |
| 234 | <tt>A</tt> is the encoded version of the largest prefix of | 234 | <tt>A</tt> is the encoded version of the largest prefix of |
| 235 | <tt>C..D</tt> | 235 | <tt>C..D</tt> |
| 236 | that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of | 236 | that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of |
| 237 | <tt>C..D</tt>, <em>before</em> encoding. | 237 | <tt>C..D</tt>, <em>before</em> encoding. |
| 238 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with | 238 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with |
| 239 | the encoding of the remaining bytes of <tt>C</tt>. | 239 | the encoding of the remaining bytes of <tt>C</tt>. |
| 240 | </p> | 240 | </p> |
| 241 | 241 | ||
| 242 | <p class=note> | 242 | <p class="note"> |
| 243 | Note: The simplest use of this function is to encode a string into it's | 243 | Note: The simplest use of this function is to encode a string into it's |
| 244 | Base64 transfer content encoding. Notice the extra parenthesis around the | 244 | Base64 transfer content encoding. Notice the extra parenthesis around the |
| 245 | call to <tt>mime.b64</tt>, to discard the second return value. | 245 | call to <tt>mime.b64</tt>, to discard the second return value. |
| 246 | </p> | 246 | </p> |
| 247 | 247 | ||
| 248 | <pre class=example> | 248 | <pre class="example"> |
| 249 | print((mime.b64("diego:password"))) | 249 | print((mime.b64("diego:password"))) |
| 250 | --> ZGllZ286cGFzc3dvcmQ= | 250 | --> ZGllZ286cGFzc3dvcmQ= |
| 251 | </pre> | 251 | </pre> |
| 252 | 252 | ||
| 253 | <!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 253 | <!-- dot +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 254 | <p class=name id="dot"> | 254 | <p class="name" id="dot"> |
| 255 | A, n = mime.<b>dot(</b>m [, B]<b>)</b> | 255 | A, n = mime.<b>dot(</b>m [, B]<b>)</b> |
| 256 | </p> | 256 | </p> |
| 257 | 257 | ||
| 258 | <p class=description> | 258 | <p class="description"> |
| 259 | Low-level filter to perform SMTP stuffing and enable transmission of | 259 | Low-level filter to perform SMTP stuffing and enable transmission of |
| 260 | messages containing the sequence "CRLF.CRLF". | 260 | messages containing the sequence "CRLF.CRLF". |
| 261 | </p> | 261 | </p> |
| 262 | 262 | ||
| 263 | <p class=parameters> | 263 | <p class="parameters"> |
| 264 | <tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the | 264 | <tt>A</tt> is the stuffed version of <tt>B</tt>. '<tt>n</tt>' gives the |
| 265 | number of characters from the sequence CRLF seen in the end of <tt>B</tt>. | 265 | number of characters from the sequence CRLF seen in the end of <tt>B</tt>. |
| 266 | '<tt>m</tt>' should tell the same, but for the previous chunk. | 266 | '<tt>m</tt>' should tell the same, but for the previous chunk. |
| 267 | </p> | 267 | </p> |
| 268 | 268 | ||
| 269 | <p class=note>Note: The message body is defined to begin with | 269 | <p class="note">Note: The message body is defined to begin with |
| 270 | an implicit CRLF. Therefore, to stuff a message correctly, the | 270 | an implicit CRLF. Therefore, to stuff a message correctly, the |
| 271 | first <tt>m</tt> should have the value 2. | 271 | first <tt>m</tt> should have the value 2. |
| 272 | </p> | 272 | </p> |
| 273 | 273 | ||
| 274 | <pre class=example> | 274 | <pre class="example"> |
| 275 | print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n"))) | 275 | print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n"))) |
| 276 | --> ..\nStuffing the message.\n..\n.. | 276 | --> ..\nStuffing the message.\n..\n.. |
| 277 | </pre> | 277 | </pre> |
| 278 | 278 | ||
| 279 | <p class=note> | 279 | <p class="note"> |
| 280 | Note: The <a href=smtp.html#send><tt>smtp.send</tt></a> function | 280 | Note: The <a href="smtp.html#send"><tt>smtp.send</tt></a> function |
| 281 | uses this filter automatically. You don't need to | 281 | uses this filter automatically. You don't need to |
| 282 | apply it again. | 282 | apply it again. |
| 283 | </p> | 283 | </p> |
| 284 | 284 | ||
| 285 | <!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 285 | <!-- eol ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 286 | 286 | ||
| 287 | <p class=name id="eol"> | 287 | <p class="name" id="eol"> |
| 288 | A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b> | 288 | A, B = mime.<b>eol(</b>C [, D, marker]<b>)</b> |
| 289 | </p> | 289 | </p> |
| 290 | 290 | ||
| 291 | <p class=description> | 291 | <p class="description"> |
| 292 | Low-level filter to perform end-of-line marker translation. | 292 | Low-level filter to perform end-of-line marker translation. |
| 293 | For each chunk, the function needs to know if the last character of the | 293 | For each chunk, the function needs to know if the last character of the |
| 294 | previous chunk could be part of an end-of-line marker or not. This is the | 294 | previous chunk could be part of an end-of-line marker or not. This is the |
| 295 | context the function receives besides the chunk. An updated version of | 295 | context the function receives besides the chunk. An updated version of |
| 296 | the context is returned after each new chunk. | 296 | the context is returned after each new chunk. |
| 297 | </p> | 297 | </p> |
| 298 | 298 | ||
| 299 | <p class=parameters> | 299 | <p class="parameters"> |
| 300 | <tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the | 300 | <tt>A</tt> is the translated version of <tt>D</tt>. <tt>C</tt> is the |
| 301 | ASCII value of the last character of the previous chunk, if it was a | 301 | ASCII value of the last character of the previous chunk, if it was a |
| 302 | candidate for line break, or 0 otherwise. | 302 | candidate for line break, or 0 otherwise. |
| 303 | <tt>B</tt> is the same as <tt>C</tt>, but for the current | 303 | <tt>B</tt> is the same as <tt>C</tt>, but for the current |
| 304 | chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF. | 304 | chunk. <tt>Marker</tt> gives the new end-of-line marker and defaults to CRLF. |
| 305 | </p> | 305 | </p> |
| 306 | 306 | ||
| 307 | <pre class=example> | 307 | <pre class="example"> |
| 308 | -- translates the end-of-line marker to UNIX | 308 | -- translates the end-of-line marker to UNIX |
| 309 | unix = mime.eol(0, dos, "\n") | 309 | unix = mime.eol(0, dos, "\n") |
| 310 | </pre> | 310 | </pre> |
| 311 | 311 | ||
| 312 | <!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 312 | <!-- qp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 313 | 313 | ||
| 314 | <p class=name id="qp"> | 314 | <p class="name" id="qp"> |
| 315 | A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b> | 315 | A, B = mime.<b>qp(</b>C [, D, marker]<b>)</b> |
| 316 | </p> | 316 | </p> |
| 317 | 317 | ||
| 318 | <p class=description> | 318 | <p class="description"> |
| 319 | Low-level filter to perform Quoted-Printable encoding. | 319 | Low-level filter to perform Quoted-Printable encoding. |
| 320 | </p> | 320 | </p> |
| 321 | 321 | ||
| 322 | <p class=parameters> | 322 | <p class="parameters"> |
| 323 | <tt>A</tt> is the encoded version of the largest prefix of | 323 | <tt>A</tt> is the encoded version of the largest prefix of |
| 324 | <tt>C..D</tt> | 324 | <tt>C..D</tt> |
| 325 | that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of | 325 | that can be encoded unambiguously. <tt>B</tt> has the remaining bytes of |
| 326 | <tt>C..D</tt>, <em>before</em> encoding. | 326 | <tt>C..D</tt>, <em>before</em> encoding. |
| 327 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with | 327 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is padded with |
| 328 | the encoding of the remaining bytes of <tt>C</tt>. | 328 | the encoding of the remaining bytes of <tt>C</tt>. |
| 329 | Throughout encoding, occurrences of CRLF are replaced by the | 329 | Throughout encoding, occurrences of CRLF are replaced by the |
| 330 | <tt>marker</tt>, which itself defaults to CRLF. | 330 | <tt>marker</tt>, which itself defaults to CRLF. |
| 331 | </p> | 331 | </p> |
| 332 | 332 | ||
| 333 | <p class=note> | 333 | <p class="note"> |
| 334 | Note: The simplest use of this function is to encode a string into it's | 334 | Note: The simplest use of this function is to encode a string into it's |
| 335 | Quoted-Printable transfer content encoding. | 335 | Quoted-Printable transfer content encoding. |
| 336 | Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value. | 336 | Notice the extra parenthesis around the call to <tt>mime.qp</tt>, to discard the second return value. |
| 337 | </p> | 337 | </p> |
| 338 | 338 | ||
| 339 | <pre class=example> | 339 | <pre class="example"> |
| 340 | print((mime.qp("maçã"))) | 340 | print((mime.qp("ma��"))) |
| 341 | --> ma=E7=E3= | 341 | --> ma=E7=E3= |
| 342 | </pre> | 342 | </pre> |
| 343 | 343 | ||
| 344 | <!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 344 | <!-- qpwrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 345 | 345 | ||
| 346 | <p class=name id="qpwrp"> | 346 | <p class="name" id="qpwrp"> |
| 347 | A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b> | 347 | A, m = mime.<b>qpwrp(</b>n [, B, length]<b>)</b> |
| 348 | </p> | 348 | </p> |
| 349 | 349 | ||
| 350 | <p class=description> | 350 | <p class="description"> |
| 351 | Low-level filter to break Quoted-Printable text into lines. | 351 | Low-level filter to break Quoted-Printable text into lines. |
| 352 | </p> | 352 | </p> |
| 353 | 353 | ||
| 354 | <p class=parameters> | 354 | <p class="parameters"> |
| 355 | <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most | 355 | <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most |
| 356 | <tt>length</tt> bytes (defaults to 76). | 356 | <tt>length</tt> bytes (defaults to 76). |
| 357 | '<tt>n</tt>' should tell how many bytes are left for the first | 357 | '<tt>n</tt>' should tell how many bytes are left for the first |
| 358 | line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes | 358 | line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes |
| 359 | left in the last line of <tt>A</tt>. | 359 | left in the last line of <tt>A</tt>. |
| 360 | </p> | 360 | </p> |
| 361 | 361 | ||
| 362 | <p class=note> | 362 | <p class="note"> |
| 363 | Note: Besides breaking text into lines, this function makes sure the line | 363 | Note: Besides breaking text into lines, this function makes sure the line |
| 364 | breaks don't fall in the middle of an escaped character combination. Also, | 364 | breaks don't fall in the middle of an escaped character combination. Also, |
| 365 | this function only breaks lines that are bigger than <tt>length</tt> bytes. | 365 | this function only breaks lines that are bigger than <tt>length</tt> bytes. |
| @@ -367,86 +367,86 @@ this function only breaks lines that are bigger than <tt>length</tt> bytes. | |||
| 367 | 367 | ||
| 368 | <!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 368 | <!-- unb64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 369 | 369 | ||
| 370 | <p class=name id="unb64"> | 370 | <p class="name" id="unb64"> |
| 371 | A, B = mime.<b>unb64(</b>C [, D]<b>)</b> | 371 | A, B = mime.<b>unb64(</b>C [, D]<b>)</b> |
| 372 | </p> | 372 | </p> |
| 373 | 373 | ||
| 374 | <p class=description> | 374 | <p class="description"> |
| 375 | Low-level filter to perform Base64 decoding. | 375 | Low-level filter to perform Base64 decoding. |
| 376 | </p> | 376 | </p> |
| 377 | 377 | ||
| 378 | <p class=parameters> | 378 | <p class="parameters"> |
| 379 | <tt>A</tt> is the decoded version of the largest prefix of | 379 | <tt>A</tt> is the decoded version of the largest prefix of |
| 380 | <tt>C..D</tt> | 380 | <tt>C..D</tt> |
| 381 | that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of | 381 | that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of |
| 382 | <tt>C..D</tt>, <em>before</em> decoding. | 382 | <tt>C..D</tt>, <em>before</em> decoding. |
| 383 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string | 383 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is the empty string |
| 384 | and <tt>B</tt> returns whatever couldn't be decoded. | 384 | and <tt>B</tt> returns whatever couldn't be decoded. |
| 385 | </p> | 385 | </p> |
| 386 | 386 | ||
| 387 | <p class=note> | 387 | <p class="note"> |
| 388 | Note: The simplest use of this function is to decode a string from it's | 388 | Note: The simplest use of this function is to decode a string from it's |
| 389 | Base64 transfer content encoding. | 389 | Base64 transfer content encoding. |
| 390 | Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. | 390 | Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. |
| 391 | </p> | 391 | </p> |
| 392 | 392 | ||
| 393 | <pre class=example> | 393 | <pre class="example"> |
| 394 | print((mime.unb64("ZGllZ286cGFzc3dvcmQ="))) | 394 | print((mime.unb64("ZGllZ286cGFzc3dvcmQ="))) |
| 395 | --> diego:password | 395 | --> diego:password |
| 396 | </pre> | 396 | </pre> |
| 397 | 397 | ||
| 398 | <!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 398 | <!-- unqp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 399 | 399 | ||
| 400 | <p class=name id="unqp"> | 400 | <p class="name" id="unqp"> |
| 401 | A, B = mime.<b>unqp(</b>C [, D]<b>)</b> | 401 | A, B = mime.<b>unqp(</b>C [, D]<b>)</b> |
| 402 | </p> | 402 | </p> |
| 403 | 403 | ||
| 404 | <p class=description> | 404 | <p class="description"> |
| 405 | Low-level filter to remove the Quoted-Printable transfer content encoding | 405 | Low-level filter to remove the Quoted-Printable transfer content encoding |
| 406 | from data. | 406 | from data. |
| 407 | </p> | 407 | </p> |
| 408 | 408 | ||
| 409 | <p class=parameters> | 409 | <p class="parameters"> |
| 410 | <tt>A</tt> is the decoded version of the largest prefix of | 410 | <tt>A</tt> is the decoded version of the largest prefix of |
| 411 | <tt>C..D</tt> | 411 | <tt>C..D</tt> |
| 412 | that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of | 412 | that can be decoded unambiguously. <tt>B</tt> has the remaining bytes of |
| 413 | <tt>C..D</tt>, <em>before</em> decoding. | 413 | <tt>C..D</tt>, <em>before</em> decoding. |
| 414 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with | 414 | If <tt>D</tt> is <tt><b>nil</b></tt>, <tt>A</tt> is augmented with |
| 415 | the encoding of the remaining bytes of <tt>C</tt>. | 415 | the encoding of the remaining bytes of <tt>C</tt>. |
| 416 | </p> | 416 | </p> |
| 417 | 417 | ||
| 418 | <p class=note> | 418 | <p class="note"> |
| 419 | Note: The simplest use of this function is to decode a string from it's | 419 | Note: The simplest use of this function is to decode a string from it's |
| 420 | Quoted-Printable transfer content encoding. | 420 | Quoted-Printable transfer content encoding. |
| 421 | Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. | 421 | Notice the extra parenthesis around the call to <tt>mime.unqp</tt>, to discard the second return value. |
| 422 | </p> | 422 | </p> |
| 423 | 423 | ||
| 424 | <pre class=example> | 424 | <pre class="example"> |
| 425 | print((mime.qp("ma=E7=E3="))) | 425 | print((mime.qp("ma=E7=E3="))) |
| 426 | --> maçã | 426 | --> ma�� |
| 427 | </pre> | 427 | </pre> |
| 428 | 428 | ||
| 429 | <!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 429 | <!-- wrp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 430 | 430 | ||
| 431 | <p class=name id="wrp"> | 431 | <p class="name" id="wrp"> |
| 432 | A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b> | 432 | A, m = mime.<b>wrp(</b>n [, B, length]<b>)</b> |
| 433 | </p> | 433 | </p> |
| 434 | 434 | ||
| 435 | <p class=description> | 435 | <p class="description"> |
| 436 | Low-level filter to break text into lines with CRLF marker. | 436 | Low-level filter to break text into lines with CRLF marker. |
| 437 | Text is assumed to be in the <a href=#normalize><tt>normalize</tt></a> form. | 437 | Text is assumed to be in the <a href="#normalize"><tt>normalize</tt></a> form. |
| 438 | </p> | 438 | </p> |
| 439 | 439 | ||
| 440 | <p class=parameters> | 440 | <p class="parameters"> |
| 441 | <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most | 441 | <tt>A</tt> is a copy of <tt>B</tt>, broken into lines of at most |
| 442 | <tt>length</tt> bytes (defaults to 76). | 442 | <tt>length</tt> bytes (defaults to 76). |
| 443 | '<tt>n</tt>' should tell how many bytes are left for the first | 443 | '<tt>n</tt>' should tell how many bytes are left for the first |
| 444 | line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes | 444 | line of <tt>B</tt> and '<tt>m</tt>' returns the number of bytes |
| 445 | left in the last line of <tt>A</tt>. | 445 | left in the last line of <tt>A</tt>. |
| 446 | </p> | 446 | </p> |
| 447 | 447 | ||
| 448 | <p class=note> | 448 | <p class="note"> |
| 449 | Note: This function only breaks lines that are bigger than | 449 | Note: This function only breaks lines that are bigger than |
| 450 | <tt>length</tt> bytes. The resulting line length does not include the CRLF | 450 | <tt>length</tt> bytes. The resulting line length does not include the CRLF |
| 451 | marker. | 451 | marker. |
| 452 | </p> | 452 | </p> |
| @@ -454,10 +454,10 @@ marker. | |||
| 454 | 454 | ||
| 455 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 455 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 456 | 456 | ||
| 457 | <div class=footer> | 457 | <div class="footer"> |
| 458 | <hr> | 458 | <hr> |
| 459 | <center> | 459 | <center> |
| 460 | <p class=bar> | 460 | <p class="bar"> |
| 461 | <a href="index.html">home</a> · | 461 | <a href="index.html">home</a> · |
| 462 | <a href="index.html#down">download</a> · | 462 | <a href="index.html#down">download</a> · |
| 463 | <a href="installation.html">installation</a> · | 463 | <a href="installation.html">installation</a> · |
diff --git a/doc/reference.html b/doc/reference.html index 163a8a2..2bc5f78 100644 --- a/doc/reference.html +++ b/doc/reference.html | |||
| @@ -1,11 +1,11 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| 5 | <head> | 5 | <head> |
| 6 | <meta name="description" content="LuaSocket: Index to reference manual"> | 6 | <meta name="description" content="LuaSocket: Index to reference manual"> |
| 7 | <meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library, | 7 | <meta name="keywords" content="Lua, LuaSocket, Index, Manual, Network, Library, |
| 8 | Support, Manual"> | 8 | Support, Manual"> |
| 9 | <title>LuaSocket: Index to reference manual</title> | 9 | <title>LuaSocket: Index to reference manual</title> |
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | 10 | <link rel="stylesheet" href="reference.css" type="text/css"> |
| 11 | </head> | 11 | </head> |
| @@ -14,22 +14,22 @@ Support, Manual"> | |||
| 14 | 14 | ||
| 15 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 15 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 16 | 16 | ||
| 17 | <div class=header> | 17 | <div class="header"> |
| 18 | <hr> | 18 | <hr> |
| 19 | <center> | 19 | <center> |
| 20 | <table summary="LuaSocket logo"> | 20 | <table summary="LuaSocket logo"> |
| 21 | <tr><td align=center><a href="http://www.lua.org"> | 21 | <tr><td align="center"><a href="http://www.lua.org"> |
| 22 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 22 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 23 | </a></td></tr> | 23 | </a></td></tr> |
| 24 | <tr><td align=center valign=top>Network support for the Lua language | 24 | <tr><td align="center" valign="top">Network support for the Lua language |
| 25 | </td></tr> | 25 | </td></tr> |
| 26 | </table> | 26 | </table> |
| 27 | <p class=bar> | 27 | <p class="bar"> |
| 28 | <a href="index.html">home</a> · | 28 | <a href="index.html">home</a> · |
| 29 | <a href="index.html#download">download</a> · | 29 | <a href="index.html#download">download</a> · |
| 30 | <a href="installation.html">installation</a> · | 30 | <a href="installation.html">installation</a> · |
| 31 | <a href="introduction.html">introduction</a> · | 31 | <a href="introduction.html">introduction</a> · |
| 32 | <a href="reference.html">reference</a> | 32 | <a href="reference.html">reference</a> |
| 33 | </p> | 33 | </p> |
| 34 | </center> | 34 | </center> |
| 35 | <hr> | 35 | <hr> |
| @@ -92,7 +92,7 @@ Support, Manual"> | |||
| 92 | <a href="ltn12.html#sink.table">table</a>. | 92 | <a href="ltn12.html#sink.table">table</a>. |
| 93 | </blockquote> | 93 | </blockquote> |
| 94 | <blockquote> | 94 | <blockquote> |
| 95 | <a href="ltn12.html#source">source</a>: | 95 | <a href="ltn12.html#source">source</a>: |
| 96 | <a href="ltn12.html#source.cat">cat</a>, | 96 | <a href="ltn12.html#source.cat">cat</a>, |
| 97 | <a href="ltn12.html#source.chain">chain</a>, | 97 | <a href="ltn12.html#source.chain">chain</a>, |
| 98 | <a href="ltn12.html#source.empty">empty</a>, | 98 | <a href="ltn12.html#source.empty">empty</a>, |
| @@ -238,10 +238,10 @@ Support, Manual"> | |||
| 238 | 238 | ||
| 239 | <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 239 | <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 240 | 240 | ||
| 241 | <div class=footer> | 241 | <div class="footer"> |
| 242 | <hr> | 242 | <hr> |
| 243 | <center> | 243 | <center> |
| 244 | <p class=bar> | 244 | <p class="bar"> |
| 245 | <a href="index.html">home</a> · | 245 | <a href="index.html">home</a> · |
| 246 | <a href="index.html#down">download</a> · | 246 | <a href="index.html#down">download</a> · |
| 247 | <a href="installation.html">installation</a> · | 247 | <a href="installation.html">installation</a> · |
diff --git a/doc/smtp.html b/doc/smtp.html index 600ec37..787d0b1 100644 --- a/doc/smtp.html +++ b/doc/smtp.html | |||
| @@ -1,11 +1,11 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| 5 | <head> | 5 | <head> |
| 6 | <meta name="description" content="LuaSocket: SMTP support"> | 6 | <meta name="description" content="LuaSocket: SMTP support"> |
| 7 | <meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart, | 7 | <meta name="keywords" content="Lua, LuaSocket, SMTP, E-Mail, MIME, Multipart, |
| 8 | Library, Support"> | 8 | Library, Support"> |
| 9 | <title>LuaSocket: SMTP support</title> | 9 | <title>LuaSocket: SMTP support</title> |
| 10 | <link rel="stylesheet" href="reference.css" type="text/css"> | 10 | <link rel="stylesheet" href="reference.css" type="text/css"> |
| 11 | </head> | 11 | </head> |
| @@ -14,22 +14,22 @@ Library, Support"> | |||
| 14 | 14 | ||
| 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 15 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 16 | 16 | ||
| 17 | <div class=header> | 17 | <div class="header"> |
| 18 | <hr> | 18 | <hr> |
| 19 | <center> | 19 | <center> |
| 20 | <table summary="LuaSocket logo"> | 20 | <table summary="LuaSocket logo"> |
| 21 | <tr><td align=center><a href="http://www.lua.org"> | 21 | <tr><td align="center"><a href="http://www.lua.org"> |
| 22 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 22 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 23 | </a></td></tr> | 23 | </a></td></tr> |
| 24 | <tr><td align=center valign=top>Network support for the Lua language | 24 | <tr><td align="center" valign="top">Network support for the Lua language |
| 25 | </td></tr> | 25 | </td></tr> |
| 26 | </table> | 26 | </table> |
| 27 | <p class=bar> | 27 | <p class="bar"> |
| 28 | <a href="index.html">home</a> · | 28 | <a href="index.html">home</a> · |
| 29 | <a href="index.html#download">download</a> · | 29 | <a href="index.html#download">download</a> · |
| 30 | <a href="installation.html">installation</a> · | 30 | <a href="installation.html">installation</a> · |
| 31 | <a href="introduction.html">introduction</a> · | 31 | <a href="introduction.html">introduction</a> · |
| 32 | <a href="reference.html">reference</a> | 32 | <a href="reference.html">reference</a> |
| 33 | </p> | 33 | </p> |
| 34 | </center> | 34 | </center> |
| 35 | <hr> | 35 | <hr> |
| @@ -37,14 +37,14 @@ Library, Support"> | |||
| 37 | 37 | ||
| 38 | <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 38 | <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 39 | 39 | ||
| 40 | <h2 id=smtp>SMTP</h2> | 40 | <h2 id="smtp">SMTP</h2> |
| 41 | 41 | ||
| 42 | <p> The <tt>smtp</tt> namespace provides functionality to send e-mail | 42 | <p> The <tt>smtp</tt> namespace provides functionality to send e-mail |
| 43 | messages. The high-level API consists of two functions: one to | 43 | messages. The high-level API consists of two functions: one to |
| 44 | define an e-mail message, and another to actually send the message. | 44 | define an e-mail message, and another to actually send the message. |
| 45 | Although almost all users will find that these functions provide more than | 45 | Although almost all users will find that these functions provide more than |
| 46 | enough functionality, the underlying implementation allows for even more | 46 | enough functionality, the underlying implementation allows for even more |
| 47 | control (if you bother to read the code). | 47 | control (if you bother to read the code). |
| 48 | </p> | 48 | </p> |
| 49 | 49 | ||
| 50 | <p>The implementation conforms to the Simple Mail Transfer Protocol, | 50 | <p>The implementation conforms to the Simple Mail Transfer Protocol, |
| @@ -54,19 +54,19 @@ href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>, | |||
| 54 | which governs the Internet Message Format. | 54 | which governs the Internet Message Format. |
| 55 | Multipart messages (those that contain attachments) are part | 55 | Multipart messages (those that contain attachments) are part |
| 56 | of the MIME standard, but described mainly | 56 | of the MIME standard, but described mainly |
| 57 | in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a> | 57 | in <a href="http://www.ietf.org/rfc/rfc2046.txt">RFC 2046</a>.</p> |
| 58 | 58 | ||
| 59 | <p> In the description below, good understanding of <a | 59 | <p> In the description below, good understanding of <a |
| 60 | href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters | 60 | href="http://lua-users.org/wiki/FiltersSourcesAndSinks"> LTN012, Filters |
| 61 | sources and sinks</a> and the <a href=mime.html>MIME</a> module is | 61 | sources and sinks</a> and the <a href="mime.html">MIME</a> module is |
| 62 | assumed. In fact, the SMTP module was the main reason for their | 62 | assumed. In fact, the SMTP module was the main reason for their |
| 63 | creation. </p> | 63 | creation. </p> |
| 64 | 64 | ||
| 65 | <p> | 65 | <p> |
| 66 | To obtain the <tt>smtp</tt> namespace, run: | 66 | To obtain the <tt>smtp</tt> namespace, run: |
| 67 | </p> | 67 | </p> |
| 68 | 68 | ||
| 69 | <pre class=example> | 69 | <pre class="example"> |
| 70 | -- loads the SMTP module and everything it requires | 70 | -- loads the SMTP module and everything it requires |
| 71 | local smtp = require("socket.smtp") | 71 | local smtp = require("socket.smtp") |
| 72 | </pre> | 72 | </pre> |
| @@ -92,40 +92,40 @@ headers = {<br> | |||
| 92 | <p> | 92 | <p> |
| 93 | Field names are case insensitive (as specified by the standard) and all | 93 | Field names are case insensitive (as specified by the standard) and all |
| 94 | functions work with lowercase field names (but see | 94 | functions work with lowercase field names (but see |
| 95 | <a href=socket.html#headers.canonic><tt>socket.headers.canonic</tt></a>). | 95 | <a href="socket.html#headers.canonic"><tt>socket.headers.canonic</tt></a>). |
| 96 | Field values are left unmodified. | 96 | Field values are left unmodified. |
| 97 | </p> | 97 | </p> |
| 98 | 98 | ||
| 99 | <p class=note> | 99 | <p class="note"> |
| 100 | Note: MIME headers are independent of order. Therefore, there is no problem | 100 | Note: MIME headers are independent of order. Therefore, there is no problem |
| 101 | in representing them in a Lua table. | 101 | in representing them in a Lua table. |
| 102 | </p> | 102 | </p> |
| 103 | 103 | ||
| 104 | <p> | 104 | <p> |
| 105 | The following constants can be set to control the default behavior of | 105 | The following constants can be set to control the default behavior of |
| 106 | the SMTP module: | 106 | the SMTP module: |
| 107 | </p> | 107 | </p> |
| 108 | 108 | ||
| 109 | <ul> | 109 | <ul> |
| 110 | <li> <tt>DOMAIN</tt>: domain used to greet the server; | 110 | <li> <tt>DOMAIN</tt>: domain used to greet the server;</li> |
| 111 | <li> <tt>PORT</tt>: default port used for the connection; | 111 | <li> <tt>PORT</tt>: default port used for the connection;</li> |
| 112 | <li> <tt>SERVER</tt>: default server used for the connection; | 112 | <li> <tt>SERVER</tt>: default server used for the connection;</li> |
| 113 | <li> <tt>TIMEOUT</tt>: default timeout for all I/O operations; | 113 | <li> <tt>TIMEOUT</tt>: default timeout for all I/O operations;</li> |
| 114 | <li> <tt>ZONE</tt>: default time zone. | 114 | <li> <tt>ZONE</tt>: default time zone.</li> |
| 115 | </ul> | 115 | </ul> |
| 116 | 116 | ||
| 117 | <!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 117 | <!-- message ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 118 | 118 | ||
| 119 | <p class=name id=message> | 119 | <p class="name" id="message"> |
| 120 | smtp.<b>message(</b>mesgt<b>)</b> | 120 | smtp.<b>message(</b>mesgt<b>)</b> |
| 121 | </p> | 121 | </p> |
| 122 | 122 | ||
| 123 | <p class=description> | 123 | <p class="description"> |
| 124 | Returns a <em>simple</em> | 124 | Returns a <em>simple</em> |
| 125 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep). | 125 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> source that sends an SMTP message body, possibly multipart (arbitrarily deep). |
| 126 | </p> | 126 | </p> |
| 127 | 127 | ||
| 128 | <p class=parameters> | 128 | <p class="parameters"> |
| 129 | The only parameter of the function is a table describing the message. | 129 | The only parameter of the function is a table describing the message. |
| 130 | <tt>Mesgt</tt> has the following form (notice the recursive structure): | 130 | <tt>Mesgt</tt> has the following form (notice the recursive structure): |
| 131 | </p> | 131 | </p> |
| @@ -135,7 +135,7 @@ The only parameter of the function is a table describing the message. | |||
| 135 | <tr><td><tt> | 135 | <tr><td><tt> |
| 136 | mesgt = {<br> | 136 | mesgt = {<br> |
| 137 | headers = <i>header-table</i>,<br> | 137 | headers = <i>header-table</i>,<br> |
| 138 | body = <i>LTN12 source</i> or <i>string</i> or | 138 | body = <i>LTN12 source</i> or <i>string</i> or |
| 139 | <i>multipart-mesgt</i><br> | 139 | <i>multipart-mesgt</i><br> |
| 140 | }<br> | 140 | }<br> |
| 141 | <br> | 141 | <br> |
| @@ -151,36 +151,36 @@ multipart-mesgt = {<br> | |||
| 151 | </table> | 151 | </table> |
| 152 | </blockquote> | 152 | </blockquote> |
| 153 | 153 | ||
| 154 | <p class=parameters> | 154 | <p class="parameters"> |
| 155 | For a simple message, all that is needed is a set of <tt>headers</tt> | 155 | For a simple message, all that is needed is a set of <tt>headers</tt> |
| 156 | and the <tt>body</tt>. The message <tt>body</tt> can be given as a string | 156 | and the <tt>body</tt>. The message <tt>body</tt> can be given as a string |
| 157 | or as a <em>simple</em> | 157 | or as a <em>simple</em> |
| 158 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 158 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 159 | source. For multipart messages, the body is a table that | 159 | source. For multipart messages, the body is a table that |
| 160 | recursively defines each part as an independent message, plus an optional | 160 | recursively defines each part as an independent message, plus an optional |
| 161 | <tt>preamble</tt> and <tt>epilogue</tt>. | 161 | <tt>preamble</tt> and <tt>epilogue</tt>. |
| 162 | </p> | 162 | </p> |
| 163 | 163 | ||
| 164 | <p class=return> | 164 | <p class="return"> |
| 165 | The function returns a <em>simple</em> | 165 | The function returns a <em>simple</em> |
| 166 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 166 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 167 | source that produces the | 167 | source that produces the |
| 168 | message contents as defined by <tt>mesgt</tt>, chunk by chunk. | 168 | message contents as defined by <tt>mesgt</tt>, chunk by chunk. |
| 169 | Hopefully, the following | 169 | Hopefully, the following |
| 170 | example will make things clear. When in doubt, refer to the appropriate RFC | 170 | example will make things clear. When in doubt, refer to the appropriate RFC |
| 171 | as listed in the introduction. </p> | 171 | as listed in the introduction. </p> |
| 172 | 172 | ||
| 173 | <pre class=example> | 173 | <pre class="example"> |
| 174 | -- load the smtp support and its friends | 174 | -- load the smtp support and its friends |
| 175 | local smtp = require("socket.smtp") | 175 | local smtp = require("socket.smtp") |
| 176 | local mime = require("mime") | 176 | local mime = require("mime") |
| 177 | local ltn12 = require("ltn12") | 177 | local ltn12 = require("ltn12") |
| 178 | 178 | ||
| 179 | -- creates a source to send a message with two parts. The first part is | 179 | -- creates a source to send a message with two parts. The first part is |
| 180 | -- plain text, the second part is a PNG image, encoded as base64. | 180 | -- plain text, the second part is a PNG image, encoded as base64. |
| 181 | source = smtp.message{ | 181 | source = smtp.message{ |
| 182 | headers = { | 182 | headers = { |
| 183 | -- Remember that headers are *ignored* by smtp.send. | 183 | -- Remember that headers are *ignored* by smtp.send. |
| 184 | from = "Sicrano de Oliveira <sicrano@example.com>", | 184 | from = "Sicrano de Oliveira <sicrano@example.com>", |
| 185 | to = "Fulano da Silva <fulano@example.com>", | 185 | to = "Fulano da Silva <fulano@example.com>", |
| 186 | subject = "Here is a message with attachments" | 186 | subject = "Here is a message with attachments" |
| @@ -191,20 +191,20 @@ source = smtp.message{ | |||
| 191 | "Preamble will probably appear even in a MIME enabled client.", | 191 | "Preamble will probably appear even in a MIME enabled client.", |
| 192 | -- first part: no headers means plain text, us-ascii. | 192 | -- first part: no headers means plain text, us-ascii. |
| 193 | -- The mime.eol low-level filter normalizes end-of-line markers. | 193 | -- The mime.eol low-level filter normalizes end-of-line markers. |
| 194 | [1] = { | 194 | [1] = { |
| 195 | body = mime.eol(0, [[ | 195 | body = mime.eol(0, [[ |
| 196 | Lines in a message body should always end with CRLF. | 196 | Lines in a message body should always end with CRLF. |
| 197 | The smtp module will *NOT* perform translation. However, the | 197 | The smtp module will *NOT* perform translation. However, the |
| 198 | send function *DOES* perform SMTP stuffing, whereas the message | 198 | send function *DOES* perform SMTP stuffing, whereas the message |
| 199 | function does *NOT*. | 199 | function does *NOT*. |
| 200 | ]]) | 200 | ]]) |
| 201 | }, | 201 | }, |
| 202 | -- second part: headers describe content to be a png image, | 202 | -- second part: headers describe content to be a png image, |
| 203 | -- sent under the base64 transfer content encoding. | 203 | -- sent under the base64 transfer content encoding. |
| 204 | -- notice that nothing happens until the message is actually sent. | 204 | -- notice that nothing happens until the message is actually sent. |
| 205 | -- small chunks are loaded into memory right before transmission and | 205 | -- small chunks are loaded into memory right before transmission and |
| 206 | -- translation happens on the fly. | 206 | -- translation happens on the fly. |
| 207 | [2] = { | 207 | [2] = { |
| 208 | headers = { | 208 | headers = { |
| 209 | ["content-type"] = 'image/png; name="image.png"', | 209 | ["content-type"] = 'image/png; name="image.png"', |
| 210 | ["content-disposition"] = 'attachment; filename="image.png"', | 210 | ["content-disposition"] = 'attachment; filename="image.png"', |
| @@ -234,7 +234,7 @@ r, e = smtp.send{ | |||
| 234 | 234 | ||
| 235 | <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 235 | <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 236 | 236 | ||
| 237 | <p class=name id=send> | 237 | <p class="name" id="send"> |
| 238 | smtp.<b>send{</b><br> | 238 | smtp.<b>send{</b><br> |
| 239 | from = <i>string</i>,<br> | 239 | from = <i>string</i>,<br> |
| 240 | rcpt = <i>string</i> or <i>string-table</i>,<br> | 240 | rcpt = <i>string</i> or <i>string-table</i>,<br> |
| @@ -249,53 +249,53 @@ smtp.<b>send{</b><br> | |||
| 249 | <b>}</b> | 249 | <b>}</b> |
| 250 | </p> | 250 | </p> |
| 251 | 251 | ||
| 252 | <p class=description> | 252 | <p class="description"> |
| 253 | Sends a message to a recipient list. Since sending messages is not as | 253 | Sends a message to a recipient list. Since sending messages is not as |
| 254 | simple as downloading an URL from a FTP or HTTP server, this function | 254 | simple as downloading an URL from a FTP or HTTP server, this function |
| 255 | doesn't have a simple interface. However, see the | 255 | doesn't have a simple interface. However, see the |
| 256 | <a href=#message><tt>message</tt></a> source factory for | 256 | <a href="#message"><tt>message</tt></a> source factory for |
| 257 | a very powerful way to define the message contents. | 257 | a very powerful way to define the message contents. |
| 258 | </p> | 258 | </p> |
| 259 | 259 | ||
| 260 | 260 | ||
| 261 | <p class=parameters> | 261 | <p class="parameters"> |
| 262 | The sender is given by the e-mail address in the <tt>from</tt> field. | 262 | The sender is given by the e-mail address in the <tt>from</tt> field. |
| 263 | <tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail | 263 | <tt>Rcpt</tt> is a Lua table with one entry for each recipient e-mail |
| 264 | address, or a string | 264 | address, or a string |
| 265 | in case there is just one recipient. | 265 | in case there is just one recipient. |
| 266 | The contents of the message are given by a <em>simple</em> | 266 | The contents of the message are given by a <em>simple</em> |
| 267 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 267 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 268 | <tt>source</tt>. Several arguments are optional: | 268 | <tt>source</tt>. Several arguments are optional: |
| 269 | </p> | 269 | </p> |
| 270 | <ul> | 270 | <ul> |
| 271 | <li> <tt>user</tt>, <tt>password</tt>: User and password for | 271 | <li> <tt>user</tt>, <tt>password</tt>: User and password for |
| 272 | authentication. The function will attempt LOGIN and PLAIN authentication | 272 | authentication. The function will attempt LOGIN and PLAIN authentication |
| 273 | methods if supported by the server (both are unsafe); | 273 | methods if supported by the server (both are unsafe);</li> |
| 274 | <li> <tt>server</tt>: Server to connect to. Defaults to "localhost"; | 274 | <li> <tt>server</tt>: Server to connect to. Defaults to "localhost";</li> |
| 275 | <li> <tt>port</tt>: Port to connect to. Defaults to 25; | 275 | <li> <tt>port</tt>: Port to connect to. Defaults to 25;</li> |
| 276 | <li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the | 276 | <li> <tt>domain</tt>: Domain name used to greet the server; Defaults to the |
| 277 | local machine host name; | 277 | local machine host name;</li> |
| 278 | <li> <tt>step</tt>: | 278 | <li> <tt>step</tt>: |
| 279 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 279 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 280 | pump step function used to pass data from the | 280 | pump step function used to pass data from the |
| 281 | source to the server. Defaults to the LTN12 <tt>pump.step</tt> function; | 281 | source to the server. Defaults to the LTN12 <tt>pump.step</tt> function;</li> |
| 282 | <li><tt>create</tt>: An optional function to be used instead of | 282 | <li><tt>create</tt>: An optional function to be used instead of |
| 283 | <a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created. | 283 | <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li> |
| 284 | </ul> | 284 | </ul> |
| 285 | 285 | ||
| 286 | <p class=return> | 286 | <p class="return"> |
| 287 | If successful, the function returns 1. Otherwise, the function returns | 287 | If successful, the function returns 1. Otherwise, the function returns |
| 288 | <b><tt>nil</tt></b> followed by an error message. | 288 | <b><tt>nil</tt></b> followed by an error message. |
| 289 | </p> | 289 | </p> |
| 290 | 290 | ||
| 291 | <p class=note> | 291 | <p class="note"> |
| 292 | Note: SMTP servers can be very picky with the format of e-mail | 292 | Note: SMTP servers can be very picky with the format of e-mail |
| 293 | addresses. To be safe, use only addresses of the form | 293 | addresses. To be safe, use only addresses of the form |
| 294 | "<tt><fulano@example.com></tt>" in the <tt>from</tt> and | 294 | "<tt><fulano@example.com></tt>" in the <tt>from</tt> and |
| 295 | <tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail | 295 | <tt>rcpt</tt> arguments to the <tt>send</tt> function. In headers, e-mail |
| 296 | addresses can take whatever form you like. </p> | 296 | addresses can take whatever form you like. </p> |
| 297 | 297 | ||
| 298 | <p class=note> | 298 | <p class="note"> |
| 299 | Big note: There is a good deal of misconception with the use of the | 299 | Big note: There is a good deal of misconception with the use of the |
| 300 | destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', | 300 | destination address field headers, i.e., the '<tt>To</tt>', '<tt>Cc</tt>', |
| 301 | and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a | 301 | and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a |
| @@ -303,68 +303,69 @@ and, more importantly, the '<tt>Bcc</tt>' headers. Do <em>not</em> add a | |||
| 303 | exact opposite of what you expect. | 303 | exact opposite of what you expect. |
| 304 | </p> | 304 | </p> |
| 305 | 305 | ||
| 306 | <p class=note> | 306 | <p class="note"> |
| 307 | Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the | 307 | Only recipients specified in the <tt>rcpt</tt> list will receive a copy of the |
| 308 | message. Each recipient of an SMTP mail message receives a copy of the | 308 | message. Each recipient of an SMTP mail message receives a copy of the |
| 309 | message body along with the headers, and nothing more. The headers | 309 | message body along with the headers, and nothing more. The headers |
| 310 | <em>are</em> part of the message and should be produced by the | 310 | <em>are</em> part of the message and should be produced by the |
| 311 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 311 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 312 | <tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em> | 312 | <tt>source</tt> function. The <tt>rcpt</tt> list is <em>not</em> |
| 313 | part of the message and will not be sent to anyone. | 313 | part of the message and will not be sent to anyone. |
| 314 | </p> | 314 | </p> |
| 315 | 315 | ||
| 316 | <p class=note> | 316 | <p class="note"> |
| 317 | <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> | 317 | <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a> |
| 318 | has two <em>important and short</em> sections, "3.6.3. Destination address | 318 | has two <em>important and short</em> sections, "3.6.3. Destination address |
| 319 | fields" and "5. Security considerations", explaining the proper | 319 | fields" and "5. Security considerations", explaining the proper |
| 320 | use of these headers. Here is a summary of what it says: | 320 | use of these headers. Here is a summary of what it says: |
| 321 | </p> | 321 | </p> |
| 322 | 322 | ||
| 323 | <ul> | 323 | <ul> |
| 324 | <li> <tt>To</tt>: contains the address(es) of the primary recipient(s) | 324 | <li> <tt>To</tt>: contains the address(es) of the primary recipient(s) |
| 325 | of the message; | 325 | of the message;</li> |
| 326 | <li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of | 326 | <li> <tt>Cc</tt>: (where the "Cc" means "Carbon Copy" in the sense of |
| 327 | making a copy on a typewriter using carbon paper) contains the | 327 | making a copy on a typewriter using carbon paper) contains the |
| 328 | addresses of others who are to receive the message, though the | 328 | addresses of others who are to receive the message, though the |
| 329 | content of the message may not be directed at them; | 329 | content of the message may not be directed at them;</li> |
| 330 | <li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon | 330 | <li> <tt>Bcc</tt>: (where the "Bcc" means "Blind Carbon |
| 331 | Copy") contains addresses of recipients of the message whose addresses are not to be revealed to other recipients of the message. | 331 | Copy") contains addresses of recipients of the message whose addresses are not |
| 332 | </ul> | 332 | to be revealed to other recipients of the message.</li> |
| 333 | </ul> | ||
| 333 | 334 | ||
| 334 | <p class=note> | 335 | <p class="note"> |
| 335 | The LuaSocket <tt>send</tt> function does not care or interpret the | 336 | The LuaSocket <tt>send</tt> function does not care or interpret the |
| 336 | headers you send, but it gives you full control over what is sent and | 337 | headers you send, but it gives you full control over what is sent and |
| 337 | to whom it is sent: | 338 | to whom it is sent: |
| 338 | </p> | 339 | </p> |
| 339 | <ul> | 340 | <ul> |
| 340 | <li> If someone is to receive the message, the e-mail address <em>has</em> | 341 | <li> If someone is to receive the message, the e-mail address <em>has</em> |
| 341 | to be in the recipient list. This is the only parameter that controls who | 342 | to be in the recipient list. This is the only parameter that controls who |
| 342 | gets a copy of the message; | 343 | gets a copy of the message;</li> |
| 343 | <li> If there are multiple recipients, none of them will automatically | 344 | <li> If there are multiple recipients, none of them will automatically |
| 344 | know that someone else got that message. That is, the default behavior is | 345 | know that someone else got that message. That is, the default behavior is |
| 345 | similar to the <tt>Bcc</tt> field of popular e-mail clients; | 346 | similar to the <tt>Bcc</tt> field of popular e-mail clients;</li> |
| 346 | <li> It is up to you to add the <tt>To</tt> header with the list of primary | 347 | <li> It is up to you to add the <tt>To</tt> header with the list of primary |
| 347 | recipients so that other recipients can see it; | 348 | recipients so that other recipients can see it;</li> |
| 348 | <li> It is also up to you to add the <tt>Cc</tt> header with the | 349 | <li> It is also up to you to add the <tt>Cc</tt> header with the |
| 349 | list of additional recipients so that everyone else sees it; | 350 | list of additional recipients so that everyone else sees it;</li> |
| 350 | <li> Adding a header <tt>Bcc</tt> is nonsense, unless it is | 351 | <li> Adding a header <tt>Bcc</tt> is nonsense, unless it is |
| 351 | empty. Otherwise, everyone receiving the message will see it and that is | 352 | empty. Otherwise, everyone receiving the message will see it and that is |
| 352 | exactly what you <em>don't</em> want to happen! | 353 | exactly what you <em>don't</em> want to happen!</li> |
| 353 | </ul> | 354 | </ul> |
| 354 | 355 | ||
| 355 | <p class=note> | 356 | <p class="note"> |
| 356 | I hope this clarifies the issue. Otherwise, please refer to | 357 | I hope this clarifies the issue. Otherwise, please refer to |
| 357 | <a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> | 358 | <a href="http://www.ietf.org/rfc/rfc2821.txt">RFC 2821</a> |
| 358 | and | 359 | and |
| 359 | <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. | 360 | <a href="http://www.ietf.org/rfc/rfc2822.txt">RFC 2822</a>. |
| 360 | </p> | 361 | </p> |
| 361 | 362 | ||
| 362 | <pre class=example> | 363 | <pre class="example"> |
| 363 | -- load the smtp support | 364 | -- load the smtp support |
| 364 | local smtp = require("socket.smtp") | 365 | local smtp = require("socket.smtp") |
| 365 | 366 | ||
| 366 | -- Connects to server "localhost" and sends a message to users | 367 | -- Connects to server "localhost" and sends a message to users |
| 367 | -- "fulano@example.com", "beltrano@example.com", | 368 | -- "fulano@example.com", "beltrano@example.com", |
| 368 | -- and "sicrano@example.com". | 369 | -- and "sicrano@example.com". |
| 369 | -- Note that "fulano" is the primary recipient, "beltrano" receives a | 370 | -- Note that "fulano" is the primary recipient, "beltrano" receives a |
| 370 | -- carbon copy and neither of them knows that "sicrano" received a blind | 371 | -- carbon copy and neither of them knows that "sicrano" received a blind |
| @@ -388,17 +389,17 @@ mesgt = { | |||
| 388 | 389 | ||
| 389 | r, e = smtp.send{ | 390 | r, e = smtp.send{ |
| 390 | from = from, | 391 | from = from, |
| 391 | rcpt = rcpt, | 392 | rcpt = rcpt, |
| 392 | source = smtp.message(mesgt) | 393 | source = smtp.message(mesgt) |
| 393 | } | 394 | } |
| 394 | </pre> | 395 | </pre> |
| 395 | 396 | ||
| 396 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 397 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 397 | 398 | ||
| 398 | <div class=footer> | 399 | <div class="footer"> |
| 399 | <hr> | 400 | <hr> |
| 400 | <center> | 401 | <center> |
| 401 | <p class=bar> | 402 | <p class="bar"> |
| 402 | <a href="index.html">home</a> · | 403 | <a href="index.html">home</a> · |
| 403 | <a href="index.html#down">download</a> · | 404 | <a href="index.html#down">download</a> · |
| 404 | <a href="installation.html">installation</a> · | 405 | <a href="installation.html">installation</a> · |
diff --git a/doc/socket.html b/doc/socket.html index 35f8391..68db7cc 100644 --- a/doc/socket.html +++ b/doc/socket.html | |||
| @@ -1,10 +1,10 @@ | |||
| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> | 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> | 3 | <html> |
| 4 | 4 | ||
| 5 | <head> | 5 | <head> |
| 6 | <meta name="description" content="LuaSocket: The core namespace"> | 6 | <meta name="description" content="LuaSocket: The core namespace"> |
| 7 | <meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> | 7 | <meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> |
| 8 | <title>LuaSocket: The socket namespace</title> | 8 | <title>LuaSocket: The socket namespace</title> |
| 9 | <link rel="stylesheet" href="reference.css" type="text/css"> | 9 | <link rel="stylesheet" href="reference.css" type="text/css"> |
| 10 | </head> | 10 | </head> |
| @@ -13,22 +13,22 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="https://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| 30 | <a href="introduction.html">introduction</a> · | 30 | <a href="introduction.html">introduction</a> · |
| 31 | <a href="reference.html">reference</a> | 31 | <a href="reference.html">reference</a> |
| 32 | </p> | 32 | </p> |
| 33 | </center> | 33 | </center> |
| 34 | <hr> | 34 | <hr> |
| @@ -36,71 +36,71 @@ | |||
| 36 | 36 | ||
| 37 | <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 37 | <!-- socket +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 38 | 38 | ||
| 39 | <h2 id=socket>The socket namespace</h2> | 39 | <h2 id="socket">The socket namespace</h2> |
| 40 | 40 | ||
| 41 | <p> | 41 | <p> |
| 42 | The <tt>socket</tt> namespace contains the core functionality of LuaSocket. | 42 | The <tt>socket</tt> namespace contains the core functionality of LuaSocket. |
| 43 | </p> | 43 | </p> |
| 44 | 44 | ||
| 45 | <p> | 45 | <p> |
| 46 | To obtain the <tt>socket</tt> namespace, run: | 46 | To obtain the <tt>socket</tt> namespace, run: |
| 47 | </p> | 47 | </p> |
| 48 | 48 | ||
| 49 | <pre class=example> | 49 | <pre class="example"> |
| 50 | -- loads the socket module | 50 | -- loads the socket module |
| 51 | local socket = require("socket") | 51 | local socket = require("socket") |
| 52 | </pre> | 52 | </pre> |
| 53 | 53 | ||
| 54 | <!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 54 | <!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 55 | 55 | ||
| 56 | <p class=name id="headers.canonic"> | 56 | <p class="name" id="headers.canonic"> |
| 57 | socket.headers.<b>canonic</b></p> | 57 | socket.headers.<b>canonic</b></p> |
| 58 | 58 | ||
| 59 | <p> The <tt>socket.headers.canonic</tt> table | 59 | <p> The <tt>socket.headers.canonic</tt> table |
| 60 | is used by the HTTP and SMTP modules to translate from | 60 | is used by the HTTP and SMTP modules to translate from |
| 61 | lowercase field names back into their canonic | 61 | lowercase field names back into their canonic |
| 62 | capitalization. When a lowercase field name exists as a key | 62 | capitalization. When a lowercase field name exists as a key |
| 63 | in this table, the associated value is substituted in | 63 | in this table, the associated value is substituted in |
| 64 | whenever the field name is sent out. | 64 | whenever the field name is sent out. |
| 65 | </p> | 65 | </p> |
| 66 | 66 | ||
| 67 | <p> | 67 | <p> |
| 68 | You can obtain the <tt>headers</tt> namespace if case run-time | 68 | You can obtain the <tt>headers</tt> namespace if case run-time |
| 69 | modifications are required by running: | 69 | modifications are required by running: |
| 70 | </p> | 70 | </p> |
| 71 | 71 | ||
| 72 | <pre class=example> | 72 | <pre class="example"> |
| 73 | -- loads the headers module | 73 | -- loads the headers module |
| 74 | local headers = require("headers") | 74 | local headers = require("headers") |
| 75 | </pre> | 75 | </pre> |
| 76 | 76 | ||
| 77 | 77 | ||
| 78 | <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 78 | <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 79 | 79 | ||
| 80 | <p class=name id=bind> | 80 | <p class="name" id="bind"> |
| 81 | socket.<b>bind(</b>address, port [, backlog]<b>)</b> | 81 | socket.<b>bind(</b>address, port [, backlog]<b>)</b> |
| 82 | </p> | 82 | </p> |
| 83 | 83 | ||
| 84 | <p class=description> | 84 | <p class="description"> |
| 85 | This function is a shortcut that creates and returns a TCP server object | 85 | This function is a shortcut that creates and returns a TCP server object |
| 86 | bound to a local <tt>address</tt> and <tt>port</tt>, ready to | 86 | bound to a local <tt>address</tt> and <tt>port</tt>, ready to |
| 87 | accept client connections. Optionally, | 87 | accept client connections. Optionally, |
| 88 | user can also specify the <tt>backlog</tt> argument to the | 88 | user can also specify the <tt>backlog</tt> argument to the |
| 89 | <a href=tcp.html#listen><tt>listen</tt></a> method (defaults to 32). | 89 | <a href="tcp.html#listen"><tt>listen</tt></a> method (defaults to 32). |
| 90 | </p> | 90 | </p> |
| 91 | 91 | ||
| 92 | <p class=note> | 92 | <p class="note"> |
| 93 | Note: The server object returned will have the option "<tt>reuseaddr</tt>" | 93 | Note: The server object returned will have the option "<tt>reuseaddr</tt>" |
| 94 | set to <tt><b>true</b></tt>. | 94 | set to <tt><b>true</b></tt>. |
| 95 | </p> | 95 | </p> |
| 96 | 96 | ||
| 97 | <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 97 | <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 98 | 98 | ||
| 99 | <p class=name id=connect> | 99 | <p class="name" id="connect"> |
| 100 | socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> | 100 | socket.<b>connect[46](</b>address, port [, locaddr] [, locport] [, family]<b>)</b> |
| 101 | </p> | 101 | </p> |
| 102 | 102 | ||
| 103 | <p class=description> | 103 | <p class="description"> |
| 104 | This function is a shortcut that creates and returns a TCP client object | 104 | This function is a shortcut that creates and returns a TCP client object |
| 105 | connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, | 105 | connected to a remote <tt>address</tt> at a given <tt>port</tt>. Optionally, |
| 106 | the user can also specify the local address and port to bind | 106 | the user can also specify the local address and port to bind |
| @@ -114,40 +114,40 @@ of connect are defined as simple helper functions that restrict the | |||
| 114 | 114 | ||
| 115 | <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 115 | <!-- debug ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 116 | 116 | ||
| 117 | <p class=name id=debug> | 117 | <p class="name" id="debug"> |
| 118 | socket.<b>_DEBUG</b> | 118 | socket.<b>_DEBUG</b> |
| 119 | </p> | 119 | </p> |
| 120 | 120 | ||
| 121 | <p class=description> | 121 | <p class="description"> |
| 122 | This constant is set to <tt><b>true</b></tt> if the library was compiled | 122 | This constant is set to <tt><b>true</b></tt> if the library was compiled |
| 123 | with debug support. | 123 | with debug support. |
| 124 | </p> | 124 | </p> |
| 125 | 125 | ||
| 126 | <!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 126 | <!-- datagramsize +++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 127 | 127 | ||
| 128 | <p class=name id=debug> | 128 | <p class="name" id="datagramsize"> |
| 129 | socket.<b>_DATAGRAMSIZE</b> | 129 | socket.<b>_DATAGRAMSIZE</b> |
| 130 | </p> | 130 | </p> |
| 131 | 131 | ||
| 132 | <p class=description> | 132 | <p class="description"> |
| 133 | Default datagram size used by calls to | 133 | Default datagram size used by calls to |
| 134 | <a href="udp.html#receive"<tt>receive</tt></a> and | 134 | <a href="udp.html#receive"><tt>receive</tt></a> and |
| 135 | <a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. | 135 | <a href="udp.html#receivefrom"><tt>receivefrom</tt></a>. |
| 136 | (Unless changed in compile time, the value is 8192.) | 136 | (Unless changed in compile time, the value is 8192.) |
| 137 | </p> | 137 | </p> |
| 138 | 138 | ||
| 139 | <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 139 | <!-- get time +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 140 | 140 | ||
| 141 | <p class=name id=gettime> | 141 | <p class="name" id="gettime"> |
| 142 | socket.<b>gettime()</b> | 142 | socket.<b>gettime()</b> |
| 143 | </p> | 143 | </p> |
| 144 | 144 | ||
| 145 | <p class=description> | 145 | <p class="description"> |
| 146 | Returns the UNIX time in seconds. You should subtract the values returned by this function | 146 | Returns the UNIX time in seconds. You should subtract the values returned by this function |
| 147 | to get meaningful values. | 147 | to get meaningful values. |
| 148 | </p> | 148 | </p> |
| 149 | 149 | ||
| 150 | <pre class=example> | 150 | <pre class="example"> |
| 151 | t = socket.gettime() | 151 | t = socket.gettime() |
| 152 | -- do stuff | 152 | -- do stuff |
| 153 | print(socket.gettime() - t .. " seconds elapsed") | 153 | print(socket.gettime() - t .. " seconds elapsed") |
| @@ -155,38 +155,38 @@ print(socket.gettime() - t .. " seconds elapsed") | |||
| 155 | 155 | ||
| 156 | <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 156 | <!-- newtry +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 157 | 157 | ||
| 158 | <p class=name id=newtry> | 158 | <p class="name" id="newtry"> |
| 159 | socket.<b>newtry(</b>finalizer<b>)</b> | 159 | socket.<b>newtry(</b>finalizer<b>)</b> |
| 160 | </p> | 160 | </p> |
| 161 | 161 | ||
| 162 | <p class=description> | 162 | <p class="description"> |
| 163 | Creates and returns a <em>clean</em> | 163 | Creates and returns a <em>clean</em> |
| 164 | <a href="#try"><tt>try</tt></a> | 164 | <a href="#try"><tt>try</tt></a> |
| 165 | function that allows for cleanup before the exception | 165 | function that allows for cleanup before the exception |
| 166 | is raised. | 166 | is raised. |
| 167 | </p> | 167 | </p> |
| 168 | 168 | ||
| 169 | <p class=parameters> | 169 | <p class="parameters"> |
| 170 | <tt>Finalizer</tt> is a function that will be called before | 170 | <tt>Finalizer</tt> is a function that will be called before |
| 171 | <tt>try</tt> throws the exception. | 171 | <tt>try</tt> throws the exception. |
| 172 | </p> | 172 | </p> |
| 173 | 173 | ||
| 174 | <p class=return> | 174 | <p class="return"> |
| 175 | The function returns your customized <tt>try</tt> function. | 175 | The function returns your customized <tt>try</tt> function. |
| 176 | </p> | 176 | </p> |
| 177 | 177 | ||
| 178 | <p class=note> | 178 | <p class="note"> |
| 179 | Note: This idea saved a <em>lot</em> of work with the | 179 | Note: This idea saved a <em>lot</em> of work with the |
| 180 | implementation of protocols in LuaSocket: | 180 | implementation of protocols in LuaSocket: |
| 181 | </p> | 181 | </p> |
| 182 | 182 | ||
| 183 | <pre class=example> | 183 | <pre class="example"> |
| 184 | foo = socket.protect(function() | 184 | foo = socket.protect(function() |
| 185 | -- connect somewhere | 185 | -- connect somewhere |
| 186 | local c = socket.try(socket.connect("somewhere", 42)) | 186 | local c = socket.try(socket.connect("somewhere", 42)) |
| 187 | -- create a try function that closes 'c' on error | 187 | -- create a try function that closes 'c' on error |
| 188 | local try = socket.newtry(function() c:close() end) | 188 | local try = socket.newtry(function() c:close() end) |
| 189 | -- do everything reassured c will be closed | 189 | -- do everything reassured c will be closed |
| 190 | try(c:send("hello there?\r\n")) | 190 | try(c:send("hello there?\r\n")) |
| 191 | local answer = try(c:receive()) | 191 | local answer = try(c:receive()) |
| 192 | ... | 192 | ... |
| @@ -198,40 +198,40 @@ end) | |||
| 198 | 198 | ||
| 199 | <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 199 | <!-- protect +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 200 | 200 | ||
| 201 | <p class=name id=protect> | 201 | <p class="name" id="protect"> |
| 202 | socket.<b>protect(</b>func<b>)</b> | 202 | socket.<b>protect(</b>func<b>)</b> |
| 203 | </p> | 203 | </p> |
| 204 | 204 | ||
| 205 | <p class=description> | 205 | <p class="description"> |
| 206 | Converts a function that throws exceptions into a safe function. This | 206 | Converts a function that throws exceptions into a safe function. This |
| 207 | function only catches exceptions thrown by the <a href=#try><tt>try</tt></a> | 207 | function only catches exceptions thrown by the <a href="#try"><tt>try</tt></a> |
| 208 | and <a href=#newtry><tt>newtry</tt></a> functions. It does not catch normal | 208 | and <a href="#newtry"><tt>newtry</tt></a> functions. It does not catch normal |
| 209 | Lua errors. | 209 | Lua errors. |
| 210 | </p> | 210 | </p> |
| 211 | 211 | ||
| 212 | <p class=parameters> | 212 | <p class="parameters"> |
| 213 | <tt>Func</tt> is a function that calls | 213 | <tt>Func</tt> is a function that calls |
| 214 | <a href=#try><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) | 214 | <a href="#try"><tt>try</tt></a> (or <tt>assert</tt>, or <tt>error</tt>) |
| 215 | to throw exceptions. | 215 | to throw exceptions. |
| 216 | </p> | 216 | </p> |
| 217 | 217 | ||
| 218 | <p class=return> | 218 | <p class="return"> |
| 219 | Returns an equivalent function that instead of throwing exceptions in case of | 219 | Returns an equivalent function that instead of throwing exceptions in case of |
| 220 | a failed <a href=#try><tt>try</tt></a> call, returns <tt><b>nil</b></tt> | 220 | a failed <a href="#try"><tt>try</tt></a> call, returns <tt><b>nil</b></tt> |
| 221 | followed by an error message. | 221 | followed by an error message. |
| 222 | </p> | 222 | </p> |
| 223 | 223 | ||
| 224 | <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 224 | <!-- select +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 225 | 225 | ||
| 226 | <p class=name id=select> | 226 | <p class="name" id="select"> |
| 227 | socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> | 227 | socket.<b>select(</b>recvt, sendt [, timeout]<b>)</b> |
| 228 | </p> | 228 | </p> |
| 229 | 229 | ||
| 230 | <p class=description> | 230 | <p class="description"> |
| 231 | Waits for a number of sockets to change status. | 231 | Waits for a number of sockets to change status. |
| 232 | </p> | 232 | </p> |
| 233 | 233 | ||
| 234 | <p class=parameters> | 234 | <p class="parameters"> |
| 235 | <tt>Recvt</tt> is an array with the sockets to test for characters | 235 | <tt>Recvt</tt> is an array with the sockets to test for characters |
| 236 | available for reading. Sockets in the <tt>sendt</tt> array are watched to | 236 | available for reading. Sockets in the <tt>sendt</tt> array are watched to |
| 237 | see if it is OK to immediately write on them. <tt>Timeout</tt> is the | 237 | see if it is OK to immediately write on them. <tt>Timeout</tt> is the |
| @@ -242,7 +242,7 @@ be empty tables or <tt><b>nil</b></tt>. Non-socket values (or values with | |||
| 242 | non-numeric indices) in the arrays will be silently ignored. | 242 | non-numeric indices) in the arrays will be silently ignored. |
| 243 | </p> | 243 | </p> |
| 244 | 244 | ||
| 245 | <p class=return> The function returns a list with the sockets ready for | 245 | <p class="return"> The function returns a list with the sockets ready for |
| 246 | reading, a list with the sockets ready for writing and an error message. | 246 | reading, a list with the sockets ready for writing and an error message. |
| 247 | The error message is "<tt>timeout</tt>" if a timeout | 247 | The error message is "<tt>timeout</tt>" if a timeout |
| 248 | condition was met, "<tt>select failed</tt>" if the call | 248 | condition was met, "<tt>select failed</tt>" if the call |
| @@ -250,10 +250,10 @@ to <tt>select</tt> failed, and | |||
| 250 | <tt><b>nil</b></tt> otherwise. The returned tables are | 250 | <tt><b>nil</b></tt> otherwise. The returned tables are |
| 251 | doubly keyed both by integers and also by the sockets | 251 | doubly keyed both by integers and also by the sockets |
| 252 | themselves, to simplify the test if a specific socket has | 252 | themselves, to simplify the test if a specific socket has |
| 253 | changed status. | 253 | changed status. |
| 254 | </p> | 254 | </p> |
| 255 | 255 | ||
| 256 | <p class=note> | 256 | <p class="note"> |
| 257 | <b>Note:</b> <tt>select</tt> can monitor a limited number | 257 | <b>Note:</b> <tt>select</tt> can monitor a limited number |
| 258 | of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This | 258 | of sockets, as defined by the constant <tt>socket._SETSIZE</tt>. This |
| 259 | number may be as high as 1024 or as low as 64 by default, | 259 | number may be as high as 1024 or as low as 64 by default, |
| @@ -262,204 +262,204 @@ at compile time. Invoking <tt>select</tt> with a larger | |||
| 262 | number of sockets will raise an error. | 262 | number of sockets will raise an error. |
| 263 | </p> | 263 | </p> |
| 264 | 264 | ||
| 265 | <p class=note> | 265 | <p class="note"> |
| 266 | <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail | 266 | <b>Important note</b>: a known bug in WinSock causes <tt>select</tt> to fail |
| 267 | on non-blocking TCP sockets. The function may return a socket as | 267 | on non-blocking TCP sockets. The function may return a socket as |
| 268 | writable even though the socket is <em>not</em> ready for sending. | 268 | writable even though the socket is <em>not</em> ready for sending. |
| 269 | </p> | 269 | </p> |
| 270 | 270 | ||
| 271 | <p class=note> | 271 | <p class="note"> |
| 272 | <b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee | 272 | <b>Another important note</b>: calling select with a server socket in the receive parameter before a call to accept does <em>not</em> guarantee |
| 273 | <a href=tcp.html#accept><tt>accept</tt></a> will return immediately. | 273 | <a href="tcp.html#accept"><tt>accept</tt></a> will return immediately. |
| 274 | Use the <a href=tcp.html#settimeout><tt>settimeout</tt></a> | 274 | Use the <a href="tcp.html#settimeout"><tt>settimeout</tt></a> |
| 275 | method or <tt>accept</tt> might block forever. | 275 | method or <tt>accept</tt> might block forever. |
| 276 | </p> | 276 | </p> |
| 277 | 277 | ||
| 278 | <p class=note> | 278 | <p class="note"> |
| 279 | <b>Yet another note</b>: If you close a socket and pass | 279 | <b>Yet another note</b>: If you close a socket and pass |
| 280 | it to <tt>select</tt>, it will be ignored. | 280 | it to <tt>select</tt>, it will be ignored. |
| 281 | </p> | 281 | </p> |
| 282 | 282 | ||
| 283 | <p class=note> | 283 | <p class="note"> |
| 284 | <b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop. | 284 | <b>Using select with non-socket objects</b>: Any object that implements <tt>getfd</tt> and <tt>dirty</tt> can be used with <tt>select</tt>, allowing objects from other libraries to be used within a <tt>socket.select</tt> driven loop. |
| 285 | </p> | 285 | </p> |
| 286 | 286 | ||
| 287 | <!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 287 | <!-- setsize ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 288 | 288 | ||
| 289 | <p class=name id=setsize> | 289 | <p class="name" id="setsize"> |
| 290 | socket.<b>_SETSIZE</b> | 290 | socket.<b>_SETSIZE</b> |
| 291 | </p> | 291 | </p> |
| 292 | 292 | ||
| 293 | <p class=description> | 293 | <p class="description"> |
| 294 | The maximum number of sockets that the <a | 294 | The maximum number of sockets that the <a |
| 295 | href=#select><tt>select</tt></a> function can handle. | 295 | href="#select"><tt>select</tt></a> function can handle. |
| 296 | </p> | 296 | </p> |
| 297 | 297 | ||
| 298 | 298 | ||
| 299 | <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 299 | <!-- sink ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 300 | 300 | ||
| 301 | <p class=name id=sink> | 301 | <p class="name" id="sink"> |
| 302 | socket.<b>sink(</b>mode, socket<b>)</b> | 302 | socket.<b>sink(</b>mode, socket<b>)</b> |
| 303 | </p> | 303 | </p> |
| 304 | 304 | ||
| 305 | <p class=description> | 305 | <p class="description"> |
| 306 | Creates an | 306 | Creates an |
| 307 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 307 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 308 | sink from a stream socket object. | 308 | sink from a stream socket object. |
| 309 | </p> | 309 | </p> |
| 310 | 310 | ||
| 311 | <p class=parameters> | 311 | <p class="parameters"> |
| 312 | <tt>Mode</tt> defines the behavior of the sink. The following | 312 | <tt>Mode</tt> defines the behavior of the sink. The following |
| 313 | options are available: | 313 | options are available: |
| 314 | </p> | 314 | </p> |
| 315 | <ul> | 315 | <ul> |
| 316 | <li> <tt>"http-chunked"</tt>: sends data through socket after applying the | 316 | <li> <tt>"http-chunked"</tt>: sends data through socket after applying the |
| 317 | <em>chunked transfer coding</em>, closing the socket when done; | 317 | <em>chunked transfer coding</em>, closing the socket when done;</li> |
| 318 | <li> <tt>"close-when-done"</tt>: sends all received data through the | 318 | <li> <tt>"close-when-done"</tt>: sends all received data through the |
| 319 | socket, closing the socket when done; | 319 | socket, closing the socket when done;</li> |
| 320 | <li> <tt>"keep-open"</tt>: sends all received data through the | 320 | <li> <tt>"keep-open"</tt>: sends all received data through the |
| 321 | socket, leaving it open when done. | 321 | socket, leaving it open when done.</li> |
| 322 | </ul> | 322 | </ul> |
| 323 | <p> | 323 | <p> |
| 324 | <tt>Socket</tt> is the stream socket object used to send the data. | 324 | <tt>Socket</tt> is the stream socket object used to send the data. |
| 325 | </p> | 325 | </p> |
| 326 | 326 | ||
| 327 | <p class=return> | 327 | <p class="return"> |
| 328 | The function returns a sink with the appropriate behavior. | 328 | The function returns a sink with the appropriate behavior. |
| 329 | </p> | 329 | </p> |
| 330 | 330 | ||
| 331 | <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 331 | <!-- skip ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 332 | 332 | ||
| 333 | <p class=name id=skip> | 333 | <p class="name" id="skip"> |
| 334 | socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> | 334 | socket.<b>skip(</b>d [, ret<sub>1</sub>, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> |
| 335 | </p> | 335 | </p> |
| 336 | 336 | ||
| 337 | <p class=description> | 337 | <p class="description"> |
| 338 | Drops a number of arguments and returns the remaining. | 338 | Drops a number of arguments and returns the remaining. |
| 339 | </p> | 339 | </p> |
| 340 | 340 | ||
| 341 | <p class=parameters> | 341 | <p class="parameters"> |
| 342 | <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to | 342 | <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to |
| 343 | <tt>ret<sub>N</sub></tt> are the arguments. | 343 | <tt>ret<sub>N</sub></tt> are the arguments. |
| 344 | </p> | 344 | </p> |
| 345 | 345 | ||
| 346 | <p class=return> | 346 | <p class="return"> |
| 347 | The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. | 347 | The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>. |
| 348 | </p> | 348 | </p> |
| 349 | 349 | ||
| 350 | <p class=note> | 350 | <p class="note"> |
| 351 | Note: This function is useful to avoid creation of dummy variables: | 351 | Note: This function is useful to avoid creation of dummy variables: |
| 352 | </p> | 352 | </p> |
| 353 | 353 | ||
| 354 | <pre class=example> | 354 | <pre class="example"> |
| 355 | -- get the status code and separator from SMTP server reply | 355 | -- get the status code and separator from SMTP server reply |
| 356 | local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) | 356 | local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)")) |
| 357 | </pre> | 357 | </pre> |
| 358 | 358 | ||
| 359 | <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 359 | <!-- sleep ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 360 | 360 | ||
| 361 | <p class=name id=sleep> | 361 | <p class="name" id="sleep"> |
| 362 | socket.<b>sleep(</b>time<b>)</b> | 362 | socket.<b>sleep(</b>time<b>)</b> |
| 363 | </p> | 363 | </p> |
| 364 | 364 | ||
| 365 | <p class=description> | 365 | <p class="description"> |
| 366 | Freezes the program execution during a given amount of time. | 366 | Freezes the program execution during a given amount of time. |
| 367 | </p> | 367 | </p> |
| 368 | 368 | ||
| 369 | <p class=parameters> | 369 | <p class="parameters"> |
| 370 | <tt>Time</tt> is the number of seconds to sleep for. If | 370 | <tt>Time</tt> is the number of seconds to sleep for. If |
| 371 | <tt>time</tt> is negative, the function returns immediately. | 371 | <tt>time</tt> is negative, the function returns immediately. |
| 372 | </p> | 372 | </p> |
| 373 | 373 | ||
| 374 | <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 374 | <!-- source +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 375 | 375 | ||
| 376 | <p class=name id=source> | 376 | <p class="name" id="source"> |
| 377 | socket.<b>source(</b>mode, socket [, length]<b>)</b> | 377 | socket.<b>source(</b>mode, socket [, length]<b>)</b> |
| 378 | </p> | 378 | </p> |
| 379 | 379 | ||
| 380 | <p class=description> | 380 | <p class="description"> |
| 381 | Creates an | 381 | Creates an |
| 382 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> | 382 | <a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> |
| 383 | source from a stream socket object. | 383 | source from a stream socket object. |
| 384 | </p> | 384 | </p> |
| 385 | 385 | ||
| 386 | <p class=parameters> | 386 | <p class="parameters"> |
| 387 | <tt>Mode</tt> defines the behavior of the source. The following | 387 | <tt>Mode</tt> defines the behavior of the source. The following |
| 388 | options are available: | 388 | options are available: |
| 389 | </p> | 389 | </p> |
| 390 | <ul> | 390 | <ul> |
| 391 | <li> <tt>"http-chunked"</tt>: receives data from socket and removes the | 391 | <li> <tt>"http-chunked"</tt>: receives data from socket and removes the |
| 392 | <em>chunked transfer coding</em> before returning the data; | 392 | <em>chunked transfer coding</em> before returning the data;</li> |
| 393 | <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the | 393 | <li> <tt>"by-length"</tt>: receives a fixed number of bytes from the |
| 394 | socket. This mode requires the extra argument <tt>length</tt>; | 394 | socket. This mode requires the extra argument <tt>length</tt>;</li> |
| 395 | <li> <tt>"until-closed"</tt>: receives data from a socket until the other | 395 | <li> <tt>"until-closed"</tt>: receives data from a socket until the other |
| 396 | side closes the connection. | 396 | side closes the connection.</li> |
| 397 | </ul> | 397 | </ul> |
| 398 | <p> | 398 | <p> |
| 399 | <tt>Socket</tt> is the stream socket object used to receive the data. | 399 | <tt>Socket</tt> is the stream socket object used to receive the data. |
| 400 | </p> | 400 | </p> |
| 401 | 401 | ||
| 402 | <p class=return> | 402 | <p class="return"> |
| 403 | The function returns a source with the appropriate behavior. | 403 | The function returns a source with the appropriate behavior. |
| 404 | </p> | 404 | </p> |
| 405 | 405 | ||
| 406 | <!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 406 | <!-- socketinvalid ++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 407 | 407 | ||
| 408 | <p class=name id=socketinvalid> | 408 | <p class="name" id="socketinvalid"> |
| 409 | socket.<b>_SOCKETINVALID</b> | 409 | socket.<b>_SOCKETINVALID</b> |
| 410 | </p> | 410 | </p> |
| 411 | 411 | ||
| 412 | <p class=description> | 412 | <p class="description"> |
| 413 | The OS value for an invalid socket. | 413 | The OS value for an invalid socket. |
| 414 | </p> | 414 | </p> |
| 415 | 415 | ||
| 416 | <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 416 | <!-- try ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 417 | 417 | ||
| 418 | <p class=name id=try> | 418 | <p class="name" id="try"> |
| 419 | socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> | 419 | socket.<b>try(</b>ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>]<b>)</b> |
| 420 | </p> | 420 | </p> |
| 421 | 421 | ||
| 422 | <p class=description> | 422 | <p class="description"> |
| 423 | Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using | 423 | Throws an exception in case <tt>ret<sub>1</sub></tt> is falsy, using |
| 424 | <tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught | 424 | <tt>ret<sub>2</sub></tt> as the error message. The exception is supposed to be caught |
| 425 | by a <a href=#protect><tt>protect</tt></a>ed function only. | 425 | by a <a href="#protect"><tt>protect</tt></a>ed function only. |
| 426 | </p> | 426 | </p> |
| 427 | 427 | ||
| 428 | <p class=parameters> | 428 | <p class="parameters"> |
| 429 | <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary | 429 | <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary |
| 430 | arguments, but are usually the return values of a function call | 430 | arguments, but are usually the return values of a function call |
| 431 | nested with <tt>try</tt>. | 431 | nested with <tt>try</tt>. |
| 432 | </p> | 432 | </p> |
| 433 | 433 | ||
| 434 | <p class=return> | 434 | <p class="return"> |
| 435 | The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if | 435 | The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if |
| 436 | <tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. | 436 | <tt>ret</tt><sub>1</sub> is not <tt><b>nil</b></tt> or <tt><b>false</b></tt>. |
| 437 | Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped | 437 | Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub> wrapped |
| 438 | in a table with metatable used by <a href=#protect><tt>protect</tt></a> to | 438 | in a table with metatable used by <a href="#protect"><tt>protect</tt></a> to |
| 439 | distinguish exceptions from runtime errors. | 439 | distinguish exceptions from runtime errors. |
| 440 | </p> | 440 | </p> |
| 441 | 441 | ||
| 442 | <pre class=example> | 442 | <pre class="example"> |
| 443 | -- connects or throws an exception with the appropriate error message | 443 | -- connects or throws an exception with the appropriate error message |
| 444 | c = socket.try(socket.connect("localhost", 80)) | 444 | c = socket.try(socket.connect("localhost", 80)) |
| 445 | </pre> | 445 | </pre> |
| 446 | 446 | ||
| 447 | <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 447 | <!-- version ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 448 | 448 | ||
| 449 | <p class=name id=version> | 449 | <p class="name" id="version"> |
| 450 | socket.<b>_VERSION</b> | 450 | socket.<b>_VERSION</b> |
| 451 | </p> | 451 | </p> |
| 452 | 452 | ||
| 453 | <p class=description> | 453 | <p class="description"> |
| 454 | This constant has a string describing the current LuaSocket version. | 454 | This constant has a string describing the current LuaSocket version. |
| 455 | </p> | 455 | </p> |
| 456 | 456 | ||
| 457 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 457 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 458 | 458 | ||
| 459 | <div class=footer> | 459 | <div class="footer"> |
| 460 | <hr> | 460 | <hr> |
| 461 | <center> | 461 | <center> |
| 462 | <p class=bar> | 462 | <p class="bar"> |
| 463 | <a href="index.html">home</a> · | 463 | <a href="index.html">home</a> · |
| 464 | <a href="index.html#down">download</a> · | 464 | <a href="index.html#down">download</a> · |
| 465 | <a href="installation.html">installation</a> · | 465 | <a href="installation.html">installation</a> · |
diff --git a/doc/tcp.html b/doc/tcp.html index 6050a5f..2d6e327 100644 --- a/doc/tcp.html +++ b/doc/tcp.html | |||
| @@ -13,17 +13,17 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| @@ -40,42 +40,43 @@ | |||
| 40 | 40 | ||
| 41 | <!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 41 | <!-- accept +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 42 | 42 | ||
| 43 | <p class=name id="accept"> | 43 | <p class="name" id="accept"> |
| 44 | server:<b>accept()</b> | 44 | server:<b>accept()</b> |
| 45 | </p> | 45 | </p> |
| 46 | 46 | ||
| 47 | <p class=description> | 47 | <p class="description"> |
| 48 | Waits for a remote connection on the server | 48 | Waits for a remote connection on the server |
| 49 | object and returns a client object representing that connection. | 49 | object and returns a client object representing that connection. |
| 50 | </p> | 50 | </p> |
| 51 | 51 | ||
| 52 | <p class=return> | 52 | <p class="return"> |
| 53 | If a connection is successfully initiated, a client object is returned. | 53 | If a connection is successfully initiated, a client object is returned. |
| 54 | If a timeout condition is met, the method returns <b><tt>nil</tt></b> | 54 | If a timeout condition is met, the method returns <b><tt>nil</tt></b> |
| 55 | followed by the error string '<tt>timeout</tt>'. Other errors are | 55 | followed by the error string '<tt>timeout</tt>'. Other errors are |
| 56 | reported by <b><tt>nil</tt></b> followed by a message describing the error. | 56 | reported by <b><tt>nil</tt></b> followed by a message describing the error. |
| 57 | </p> | 57 | </p> |
| 58 | 58 | ||
| 59 | <p class=note> | 59 | <p class="note"> |
| 60 | Note: calling <a href=socket.html#select><tt>socket.select</tt></a> | 60 | Note: calling <a href="socket.html#select"><tt>socket.select</tt></a> |
| 61 | with a server object in | 61 | with a server object in |
| 62 | the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does | 62 | the <tt>recvt</tt> parameter before a call to <tt>accept</tt> does |
| 63 | <em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a | 63 | <em>not</em> guarantee <tt>accept</tt> will return immediately. Use the <a |
| 64 | href=#settimeout><tt>settimeout</tt></a> method or <tt>accept</tt> | 64 | href="#settimeout"><tt>settimeout</tt></a> method or <tt>accept</tt> |
| 65 | might block until <em>another</em> client shows up. | 65 | might block until <em>another</em> client shows up. |
| 66 | </p> | 66 | </p> |
| 67 | 67 | ||
| 68 | <!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 68 | <!-- bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 69 | 69 | ||
| 70 | <p class=name id="bind"> | 70 | <p class="name" id="bind"> |
| 71 | master:<b>bind(</b>address, port<b>)</b> | 71 | master:<b>bind(</b>address, port<b>)</b> |
| 72 | </p> | 72 | </p> |
| 73 | 73 | ||
| 74 | <p class=description> | 74 | <p class="description"> |
| 75 | Binds a master object to <tt>address</tt> and <tt>port</tt> on the | 75 | Binds a master object to <tt>address</tt> and <tt>port</tt> on the |
| 76 | local host. | 76 | local host. |
| 77 | </p> | ||
| 77 | 78 | ||
| 78 | <p class=parameters> | 79 | <p class="parameters"> |
| 79 | <tt>Address</tt> can be an IP address or a host name. | 80 | <tt>Address</tt> can be an IP address or a host name. |
| 80 | <tt>Port</tt> must be an integer number in the range [0..64K). | 81 | <tt>Port</tt> must be an integer number in the range [0..64K). |
| 81 | If <tt>address</tt> | 82 | If <tt>address</tt> |
| @@ -86,25 +87,25 @@ If <tt>port</tt> is 0, the system automatically | |||
| 86 | chooses an ephemeral port. | 87 | chooses an ephemeral port. |
| 87 | </p> | 88 | </p> |
| 88 | 89 | ||
| 89 | <p class=return> | 90 | <p class="return"> |
| 90 | In case of success, the method returns 1. In case of error, the | 91 | In case of success, the method returns 1. In case of error, the |
| 91 | method returns <b><tt>nil</tt></b> followed by an error message. | 92 | method returns <b><tt>nil</tt></b> followed by an error message. |
| 92 | </p> | 93 | </p> |
| 93 | 94 | ||
| 94 | <p class=note> | 95 | <p class="note"> |
| 95 | Note: The function <a href=socket.html#bind><tt>socket.bind</tt></a> | 96 | Note: The function <a href="socket.html#bind"><tt>socket.bind</tt></a> |
| 96 | is available and is a shortcut for the creation of server sockets. | 97 | is available and is a shortcut for the creation of server sockets. |
| 97 | </p> | 98 | </p> |
| 98 | 99 | ||
| 99 | <!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 100 | <!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 100 | 101 | ||
| 101 | <p class=name id="close"> | 102 | <p class="name" id="close"> |
| 102 | master:<b>close()</b><br> | 103 | master:<b>close()</b><br> |
| 103 | client:<b>close()</b><br> | 104 | client:<b>close()</b><br> |
| 104 | server:<b>close()</b> | 105 | server:<b>close()</b> |
| 105 | </p> | 106 | </p> |
| 106 | 107 | ||
| 107 | <p class=description> | 108 | <p class="description"> |
| 108 | Closes a TCP object. The internal socket used by the object is closed | 109 | Closes a TCP object. The internal socket used by the object is closed |
| 109 | and the local address to which the object was | 110 | and the local address to which the object was |
| 110 | bound is made available to other applications. No further operations | 111 | bound is made available to other applications. No further operations |
| @@ -112,7 +113,7 @@ bound is made available to other applications. No further operations | |||
| 112 | a closed socket. | 113 | a closed socket. |
| 113 | </p> | 114 | </p> |
| 114 | 115 | ||
| 115 | <p class=note> | 116 | <p class="note"> |
| 116 | Note: It is important to close all used sockets once they are not | 117 | Note: It is important to close all used sockets once they are not |
| 117 | needed, since, in many systems, each socket uses a file descriptor, | 118 | needed, since, in many systems, each socket uses a file descriptor, |
| 118 | which are limited system resources. Garbage-collected objects are | 119 | which are limited system resources. Garbage-collected objects are |
| @@ -121,53 +122,53 @@ automatically closed before destruction, though. | |||
| 121 | 122 | ||
| 122 | <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 123 | <!-- connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 123 | 124 | ||
| 124 | <p class=name id="connect"> | 125 | <p class="name" id="connect"> |
| 125 | master:<b>connect(</b>address, port<b>)</b> | 126 | master:<b>connect(</b>address, port<b>)</b> |
| 126 | </p> | 127 | </p> |
| 127 | 128 | ||
| 128 | <p class=description> | 129 | <p class="description"> |
| 129 | Attempts to connect a master object to a remote host, transforming it into a | 130 | Attempts to connect a master object to a remote host, transforming it into a |
| 130 | client object. | 131 | client object. |
| 131 | Client objects support methods | 132 | Client objects support methods |
| 132 | <a href=#send><tt>send</tt></a>, | 133 | <a href="#send"><tt>send</tt></a>, |
| 133 | <a href=#receive><tt>receive</tt></a>, | 134 | <a href="#receive"><tt>receive</tt></a>, |
| 134 | <a href=#getsockname><tt>getsockname</tt></a>, | 135 | <a href="#getsockname"><tt>getsockname</tt></a>, |
| 135 | <a href=#getpeername><tt>getpeername</tt></a>, | 136 | <a href="#getpeername"><tt>getpeername</tt></a>, |
| 136 | <a href=#settimeout><tt>settimeout</tt></a>, | 137 | <a href="#settimeout"><tt>settimeout</tt></a>, |
| 137 | and <a href=#close><tt>close</tt></a>. | 138 | and <a href="#close"><tt>close</tt></a>. |
| 138 | </p> | 139 | </p> |
| 139 | 140 | ||
| 140 | <p class=parameters> | 141 | <p class="parameters"> |
| 141 | <tt>Address</tt> can be an IP address or a host name. | 142 | <tt>Address</tt> can be an IP address or a host name. |
| 142 | <tt>Port</tt> must be an integer number in the range [1..64K). | 143 | <tt>Port</tt> must be an integer number in the range [1..64K). |
| 143 | </p> | 144 | </p> |
| 144 | 145 | ||
| 145 | <p class=return> | 146 | <p class="return"> |
| 146 | In case of error, the method returns <b><tt>nil</tt></b> followed by a string | 147 | In case of error, the method returns <b><tt>nil</tt></b> followed by a string |
| 147 | describing the error. In case of success, the method returns 1. | 148 | describing the error. In case of success, the method returns 1. |
| 148 | </p> | 149 | </p> |
| 149 | 150 | ||
| 150 | <p class=note> | 151 | <p class="note"> |
| 151 | Note: The function <a href=socket.html#connect><tt>socket.connect</tt></a> | 152 | Note: The function <a href="socket.html#connect"><tt>socket.connect</tt></a> |
| 152 | is available and is a shortcut for the creation of client sockets. | 153 | is available and is a shortcut for the creation of client sockets. |
| 153 | </p> | 154 | </p> |
| 154 | 155 | ||
| 155 | <p class=note> | 156 | <p class="note"> |
| 156 | Note: Starting with LuaSocket 2.0, | 157 | Note: Starting with LuaSocket 2.0, |
| 157 | the <a href=#settimeout><tt>settimeout</tt></a> | 158 | the <a href="#settimeout"><tt>settimeout</tt></a> |
| 158 | method affects the behavior of <tt>connect</tt>, causing it to return | 159 | method affects the behavior of <tt>connect</tt>, causing it to return |
| 159 | with an error in case of a timeout. If that happens, you can still call <a | 160 | with an error in case of a timeout. If that happens, you can still call <a |
| 160 | href=socket.html#select><tt>socket.select</tt></a> with the socket in the | 161 | href="socket.html#select"><tt>socket.select</tt></a> with the socket in the |
| 161 | <tt>sendt</tt> table. The socket will be writable when the connection is | 162 | <tt>sendt</tt> table. The socket will be writable when the connection is |
| 162 | established. | 163 | established. |
| 163 | </p> | 164 | </p> |
| 164 | 165 | ||
| 165 | <p class=note> | 166 | <p class="note"> |
| 166 | Note: Starting with LuaSocket 3.0, the host name resolution | 167 | Note: Starting with LuaSocket 3.0, the host name resolution |
| 167 | depends on whether the socket was created by | 168 | depends on whether the socket was created by |
| 168 | <a href=#socket.tcp><tt>socket.tcp</tt></a>, | 169 | <a href="#socket.tcp"><tt>socket.tcp</tt></a>, |
| 169 | <a href=#socket.tcp4><tt>socket.tcp4</tt></a> or | 170 | <a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or |
| 170 | <a href=#socket.tcp6><tt>socket.tcp6</tt></a>. Addresses from | 171 | <a href="#socket.tcp6"><tt>socket.tcp6</tt></a>. Addresses from |
| 171 | the appropriate family (or both) are tried in the order | 172 | the appropriate family (or both) are tried in the order |
| 172 | returned by the resolver until the | 173 | returned by the resolver until the |
| 173 | first success or until the last failure. If the timeout was | 174 | first success or until the last failure. If the timeout was |
| @@ -176,42 +177,42 @@ set to zero, only the first address is tried. | |||
| 176 | 177 | ||
| 177 | <!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 178 | <!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 178 | 179 | ||
| 179 | <p class=name id="dirty"> | 180 | <p class="name" id="dirty"> |
| 180 | master:<b>dirty()</b><br> | 181 | master:<b>dirty()</b><br> |
| 181 | client:<b>dirty()</b><br> | 182 | client:<b>dirty()</b><br> |
| 182 | server:<b>dirty()</b> | 183 | server:<b>dirty()</b> |
| 183 | </p> | 184 | </p> |
| 184 | 185 | ||
| 185 | <p class=description> | 186 | <p class="description"> |
| 186 | Check the read buffer status. | 187 | Check the read buffer status. |
| 187 | </p> | 188 | </p> |
| 188 | 189 | ||
| 189 | <p class=return> | 190 | <p class="return"> |
| 190 | Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. | 191 | Returns <tt>true</tt> if there is any data in the read buffer, <tt>false</tt> otherwise. |
| 191 | </p> | 192 | </p> |
| 192 | 193 | ||
| 193 | <p class=note> | 194 | <p class="note"> |
| 194 | Note: <b>This is an internal method, use at your own risk.</b> | 195 | Note: <b>This is an internal method, use at your own risk.</b> |
| 195 | </p> | 196 | </p> |
| 196 | 197 | ||
| 197 | 198 | ||
| 198 | <!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 199 | <!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 199 | 200 | ||
| 200 | <p class=name id="getfd"> | 201 | <p class="name" id="getfd"> |
| 201 | master:<b>getfd()</b><br> | 202 | master:<b>getfd()</b><br> |
| 202 | client:<b>getfd()</b><br> | 203 | client:<b>getfd()</b><br> |
| 203 | server:<b>getfd()</b> | 204 | server:<b>getfd()</b> |
| 204 | </p> | 205 | </p> |
| 205 | 206 | ||
| 206 | <p class=description> | 207 | <p class="description"> |
| 207 | Returns the underling socket descriptor or handle associated to the object. | 208 | Returns the underling socket descriptor or handle associated to the object. |
| 208 | </p> | 209 | </p> |
| 209 | 210 | ||
| 210 | <p class=return> | 211 | <p class="return"> |
| 211 | The descriptor or handle. In case the object has been closed, the return will be -1. | 212 | The descriptor or handle. In case the object has been closed, the return will be -1. |
| 212 | </p> | 213 | </p> |
| 213 | 214 | ||
| 214 | <p class=note> | 215 | <p class="note"> |
| 215 | Note: <b>This is an internal method. Unlikely to be | 216 | Note: <b>This is an internal method. Unlikely to be |
| 216 | portable. Use at your own risk. </b> | 217 | portable. Use at your own risk. </b> |
| 217 | </p> | 218 | </p> |
| @@ -219,28 +220,27 @@ portable. Use at your own risk. </b> | |||
| 219 | 220 | ||
| 220 | <!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 221 | <!-- getoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 221 | 222 | ||
| 222 | <p class=name id="getoption"> | 223 | <p class="name" id="getoption"> |
| 223 | client:<b>getoption(</b>option)</b><br> | 224 | client:<b>getoption(option)</b><br> |
| 224 | server:<b>getoption(</b>option)</b> | 225 | server:<b>getoption(option)</b> |
| 225 | </p> | 226 | </p> |
| 226 | 227 | ||
| 227 | <p class=description> | 228 | <p class="description"> |
| 228 | Gets options for the TCP object. | 229 | Gets options for the TCP object. |
| 229 | See <a href=#setoption><tt>setoption</tt></a> for description of the | 230 | See <a href="#setoption"><tt>setoption</tt></a> for description of the |
| 230 | option names and values. | 231 | option names and values. |
| 231 | </p> | 232 | </p> |
| 232 | 233 | ||
| 233 | <p class=parameters> | 234 | <p class="parameters"> |
| 234 | <tt>Option</tt> is a string with the option name. | 235 | <tt>Option</tt> is a string with the option name.</p> |
| 235 | <ul> | 236 | <ul> |
| 236 | 237 | <li> '<tt>keepalive</tt>'</li> | |
| 237 | <li> '<tt>keepalive</tt>' | 238 | <li> '<tt>linger</tt>'</li> |
| 238 | <li> '<tt>linger</tt>' | 239 | <li> '<tt>reuseaddr</tt>'</li> |
| 239 | <li> '<tt>reuseaddr</tt>' | 240 | <li> '<tt>tcp-nodelay</tt>'</li> |
| 240 | <li> '<tt>tcp-nodelay</tt>' | ||
| 241 | </ul> | 241 | </ul> |
| 242 | 242 | ||
| 243 | <p class=return> | 243 | <p class="return"> |
| 244 | The method returns the option <tt>value</tt> in case of success, or | 244 | The method returns the option <tt>value</tt> in case of success, or |
| 245 | <b><tt>nil</tt></b> followed by an error message otherwise. | 245 | <b><tt>nil</tt></b> followed by an error message otherwise. |
| 246 | </p> | 246 | </p> |
| @@ -248,38 +248,38 @@ The method returns the option <tt>value</tt> in case of success, or | |||
| 248 | 248 | ||
| 249 | <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 249 | <!-- getpeername ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 250 | 250 | ||
| 251 | <p class=name id="getpeername"> | 251 | <p class="name" id="getpeername"> |
| 252 | client:<b>getpeername()</b> | 252 | client:<b>getpeername()</b> |
| 253 | </p> | 253 | </p> |
| 254 | 254 | ||
| 255 | <p class=description> | 255 | <p class="description"> |
| 256 | Returns information about the remote side of a connected client object. | 256 | Returns information about the remote side of a connected client object. |
| 257 | </p> | 257 | </p> |
| 258 | 258 | ||
| 259 | <p class=return> | 259 | <p class="return"> |
| 260 | Returns a string with the IP address of the peer, the | 260 | Returns a string with the IP address of the peer, the |
| 261 | port number that peer is using for the connection, | 261 | port number that peer is using for the connection, |
| 262 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | 262 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). |
| 263 | In case of error, the method returns <b><tt>nil</tt></b>. | 263 | In case of error, the method returns <b><tt>nil</tt></b>. |
| 264 | </p> | 264 | </p> |
| 265 | 265 | ||
| 266 | <p class=note> | 266 | <p class="note"> |
| 267 | Note: It makes no sense to call this method on server objects. | 267 | Note: It makes no sense to call this method on server objects. |
| 268 | </p> | 268 | </p> |
| 269 | 269 | ||
| 270 | <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 270 | <!-- getsockname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 271 | 271 | ||
| 272 | <p class=name id="getsockname"> | 272 | <p class="name" id="getsockname"> |
| 273 | master:<b>getsockname()</b><br> | 273 | master:<b>getsockname()</b><br> |
| 274 | client:<b>getsockname()</b><br> | 274 | client:<b>getsockname()</b><br> |
| 275 | server:<b>getsockname()</b> | 275 | server:<b>getsockname()</b> |
| 276 | </p> | 276 | </p> |
| 277 | 277 | ||
| 278 | <p class=description> | 278 | <p class="description"> |
| 279 | Returns the local address information associated to the object. | 279 | Returns the local address information associated to the object. |
| 280 | </p> | 280 | </p> |
| 281 | 281 | ||
| 282 | <p class=return> | 282 | <p class="return"> |
| 283 | The method returns a string with local IP address, a number with | 283 | The method returns a string with local IP address, a number with |
| 284 | the local port, | 284 | the local port, |
| 285 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | 285 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). |
| @@ -288,31 +288,31 @@ In case of error, the method returns <b><tt>nil</tt></b>. | |||
| 288 | 288 | ||
| 289 | <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 289 | <!-- getstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 290 | 290 | ||
| 291 | <p class=name id="getstats"> | 291 | <p class="name" id="getstats"> |
| 292 | master:<b>getstats()</b><br> | 292 | master:<b>getstats()</b><br> |
| 293 | client:<b>getstats()</b><br> | 293 | client:<b>getstats()</b><br> |
| 294 | server:<b>getstats()</b><br> | 294 | server:<b>getstats()</b><br> |
| 295 | </p> | 295 | </p> |
| 296 | 296 | ||
| 297 | <p class=description> | 297 | <p class="description"> |
| 298 | Returns accounting information on the socket, useful for throttling | 298 | Returns accounting information on the socket, useful for throttling |
| 299 | of bandwidth. | 299 | of bandwidth. |
| 300 | </p> | 300 | </p> |
| 301 | 301 | ||
| 302 | <p class=return> | 302 | <p class="return"> |
| 303 | The method returns the number of bytes received, the number of bytes sent, | 303 | The method returns the number of bytes received, the number of bytes sent, |
| 304 | and the age of the socket object in seconds. | 304 | and the age of the socket object in seconds. |
| 305 | </p> | 305 | </p> |
| 306 | 306 | ||
| 307 | <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 307 | <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 308 | 308 | ||
| 309 | <p class=name id="gettimeout"> | 309 | <p class="name" id="gettimeout"> |
| 310 | master:<b>gettimeout()</b><br> | 310 | master:<b>gettimeout()</b><br> |
| 311 | client:<b>gettimeout()</b><br> | 311 | client:<b>gettimeout()</b><br> |
| 312 | server:<b>gettimeout()</b> | 312 | server:<b>gettimeout()</b> |
| 313 | </p> | 313 | </p> |
| 314 | 314 | ||
| 315 | <p class=description> | 315 | <p class="description"> |
| 316 | Returns the current block timeout followed by the curent | 316 | Returns the current block timeout followed by the curent |
| 317 | total timeout. | 317 | total timeout. |
| 318 | </p> | 318 | </p> |
| @@ -320,65 +320,65 @@ total timeout. | |||
| 320 | 320 | ||
| 321 | <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 321 | <!-- listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 322 | 322 | ||
| 323 | <p class=name id="listen"> | 323 | <p class="name" id="listen"> |
| 324 | master:<b>listen(</b>backlog<b>)</b> | 324 | master:<b>listen(</b>backlog<b>)</b> |
| 325 | </p> | 325 | </p> |
| 326 | 326 | ||
| 327 | <p class=description> | 327 | <p class="description"> |
| 328 | Specifies the socket is willing to receive connections, transforming the | 328 | Specifies the socket is willing to receive connections, transforming the |
| 329 | object into a server object. Server objects support the | 329 | object into a server object. Server objects support the |
| 330 | <a href=#accept><tt>accept</tt></a>, | 330 | <a href="#accept"><tt>accept</tt></a>, |
| 331 | <a href=#getsockname><tt>getsockname</tt></a>, | 331 | <a href="#getsockname"><tt>getsockname</tt></a>, |
| 332 | <a href=#setoption><tt>setoption</tt></a>, | 332 | <a href="#setoption"><tt>setoption</tt></a>, |
| 333 | <a href=#settimeout><tt>settimeout</tt></a>, | 333 | <a href="#settimeout"><tt>settimeout</tt></a>, |
| 334 | and <a href=#close><tt>close</tt></a> methods. | 334 | and <a href="#close"><tt>close</tt></a> methods. |
| 335 | </p> | 335 | </p> |
| 336 | 336 | ||
| 337 | <p class=parameters> | 337 | <p class="parameters"> |
| 338 | The parameter <tt>backlog</tt> specifies the number of client | 338 | The parameter <tt>backlog</tt> specifies the number of client |
| 339 | connections that can | 339 | connections that can |
| 340 | be queued waiting for service. If the queue is full and another client | 340 | be queued waiting for service. If the queue is full and another client |
| 341 | attempts connection, the connection is refused. | 341 | attempts connection, the connection is refused. |
| 342 | </p> | 342 | </p> |
| 343 | 343 | ||
| 344 | <p class=return> | 344 | <p class="return"> |
| 345 | In case of success, the method returns 1. In case of error, the | 345 | In case of success, the method returns 1. In case of error, the |
| 346 | method returns <b><tt>nil</tt></b> followed by an error message. | 346 | method returns <b><tt>nil</tt></b> followed by an error message. |
| 347 | </p> | 347 | </p> |
| 348 | 348 | ||
| 349 | <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 349 | <!-- receive ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 350 | 350 | ||
| 351 | <p class=name id="receive"> | 351 | <p class="name" id="receive"> |
| 352 | client:<b>receive(</b>[pattern [, prefix]]<b>)</b> | 352 | client:<b>receive(</b>[pattern [, prefix]]<b>)</b> |
| 353 | </p> | 353 | </p> |
| 354 | 354 | ||
| 355 | <p class=description> | 355 | <p class="description"> |
| 356 | Reads data from a client object, according to the specified <em>read | 356 | Reads data from a client object, according to the specified <em>read |
| 357 | pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. | 357 | pattern</em>. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. |
| 358 | </p> | 358 | </p> |
| 359 | 359 | ||
| 360 | <p class=parameters> | 360 | <p class="parameters"> |
| 361 | <tt>Pattern</tt> can be any of the following: | 361 | <tt>Pattern</tt> can be any of the following: |
| 362 | </p> | 362 | </p> |
| 363 | 363 | ||
| 364 | <ul> | 364 | <ul> |
| 365 | <li> '<tt>*a</tt>': reads from the socket until the connection is | 365 | <li> '<tt>*a</tt>': reads from the socket until the connection is |
| 366 | closed. No end-of-line translation is performed; | 366 | closed. No end-of-line translation is performed;</li> |
| 367 | <li> '<tt>*l</tt>': reads a line of text from the socket. The line is | 367 | <li> '<tt>*l</tt>': reads a line of text from the socket. The line is |
| 368 | terminated by a LF character (ASCII 10), optionally preceded by a | 368 | terminated by a LF character (ASCII 10), optionally preceded by a |
| 369 | CR character (ASCII 13). The CR and LF characters are not included in | 369 | CR character (ASCII 13). The CR and LF characters are not included in |
| 370 | the returned line. In fact, <em>all</em> CR characters are | 370 | the returned line. In fact, <em>all</em> CR characters are |
| 371 | ignored by the pattern. This is the default pattern; | 371 | ignored by the pattern. This is the default pattern;</li> |
| 372 | <li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> | 372 | <li> <tt>number</tt>: causes the method to read a specified <tt>number</tt> |
| 373 | of bytes from the socket. | 373 | of bytes from the socket.</li> |
| 374 | </ul> | 374 | </ul> |
| 375 | 375 | ||
| 376 | <p class=parameters> | 376 | <p class="parameters"> |
| 377 | <tt>Prefix</tt> is an optional string to be concatenated to the beginning | 377 | <tt>Prefix</tt> is an optional string to be concatenated to the beginning |
| 378 | of any received data before return. | 378 | of any received data before return. |
| 379 | </p> | 379 | </p> |
| 380 | 380 | ||
| 381 | <p class=return> | 381 | <p class="return"> |
| 382 | If successful, the method returns the received pattern. In case of error, | 382 | If successful, the method returns the received pattern. In case of error, |
| 383 | the method returns <tt><b>nil</b></tt> followed by an error | 383 | the method returns <tt><b>nil</b></tt> followed by an error |
| 384 | message, followed by a (possibly empty) string containing | 384 | message, followed by a (possibly empty) string containing |
| @@ -388,7 +388,7 @@ closed before the transmission was completed or the string | |||
| 388 | '<tt>timeout</tt>' in case there was a timeout during the operation. | 388 | '<tt>timeout</tt>' in case there was a timeout during the operation. |
| 389 | </p> | 389 | </p> |
| 390 | 390 | ||
| 391 | <p class=note> | 391 | <p class="note"> |
| 392 | <b>Important note</b>: This function was changed <em>severely</em>. It used | 392 | <b>Important note</b>: This function was changed <em>severely</em>. It used |
| 393 | to support multiple patterns (but I have never seen this feature used) and | 393 | to support multiple patterns (but I have never seen this feature used) and |
| 394 | now it doesn't anymore. Partial results used to be returned in the same | 394 | now it doesn't anymore. Partial results used to be returned in the same |
| @@ -399,22 +399,22 @@ too. | |||
| 399 | 399 | ||
| 400 | <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 400 | <!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 401 | 401 | ||
| 402 | <p class=name id="send"> | 402 | <p class="name" id="send"> |
| 403 | client:<b>send(</b>data [, i [, j]]<b>)</b> | 403 | client:<b>send(</b>data [, i [, j]]<b>)</b> |
| 404 | </p> | 404 | </p> |
| 405 | 405 | ||
| 406 | <p class=description> | 406 | <p class="description"> |
| 407 | Sends <tt>data</tt> through client object. | 407 | Sends <tt>data</tt> through client object. |
| 408 | </p> | 408 | </p> |
| 409 | 409 | ||
| 410 | <p class=parameters> | 410 | <p class="parameters"> |
| 411 | <tt>Data</tt> is the string to be sent. The optional arguments | 411 | <tt>Data</tt> is the string to be sent. The optional arguments |
| 412 | <tt>i</tt> and <tt>j</tt> work exactly like the standard | 412 | <tt>i</tt> and <tt>j</tt> work exactly like the standard |
| 413 | <tt>string.sub</tt> Lua function to allow the selection of a | 413 | <tt>string.sub</tt> Lua function to allow the selection of a |
| 414 | substring to be sent. | 414 | substring to be sent. |
| 415 | </p> | 415 | </p> |
| 416 | 416 | ||
| 417 | <p class=return> | 417 | <p class="return"> |
| 418 | If successful, the method returns the index of the last byte | 418 | If successful, the method returns the index of the last byte |
| 419 | within <tt>[i, j]</tt> that has been sent. Notice that, if | 419 | within <tt>[i, j]</tt> that has been sent. Notice that, if |
| 420 | <tt>i</tt> is 1 or absent, this is effectively the total | 420 | <tt>i</tt> is 1 or absent, this is effectively the total |
| @@ -428,7 +428,7 @@ was completed or the string '<tt>timeout</tt>' in case | |||
| 428 | there was a timeout during the operation. | 428 | there was a timeout during the operation. |
| 429 | </p> | 429 | </p> |
| 430 | 430 | ||
| 431 | <p class=note> | 431 | <p class="note"> |
| 432 | Note: Output is <em>not</em> buffered. For small strings, | 432 | Note: Output is <em>not</em> buffered. For small strings, |
| 433 | it is always better to concatenate them in Lua | 433 | it is always better to concatenate them in Lua |
| 434 | (with the '<tt>..</tt>' operator) and send the result in one call | 434 | (with the '<tt>..</tt>' operator) and send the result in one call |
| @@ -437,27 +437,27 @@ instead of calling the method several times. | |||
| 437 | 437 | ||
| 438 | <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 438 | <!-- setoption ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 439 | 439 | ||
| 440 | <p class=name id="setoption"> | 440 | <p class="name" id="setoption"> |
| 441 | client:<b>setoption(</b>option [, value]<b>)</b><br> | 441 | client:<b>setoption(</b>option [, value]<b>)</b><br> |
| 442 | server:<b>setoption(</b>option [, value]<b>)</b> | 442 | server:<b>setoption(</b>option [, value]<b>)</b> |
| 443 | </p> | 443 | </p> |
| 444 | 444 | ||
| 445 | <p class=description> | 445 | <p class="description"> |
| 446 | Sets options for the TCP object. Options are only needed by low-level or | 446 | Sets options for the TCP object. Options are only needed by low-level or |
| 447 | time-critical applications. You should only modify an option if you | 447 | time-critical applications. You should only modify an option if you |
| 448 | are sure you need it. | 448 | are sure you need it. |
| 449 | </p> | 449 | </p> |
| 450 | 450 | ||
| 451 | <p class=parameters> | 451 | <p class="parameters"> |
| 452 | <tt>Option</tt> is a string with the option name, and <tt>value</tt> | 452 | <tt>Option</tt> is a string with the option name, and <tt>value</tt> |
| 453 | depends on the option being set: | 453 | depends on the option being set:</p> |
| 454 | 454 | ||
| 455 | <ul> | 455 | <ul> |
| 456 | 456 | ||
| 457 | <li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables | 457 | <li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables |
| 458 | the periodic transmission of messages on a connected socket. Should the | 458 | the periodic transmission of messages on a connected socket. Should the |
| 459 | connected party fail to respond to these messages, the connection is | 459 | connected party fail to respond to these messages, the connection is |
| 460 | considered broken and processes using the socket are notified; | 460 | considered broken and processes using the socket are notified;</li> |
| 461 | 461 | ||
| 462 | <li> '<tt>linger</tt>': Controls the action taken when unsent data are | 462 | <li> '<tt>linger</tt>': Controls the action taken when unsent data are |
| 463 | queued on a socket and a close is performed. The value is a table with a | 463 | queued on a socket and a close is performed. The value is a table with a |
| @@ -468,79 +468,79 @@ it is able to transmit the data or until '<tt>timeout</tt>' has passed. If | |||
| 468 | '<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will | 468 | '<tt>on</tt>' is <tt>false</tt> and a close is issued, the system will |
| 469 | process the close in a manner that allows the process to continue as | 469 | process the close in a manner that allows the process to continue as |
| 470 | quickly as possible. I do not advise you to set this to anything other than | 470 | quickly as possible. I do not advise you to set this to anything other than |
| 471 | zero; | 471 | zero;</li> |
| 472 | 472 | ||
| 473 | <li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules | 473 | <li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules |
| 474 | used in validating addresses supplied in a call to | 474 | used in validating addresses supplied in a call to |
| 475 | <a href=#bind><tt>bind</tt></a> should allow reuse of local addresses; | 475 | <a href="#bind"><tt>bind</tt></a> should allow reuse of local addresses;</li> |
| 476 | 476 | ||
| 477 | <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> | 477 | <li> '<tt>tcp-nodelay</tt>': Setting this option to <tt>true</tt> |
| 478 | disables the Nagle's algorithm for the connection; | 478 | disables the Nagle's algorithm for the connection;</li> |
| 479 | 479 | ||
| 480 | <li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!! | 480 | <li> '<tt>tcp-keepidle</tt>': value in seconds for <tt>TCP_KEEPIDLE</tt> Linux only!!</li> |
| 481 | 481 | ||
| 482 | <li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!! | 482 | <li> '<tt>tcp-keepcnt</tt>': value for <tt>TCP_KEEPCNT</tt> Linux only!!</li> |
| 483 | 483 | ||
| 484 | <li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!! | 484 | <li> '<tt>tcp-keepintvl</tt>': value for <tt>TCP_KEEPINTVL</tt> Linux only!!</li> |
| 485 | 485 | ||
| 486 | <li> '<tt>ipv6-v6only</tt>': | 486 | <li> '<tt>ipv6-v6only</tt>': |
| 487 | Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to | 487 | Setting this option to <tt>true</tt> restricts an <tt>inet6</tt> socket to |
| 488 | sending and receiving only IPv6 packets. | 488 | sending and receiving only IPv6 packets.</li> |
| 489 | </ul> | 489 | </ul> |
| 490 | 490 | ||
| 491 | <p class=return> | 491 | <p class="return"> |
| 492 | The method returns 1 in case of success, or <b><tt>nil</tt></b> | 492 | The method returns 1 in case of success, or <b><tt>nil</tt></b> |
| 493 | followed by an error message otherwise. | 493 | followed by an error message otherwise. |
| 494 | </p> | 494 | </p> |
| 495 | 495 | ||
| 496 | <p class=note> | 496 | <p class="note"> |
| 497 | Note: The descriptions above come from the man pages. | 497 | Note: The descriptions above come from the man pages. |
| 498 | </p> | 498 | </p> |
| 499 | 499 | ||
| 500 | <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 500 | <!-- setstats +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 501 | 501 | ||
| 502 | <p class=name id="setstats"> | 502 | <p class="name" id="setstats"> |
| 503 | master:<b>setstats(</b>received, sent, age<b>)</b><br> | 503 | master:<b>setstats(</b>received, sent, age<b>)</b><br> |
| 504 | client:<b>setstats(</b>received, sent, age<b>)</b><br> | 504 | client:<b>setstats(</b>received, sent, age<b>)</b><br> |
| 505 | server:<b>setstats(</b>received, sent, age<b>)</b><br> | 505 | server:<b>setstats(</b>received, sent, age<b>)</b><br> |
| 506 | </p> | 506 | </p> |
| 507 | 507 | ||
| 508 | <p class=description> | 508 | <p class="description"> |
| 509 | Resets accounting information on the socket, useful for throttling | 509 | Resets accounting information on the socket, useful for throttling |
| 510 | of bandwidth. | 510 | of bandwidth. |
| 511 | </p> | 511 | </p> |
| 512 | 512 | ||
| 513 | <p class=parameters> | 513 | <p class="parameters"> |
| 514 | <tt>Received</tt> is a number with the new number of bytes received. | 514 | <tt>Received</tt> is a number with the new number of bytes received. |
| 515 | <tt>Sent</tt> is a number with the new number of bytes sent. | 515 | <tt>Sent</tt> is a number with the new number of bytes sent. |
| 516 | <tt>Age</tt> is the new age in seconds. | 516 | <tt>Age</tt> is the new age in seconds. |
| 517 | </p> | 517 | </p> |
| 518 | 518 | ||
| 519 | <p class=return> | 519 | <p class="return"> |
| 520 | The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. | 520 | The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise. |
| 521 | </p> | 521 | </p> |
| 522 | 522 | ||
| 523 | <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 523 | <!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 524 | 524 | ||
| 525 | <p class=name id="settimeout"> | 525 | <p class="name" id="settimeout"> |
| 526 | master:<b>settimeout(</b>value [, mode]<b>)</b><br> | 526 | master:<b>settimeout(</b>value [, mode]<b>)</b><br> |
| 527 | client:<b>settimeout(</b>value [, mode]<b>)</b><br> | 527 | client:<b>settimeout(</b>value [, mode]<b>)</b><br> |
| 528 | server:<b>settimeout(</b>value [, mode]<b>)</b> | 528 | server:<b>settimeout(</b>value [, mode]<b>)</b> |
| 529 | </p> | 529 | </p> |
| 530 | 530 | ||
| 531 | <p class=description> | 531 | <p class="description"> |
| 532 | Changes the timeout values for the object. By default, | 532 | Changes the timeout values for the object. By default, |
| 533 | all I/O operations are blocking. That is, any call to the methods | 533 | all I/O operations are blocking. That is, any call to the methods |
| 534 | <a href=#send><tt>send</tt></a>, | 534 | <a href="#send"><tt>send</tt></a>, |
| 535 | <a href=#receive><tt>receive</tt></a>, and | 535 | <a href="#receive"><tt>receive</tt></a>, and |
| 536 | <a href=#accept><tt>accept</tt></a> | 536 | <a href="#accept"><tt>accept</tt></a> |
| 537 | will block indefinitely, until the operation completes. The | 537 | will block indefinitely, until the operation completes. The |
| 538 | <tt>settimeout</tt> method defines a limit on the amount of time the | 538 | <tt>settimeout</tt> method defines a limit on the amount of time the |
| 539 | I/O methods can block. When a timeout is set and the specified amount of | 539 | I/O methods can block. When a timeout is set and the specified amount of |
| 540 | time has elapsed, the affected methods give up and fail with an error code. | 540 | time has elapsed, the affected methods give up and fail with an error code. |
| 541 | </p> | 541 | </p> |
| 542 | 542 | ||
| 543 | <p class=parameters> | 543 | <p class="parameters"> |
| 544 | The amount of time to wait is specified as the | 544 | The amount of time to wait is specified as the |
| 545 | <tt>value</tt> parameter, in seconds. There are two timeout modes and | 545 | <tt>value</tt> parameter, in seconds. There are two timeout modes and |
| 546 | both can be used together for fine tuning: | 546 | both can be used together for fine tuning: |
| @@ -557,12 +557,12 @@ the amount of time LuaSocket can block a Lua script before returning from | |||
| 557 | a call.</li> | 557 | a call.</li> |
| 558 | </ul> | 558 | </ul> |
| 559 | 559 | ||
| 560 | <p class=parameters> | 560 | <p class="parameters"> |
| 561 | The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block | 561 | The <b><tt>nil</tt></b> timeout <tt>value</tt> allows operations to block |
| 562 | indefinitely. Negative timeout values have the same effect. | 562 | indefinitely. Negative timeout values have the same effect. |
| 563 | </p> | 563 | </p> |
| 564 | 564 | ||
| 565 | <p class=note> | 565 | <p class="note"> |
| 566 | Note: although timeout values have millisecond precision in LuaSocket, | 566 | Note: although timeout values have millisecond precision in LuaSocket, |
| 567 | large blocks can cause I/O functions not to respect timeout values due | 567 | large blocks can cause I/O functions not to respect timeout values due |
| 568 | to the time the library takes to transfer blocks to and from the OS | 568 | to the time the library takes to transfer blocks to and from the OS |
| @@ -571,7 +571,7 @@ and perform automatic name resolution might be blocked by the resolver for | |||
| 571 | longer than the specified timeout value. | 571 | longer than the specified timeout value. |
| 572 | </p> | 572 | </p> |
| 573 | 573 | ||
| 574 | <p class=note> | 574 | <p class="note"> |
| 575 | Note: The old <tt>timeout</tt> method is deprecated. The name has been | 575 | Note: The old <tt>timeout</tt> method is deprecated. The name has been |
| 576 | changed for sake of uniformity, since all other method names already | 576 | changed for sake of uniformity, since all other method names already |
| 577 | contained verbs making their imperative nature obvious. | 577 | contained verbs making their imperative nature obvious. |
| @@ -579,123 +579,124 @@ contained verbs making their imperative nature obvious. | |||
| 579 | 579 | ||
| 580 | <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 580 | <!-- shutdown +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 581 | 581 | ||
| 582 | <p class=name id="shutdown"> | 582 | <p class="name" id="shutdown"> |
| 583 | client:<b>shutdown(</b>mode<b>)</b><br> | 583 | client:<b>shutdown(</b>mode<b>)</b><br> |
| 584 | </p> | 584 | </p> |
| 585 | 585 | ||
| 586 | <p class=description> | 586 | <p class="description"> |
| 587 | Shuts down part of a full-duplex connection. | 587 | Shuts down part of a full-duplex connection. |
| 588 | </p> | 588 | </p> |
| 589 | 589 | ||
| 590 | <p class=parameters> | 590 | <p class="parameters"> |
| 591 | Mode tells which way of the connection should be shut down and can | 591 | Mode tells which way of the connection should be shut down and can |
| 592 | take the value: | 592 | take the value: |
| 593 | <ul> | 593 | <ul> |
| 594 | <li>"<tt>both</tt>": disallow further sends and receives on the object. | 594 | <li>"<tt>both</tt>": disallow further sends and receives on the object. |
| 595 | This is the default mode; | 595 | This is the default mode;</li> |
| 596 | <li>"<tt>send</tt>": disallow further sends on the object; | 596 | <li>"<tt>send</tt>": disallow further sends on the object;</li> |
| 597 | <li>"<tt>receive</tt>": disallow further receives on the object. | 597 | <li>"<tt>receive</tt>": disallow further receives on the object.</li> |
| 598 | </ul> | 598 | </ul> |
| 599 | </p> | ||
| 599 | 600 | ||
| 600 | <p class=return> | 601 | <p class="return"> |
| 601 | This function returns 1. | 602 | This function returns 1. |
| 602 | </p> | 603 | </p> |
| 603 | 604 | ||
| 604 | <!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 605 | <!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 605 | 606 | ||
| 606 | <p class=name id="setfd"> | 607 | <p class="name" id="setfd"> |
| 607 | master:<b>setfd(</b>fd<b>)</b><br> | 608 | master:<b>setfd(</b>fd<b>)</b><br> |
| 608 | client:<b>setfd(</b>fd<b>)</b><br> | 609 | client:<b>setfd(</b>fd<b>)</b><br> |
| 609 | server:<b>setfd(</b>fd<b>)</b> | 610 | server:<b>setfd(</b>fd<b>)</b> |
| 610 | </p> | 611 | </p> |
| 611 | 612 | ||
| 612 | <p class=description> | 613 | <p class="description"> |
| 613 | Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made. | 614 | Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made. |
| 614 | </p> | 615 | </p> |
| 615 | 616 | ||
| 616 | <p class=return> | 617 | <p class="return"> |
| 617 | No return value. | 618 | No return value. |
| 618 | </p> | 619 | </p> |
| 619 | 620 | ||
| 620 | <p class=note> | 621 | <p class="note"> |
| 621 | Note: <b>This is an internal method. Unlikely to be | 622 | Note: <b>This is an internal method. Unlikely to be |
| 622 | portable. Use at your own risk. </b> | 623 | portable. Use at your own risk. </b> |
| 623 | </p> | 624 | </p> |
| 624 | 625 | ||
| 625 | <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 626 | <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 626 | 627 | ||
| 627 | <p class=name id="socket.tcp"> | 628 | <p class="name" id="socket.tcp"> |
| 628 | socket.<b>tcp()</b> | 629 | socket.<b>tcp()</b> |
| 629 | </p> | 630 | </p> |
| 630 | 631 | ||
| 631 | <p class=description> | 632 | <p class="description"> |
| 632 | Creates and returns an TCP master object. A master object can | 633 | Creates and returns an TCP master object. A master object can |
| 633 | be transformed into a server object with the method | 634 | be transformed into a server object with the method |
| 634 | <a href=#listen><tt>listen</tt></a> (after a call to <a | 635 | <a href="#listen"><tt>listen</tt></a> (after a call to <a |
| 635 | href=#bind><tt>bind</tt></a>) or into a client object with | 636 | href="#bind"><tt>bind</tt></a>) or into a client object with |
| 636 | the method <a href=#connect><tt>connect</tt></a>. The only other | 637 | the method <a href="#connect"><tt>connect</tt></a>. The only other |
| 637 | method supported by a master object is the | 638 | method supported by a master object is the |
| 638 | <a href=#close><tt>close</tt></a> method.</p> | 639 | <a href="#close"><tt>close</tt></a> method.</p> |
| 639 | 640 | ||
| 640 | <p class=return> | 641 | <p class="return"> |
| 641 | In case of success, a new master object is returned. In case of error, | 642 | In case of success, a new master object is returned. In case of error, |
| 642 | <b><tt>nil</tt></b> is returned, followed by an error message. | 643 | <b><tt>nil</tt></b> is returned, followed by an error message. |
| 643 | </p> | 644 | </p> |
| 644 | 645 | ||
| 645 | <p class=note> | 646 | <p class="note"> |
| 646 | Note: The choice between IPv4 and IPv6 happens during a call to | 647 | Note: The choice between IPv4 and IPv6 happens during a call to |
| 647 | <a href=#bind><tt>bind</tt></a> or <a | 648 | <a href="#bind"><tt>bind</tt></a> or <a |
| 648 | href=#bind><tt>connect</tt></a>, depending on the address | 649 | href="#bind"><tt>connect</tt></a>, depending on the address |
| 649 | family obtained from the resolver. | 650 | family obtained from the resolver. |
| 650 | </p> | 651 | </p> |
| 651 | 652 | ||
| 652 | <p class=note> | 653 | <p class="note"> |
| 653 | Note: Before the choice between IPv4 and IPv6 happens, | 654 | Note: Before the choice between IPv4 and IPv6 happens, |
| 654 | the internal socket object is invalid and therefore <a | 655 | the internal socket object is invalid and therefore <a |
| 655 | href=#setoption><tt>setoption</tt></a> will fail. | 656 | href="#setoption"><tt>setoption</tt></a> will fail. |
| 656 | </p> | 657 | </p> |
| 657 | 658 | ||
| 658 | <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 659 | <!-- socket.tcp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 659 | 660 | ||
| 660 | <p class=name id="socket.tcp4"> | 661 | <p class="name" id="socket.tcp4"> |
| 661 | socket.<b>tcp4()</b> | 662 | socket.<b>tcp4()</b> |
| 662 | </p> | 663 | </p> |
| 663 | 664 | ||
| 664 | <p class=description> | 665 | <p class="description"> |
| 665 | Creates and returns an IPv4 TCP master object. A master object can | 666 | Creates and returns an IPv4 TCP master object. A master object can |
| 666 | be transformed into a server object with the method | 667 | be transformed into a server object with the method |
| 667 | <a href=#listen><tt>listen</tt></a> (after a call to <a | 668 | <a href="#listen"><tt>listen</tt></a> (after a call to <a |
| 668 | href=#bind><tt>bind</tt></a>) or into a client object with | 669 | href="#bind"><tt>bind</tt></a>) or into a client object with |
| 669 | the method <a href=#connect><tt>connect</tt></a>. The only other | 670 | the method <a href="#connect"><tt>connect</tt></a>. The only other |
| 670 | method supported by a master object is the | 671 | method supported by a master object is the |
| 671 | <a href=#close><tt>close</tt></a> method.</p> | 672 | <a href="#close"><tt>close</tt></a> method.</p> |
| 672 | 673 | ||
| 673 | <p class=return> | 674 | <p class="return"> |
| 674 | In case of success, a new master object is returned. In case of error, | 675 | In case of success, a new master object is returned. In case of error, |
| 675 | <b><tt>nil</tt></b> is returned, followed by an error message. | 676 | <b><tt>nil</tt></b> is returned, followed by an error message. |
| 676 | </p> | 677 | </p> |
| 677 | 678 | ||
| 678 | <!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 679 | <!-- socket.tcp6 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 679 | 680 | ||
| 680 | <p class=name id="socket.tcp6"> | 681 | <p class="name" id="socket.tcp6"> |
| 681 | socket.<b>tcp6()</b> | 682 | socket.<b>tcp6()</b> |
| 682 | </p> | 683 | </p> |
| 683 | 684 | ||
| 684 | <p class=description> | 685 | <p class="description"> |
| 685 | Creates and returns an IPv6 TCP master object. A master object can | 686 | Creates and returns an IPv6 TCP master object. A master object can |
| 686 | be transformed into a server object with the method | 687 | be transformed into a server object with the method |
| 687 | <a href=#listen><tt>listen</tt></a> (after a call to <a | 688 | <a href="#listen"><tt>listen</tt></a> (after a call to <a |
| 688 | href=#bind><tt>bind</tt></a>) or into a client object with | 689 | href="#bind"><tt>bind</tt></a>) or into a client object with |
| 689 | the method <a href=#connect><tt>connect</tt></a>. The only other | 690 | the method <a href="#connect"><tt>connect</tt></a>. The only other |
| 690 | method supported by a master object is the | 691 | method supported by a master object is the |
| 691 | <a href=#close><tt>close</tt></a> method.</p> | 692 | <a href="#close"><tt>close</tt></a> method.</p> |
| 692 | 693 | ||
| 693 | <p class=return> | 694 | <p class="return"> |
| 694 | In case of success, a new master object is returned. In case of error, | 695 | In case of success, a new master object is returned. In case of error, |
| 695 | <b><tt>nil</tt></b> is returned, followed by an error message. | 696 | <b><tt>nil</tt></b> is returned, followed by an error message. |
| 696 | </p> | 697 | </p> |
| 697 | 698 | ||
| 698 | <p class=note> | 699 | <p class="note"> |
| 699 | Note: The TCP object returned will have the option | 700 | Note: The TCP object returned will have the option |
| 700 | "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. | 701 | "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. |
| 701 | </p> | 702 | </p> |
| @@ -704,10 +705,10 @@ Note: The TCP object returned will have the option | |||
| 704 | 705 | ||
| 705 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 706 | <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 706 | 707 | ||
| 707 | <div class=footer> | 708 | <div class="footer"> |
| 708 | <hr> | 709 | <hr> |
| 709 | <center> | 710 | <center> |
| 710 | <p class=bar> | 711 | <p class="bar"> |
| 711 | <a href="index.html">home</a> · | 712 | <a href="index.html">home</a> · |
| 712 | <a href="index.html#down">download</a> · | 713 | <a href="index.html#down">download</a> · |
| 713 | <a href="installation.html">installation</a> · | 714 | <a href="installation.html">installation</a> · |
diff --git a/doc/udp.html b/doc/udp.html index 4618aad..db711cb 100644 --- a/doc/udp.html +++ b/doc/udp.html | |||
| @@ -13,17 +13,17 @@ | |||
| 13 | 13 | ||
| 14 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 14 | <!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 15 | 15 | ||
| 16 | <div class=header> | 16 | <div class="header"> |
| 17 | <hr> | 17 | <hr> |
| 18 | <center> | 18 | <center> |
| 19 | <table summary="LuaSocket logo"> | 19 | <table summary="LuaSocket logo"> |
| 20 | <tr><td align=center><a href="http://www.lua.org"> | 20 | <tr><td align="center"><a href="http://www.lua.org"> |
| 21 | <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png"> | 21 | <img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png"> |
| 22 | </a></td></tr> | 22 | </a></td></tr> |
| 23 | <tr><td align=center valign=top>Network support for the Lua language | 23 | <tr><td align="center" valign="top">Network support for the Lua language |
| 24 | </td></tr> | 24 | </td></tr> |
| 25 | </table> | 25 | </table> |
| 26 | <p class=bar> | 26 | <p class="bar"> |
| 27 | <a href="index.html">home</a> · | 27 | <a href="index.html">home</a> · |
| 28 | <a href="index.html#download">download</a> · | 28 | <a href="index.html#download">download</a> · |
| 29 | <a href="installation.html">installation</a> · | 29 | <a href="installation.html">installation</a> · |
| @@ -71,26 +71,26 @@ unconnected:<b>getoption()</b> | |||
| 71 | 71 | ||
| 72 | <p class="description"> | 72 | <p class="description"> |
| 73 | Gets an option value from the UDP object. | 73 | Gets an option value from the UDP object. |
| 74 | See <a href=#setoption><tt>setoption</tt></a> for | 74 | See <a href="#setoption"><tt>setoption</tt></a> for |
| 75 | description of the option names and values. | 75 | description of the option names and values. |
| 76 | </p> | 76 | </p> |
| 77 | 77 | ||
| 78 | <p class="parameters"><tt>Option</tt> is a string with the option name. | 78 | <p class="parameters"><tt>Option</tt> is a string with the option name. |
| 79 | <ul> | 79 | <ul> |
| 80 | <li> '<tt>dontroute</tt>' | 80 | <li> '<tt>dontroute</tt>'</li> |
| 81 | <li> '<tt>broadcast</tt>' | 81 | <li> '<tt>broadcast</tt>'</li> |
| 82 | <li> '<tt>reuseaddr</tt>' | 82 | <li> '<tt>reuseaddr</tt>'</li> |
| 83 | <li> '<tt>reuseport</tt>' | 83 | <li> '<tt>reuseport</tt>'</li> |
| 84 | <li> '<tt>ip-multicast-loop</tt>' | 84 | <li> '<tt>ip-multicast-loop</tt>'</li> |
| 85 | <li> '<tt>ipv6-v6only</tt>' | 85 | <li> '<tt>ipv6-v6only</tt>'</li> |
| 86 | <li> '<tt>ip-multicast-if</tt>' | 86 | <li> '<tt>ip-multicast-if</tt>'</li> |
| 87 | <li> '<tt>ip-multicast-ttl</tt>' | 87 | <li> '<tt>ip-multicast-ttl</tt>'</li> |
| 88 | <li> '<tt>ip-add-membership</tt>' | 88 | <li> '<tt>ip-add-membership</tt>'</li> |
| 89 | <li> '<tt>ip-drop-membership</tt>' | 89 | <li> '<tt>ip-drop-membership</tt>'</li> |
| 90 | </ul> | 90 | </ul> |
| 91 | </p> | 91 | </p> |
| 92 | 92 | ||
| 93 | <p class=return> | 93 | <p class="return"> |
| 94 | The method returns the option <tt>value</tt> in case of | 94 | The method returns the option <tt>value</tt> in case of |
| 95 | success, or | 95 | success, or |
| 96 | <b><tt>nil</tt></b> followed by an error message otherwise. | 96 | <b><tt>nil</tt></b> followed by an error message otherwise. |
| @@ -108,7 +108,7 @@ associated with a connected UDP object. | |||
| 108 | </p> | 108 | </p> |
| 109 | 109 | ||
| 110 | 110 | ||
| 111 | <p class=return> | 111 | <p class="return"> |
| 112 | Returns a string with the IP address of the peer, the | 112 | Returns a string with the IP address of the peer, the |
| 113 | port number that peer is using for the connection, | 113 | port number that peer is using for the connection, |
| 114 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | 114 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). |
| @@ -131,7 +131,7 @@ Returns the local address information associated to the object. | |||
| 131 | </p> | 131 | </p> |
| 132 | 132 | ||
| 133 | 133 | ||
| 134 | <p class=return> | 134 | <p class="return"> |
| 135 | The method returns a string with local IP address, a number with | 135 | The method returns a string with local IP address, a number with |
| 136 | the local port, | 136 | the local port, |
| 137 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). | 137 | and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>"). |
| @@ -148,12 +148,12 @@ wild-card address). | |||
| 148 | 148 | ||
| 149 | <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 149 | <!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 150 | 150 | ||
| 151 | <p class=name id="gettimeout"> | 151 | <p class="name" id="gettimeout"> |
| 152 | connected:<b>settimeout(</b>value<b>)</b><br> | 152 | connected:<b>settimeout(</b>value<b>)</b><br> |
| 153 | unconnected:<b>settimeout(</b>value<b>)</b> | 153 | unconnected:<b>settimeout(</b>value<b>)</b> |
| 154 | </p> | 154 | </p> |
| 155 | 155 | ||
| 156 | <p class=description> | 156 | <p class="description"> |
| 157 | Returns the current timeout value. | 157 | Returns the current timeout value. |
| 158 | </p> | 158 | </p> |
| 159 | 159 | ||
| @@ -180,8 +180,8 @@ the excess bytes are discarded. If there are less then | |||
| 180 | <tt>size</tt> bytes available in the current datagram, the | 180 | <tt>size</tt> bytes available in the current datagram, the |
| 181 | available bytes are returned. | 181 | available bytes are returned. |
| 182 | If <tt>size</tt> is omitted, the | 182 | If <tt>size</tt> is omitted, the |
| 183 | compile-time constant <a | 183 | compile-time constant <a href="socket.html#datagramsize"> |
| 184 | href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used | 184 | <tt>socket._DATAGRAMSIZE</tt></a> is used |
| 185 | (it defaults to 8192 bytes). Larger sizes will cause a | 185 | (it defaults to 8192 bytes). Larger sizes will cause a |
| 186 | temporary buffer to be allocated for the operation. | 186 | temporary buffer to be allocated for the operation. |
| 187 | </p> | 187 | </p> |
| @@ -286,45 +286,45 @@ name, and <tt>value</tt> depends on the option being set: | |||
| 286 | <ul> | 286 | <ul> |
| 287 | <li> '<tt>dontroute</tt>': Indicates that outgoing | 287 | <li> '<tt>dontroute</tt>': Indicates that outgoing |
| 288 | messages should bypass the standard routing facilities. | 288 | messages should bypass the standard routing facilities. |
| 289 | Receives a boolean value; | 289 | Receives a boolean value;</li> |
| 290 | <li> '<tt>broadcast</tt>': Requests permission to send | 290 | <li> '<tt>broadcast</tt>': Requests permission to send |
| 291 | broadcast datagrams on the socket. | 291 | broadcast datagrams on the socket. |
| 292 | Receives a boolean value; | 292 | Receives a boolean value;</li> |
| 293 | <li> '<tt>reuseaddr</tt>': Indicates that the rules used in | 293 | <li> '<tt>reuseaddr</tt>': Indicates that the rules used in |
| 294 | validating addresses supplied in a <tt>bind()</tt> call | 294 | validating addresses supplied in a <tt>bind()</tt> call |
| 295 | should allow reuse of local addresses. | 295 | should allow reuse of local addresses. |
| 296 | Receives a boolean value; | 296 | Receives a boolean value;</li> |
| 297 | <li> '<tt>reuseport</tt>': Allows completely duplicate | 297 | <li> '<tt>reuseport</tt>': Allows completely duplicate |
| 298 | bindings by multiple processes if they all set | 298 | bindings by multiple processes if they all set |
| 299 | '<tt>reuseport</tt>' before binding the port. | 299 | '<tt>reuseport</tt>' before binding the port. |
| 300 | Receives a boolean value; | 300 | Receives a boolean value;</li> |
| 301 | <li> '<tt>ip-multicast-loop</tt>': | 301 | <li> '<tt>ip-multicast-loop</tt>': |
| 302 | Specifies whether or not a copy of an outgoing multicast | 302 | Specifies whether or not a copy of an outgoing multicast |
| 303 | datagram is delivered to the sending host as long as it is a | 303 | datagram is delivered to the sending host as long as it is a |
| 304 | member of the multicast group. | 304 | member of the multicast group. |
| 305 | Receives a boolean value; | 305 | Receives a boolean value;</li> |
| 306 | <li> '<tt>ipv6-v6only</tt>': | 306 | <li> '<tt>ipv6-v6only</tt>': |
| 307 | Specifies whether to restrict <tt>inet6</tt> sockets to | 307 | Specifies whether to restrict <tt>inet6</tt> sockets to |
| 308 | sending and receiving only IPv6 packets. | 308 | sending and receiving only IPv6 packets. |
| 309 | Receive a boolean value; | 309 | Receive a boolean value;</li> |
| 310 | <li> '<tt>ip-multicast-if</tt>': | 310 | <li> '<tt>ip-multicast-if</tt>': |
| 311 | Sets the interface over which outgoing multicast datagrams | 311 | Sets the interface over which outgoing multicast datagrams |
| 312 | are sent. | 312 | are sent. |
| 313 | Receives an IP address; | 313 | Receives an IP address;</li> |
| 314 | <li> '<tt>ip-multicast-ttl</tt>': | 314 | <li> '<tt>ip-multicast-ttl</tt>': |
| 315 | Sets the Time To Live in the IP header for outgoing | 315 | Sets the Time To Live in the IP header for outgoing |
| 316 | multicast datagrams. | 316 | multicast datagrams. |
| 317 | Receives a number; | 317 | Receives a number;</li> |
| 318 | <li> '<tt>ip-add-membership</tt>': | 318 | <li> '<tt>ip-add-membership</tt>': |
| 319 | Joins the multicast group specified. | 319 | Joins the multicast group specified. |
| 320 | Receives a table with fields | 320 | Receives a table with fields |
| 321 | <tt>multiaddr</tt> and <tt>interface</tt>, each containing an | 321 | <tt>multiaddr</tt> and <tt>interface</tt>, each containing an |
| 322 | IP address; | 322 | IP address;</li> |
| 323 | <li> '<tt>ip-drop-membership</tt>': Leaves the multicast | 323 | <li> '<tt>ip-drop-membership</tt>': Leaves the multicast |
| 324 | group specified. | 324 | group specified. |
| 325 | Receives a table with fields | 325 | Receives a table with fields |
| 326 | <tt>multiaddr</tt> and <tt>interface</tt>, each containing an | 326 | <tt>multiaddr</tt> and <tt>interface</tt>, each containing an |
| 327 | IP address. | 327 | IP address.</li> |
| 328 | </ul> | 328 | </ul> |
| 329 | 329 | ||
| 330 | <p class="return"> | 330 | <p class="return"> |
| @@ -332,7 +332,7 @@ The method returns 1 in case of success, or | |||
| 332 | <b><tt>nil</tt></b> followed by an error message otherwise. | 332 | <b><tt>nil</tt></b> followed by an error message otherwise. |
| 333 | </p> | 333 | </p> |
| 334 | 334 | ||
| 335 | <p class=note> | 335 | <p class="note"> |
| 336 | Note: The descriptions above come from the man pages. | 336 | Note: The descriptions above come from the man pages. |
| 337 | </p> | 337 | </p> |
| 338 | 338 | ||
| @@ -381,11 +381,11 @@ is recommended when the same peer is used for several transmissions | |||
| 381 | and can result in up to 30% performance gains. | 381 | and can result in up to 30% performance gains. |
| 382 | </p> | 382 | </p> |
| 383 | 383 | ||
| 384 | <p class=note> | 384 | <p class="note"> |
| 385 | Note: Starting with LuaSocket 3.0, the host name resolution | 385 | Note: Starting with LuaSocket 3.0, the host name resolution |
| 386 | depends on whether the socket was created by <a | 386 | depends on whether the socket was created by <a |
| 387 | href=#socket.udp><tt>socket.udp</tt></a> or <a | 387 | href="#socket.udp"><tt>socket.udp</tt></a> or <a |
| 388 | href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from | 388 | href="#socket.udp6"><tt>socket.udp6</tt></a>. Addresses from |
| 389 | the appropriate family are tried in succession until the | 389 | the appropriate family are tried in succession until the |
| 390 | first success or until the last failure. | 390 | first success or until the last failure. |
| 391 | </p> | 391 | </p> |
| @@ -492,23 +492,23 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by | |||
| 492 | an error message. | 492 | an error message. |
| 493 | </p> | 493 | </p> |
| 494 | 494 | ||
| 495 | <p class=note> | 495 | <p class="note"> |
| 496 | Note: The choice between IPv4 and IPv6 happens during a call to | 496 | Note: The choice between IPv4 and IPv6 happens during a call to |
| 497 | <a href=#sendto><tt>sendto</tt></a>, <a | 497 | <a href="#sendto"><tt>sendto</tt></a>, <a |
| 498 | href=#setpeername><tt>setpeername</tt></a>, or <a | 498 | href="#setpeername"><tt>setpeername</tt></a>, or <a |
| 499 | href=#setsockname><tt>sockname</tt></a>, depending on the address | 499 | href="#setsockname"><tt>sockname</tt></a>, depending on the address |
| 500 | family obtained from the resolver. | 500 | family obtained from the resolver. |
| 501 | </p> | 501 | </p> |
| 502 | 502 | ||
| 503 | <p class=note> | 503 | <p class="note"> |
| 504 | Note: Before the choice between IPv4 and IPv6 happens, | 504 | Note: Before the choice between IPv4 and IPv6 happens, |
| 505 | the internal socket object is invalid and therefore <a | 505 | the internal socket object is invalid and therefore <a |
| 506 | href=#setoption><tt>setoption</tt></a> will fail. | 506 | href="#setoption"><tt>setoption</tt></a> will fail. |
| 507 | </p> | 507 | </p> |
| 508 | 508 | ||
| 509 | <!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 509 | <!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 510 | 510 | ||
| 511 | <p class="name" id="socket.udp"> | 511 | <p class="name" id="socket.udp4"> |
| 512 | socket.<b>udp4()</b> | 512 | socket.<b>udp4()</b> |
| 513 | </p> | 513 | </p> |
| 514 | 514 | ||
| @@ -564,7 +564,7 @@ returned. In case of error, <b><tt>nil</tt></b> is returned, followed by | |||
| 564 | an error message. | 564 | an error message. |
| 565 | </p> | 565 | </p> |
| 566 | 566 | ||
| 567 | <p class=note> | 567 | <p class="note"> |
| 568 | Note: The TCP object returned will have the option | 568 | Note: The TCP object returned will have the option |
| 569 | "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. | 569 | "<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>. |
| 570 | </p> | 570 | </p> |
| @@ -573,10 +573,10 @@ Note: The TCP object returned will have the option | |||
| 573 | 573 | ||
| 574 | <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> | 574 | <!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --> |
| 575 | 575 | ||
| 576 | <div class=footer> | 576 | <div class="footer"> |
| 577 | <hr> | 577 | <hr> |
| 578 | <center> | 578 | <center> |
| 579 | <p class=bar> | 579 | <p class="bar"> |
| 580 | <a href="index.html">home</a> · | 580 | <a href="index.html">home</a> · |
| 581 | <a href="index.html#download">download</a> · | 581 | <a href="index.html#download">download</a> · |
| 582 | <a href="installation.html">installation</a> · | 582 | <a href="installation.html">installation</a> · |