LuaSocket: DNS support

From f98977b2dac48fc66822402b095336e683715126 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 23 Mar 2022 00:09:53 +0300 Subject: Move doc→docs so we can serve it with GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/dns.html | 183 ------------- doc/ftp.html | 288 -------------------- doc/http.html | 339 ----------------------- doc/index.html | 215 --------------- doc/installation.html | 127 --------- doc/introduction.html | 333 ----------------------- doc/ltn12.html | 440 ------------------------------ doc/lua05.ppt | Bin 304128 -> 0 bytes doc/luasocket.png | Bin 11732 -> 0 bytes doc/mime.html | 477 -------------------------------- doc/reference.css | 55 ---- doc/reference.html | 261 ------------------ doc/smtp.html | 419 ----------------------------- doc/socket.html | 481 --------------------------------- doc/tcp.html | 732 -------------------------------------------------- doc/udp.html | 596 ---------------------------------------- doc/url.html | 328 ---------------------- 17 files changed, 5274 deletions(-) delete mode 100644 doc/dns.html delete mode 100644 doc/ftp.html delete mode 100644 doc/http.html delete mode 100644 doc/index.html delete mode 100644 doc/installation.html delete mode 100644 doc/introduction.html delete mode 100644 doc/ltn12.html delete mode 100644 doc/lua05.ppt delete mode 100644 doc/luasocket.png delete mode 100644 doc/mime.html delete mode 100644 doc/reference.css delete mode 100644 doc/reference.html delete mode 100644 doc/smtp.html delete mode 100644 doc/socket.html delete mode 100644 doc/tcp.html delete mode 100644 doc/udp.html delete mode 100644 doc/url.html (limited to 'doc') diff --git a/doc/dns.html b/doc/dns.html deleted file mode 100644 index 56ce3ba..0000000 --- a/doc/dns.html +++ /dev/null @@ -1,183 +0,0 @@ - - - - - - -LuaSocket: DNS support - - - - - - - - - - - -

DNS

- -

-IPv4 name resolution functions -dns.toip -and -dns.tohostname -return all information obtained from -the resolver in a table of the form: -

- -

-resolved4 = { - name = canonic-name, - alias = alias-list, - ip = ip-address-list -} -

- -

-Note that the alias list can be empty. -

- -

-The more general name resolution function -dns.getaddrinfo, which -supports both IPv6 and IPv4, -returns all information obtained from -the resolver in a table of the form: -

- -

-resolved6 = { - [1] = { - family = family-name-1, - addr = address-1 - }, - ... - [n] = { - family = family-name-n, - addr = address-n - } -} -

- -

-Here, family contains the string "inet" for IPv4 -addresses, and "inet6" for IPv6 addresses. -

- - - -

-socket.dns.getaddrinfo(address) -

- -

-Converts from host name to address. -

- -

-Address can be an IPv4 or IPv6 address or host name. -

- -

-The function returns a table with all information returned by -the resolver. In case of error, the function returns nil -followed by an error message. -

- - - -

-socket.dns.gethostname() -

- -

-Returns the standard host name for the machine as a string. -

- - - -

-socket.dns.tohostname(address) -

- -

-Converts from IPv4 address to host name. -

- -

-Address can be an IP address or host name. -

- -

-The function returns a string with the canonic host name of the given -address, followed by a table with all information returned by -the resolver. In case of error, the function returns nil -followed by an error message. -

- - - -

-socket.dns.toip(address) -

- -

-Converts from host name to IPv4 address. -

- -

-Address can be an IP address or host name. -

- -

-Returns a string with the first IP address found for address, -followed by a table with all information returned by the resolver. -In case of error, the function returns nil followed by an error -message. -

- - - - - - - diff --git a/doc/ftp.html b/doc/ftp.html deleted file mode 100644 index 7f7da2e..0000000 --- a/doc/ftp.html +++ /dev/null @@ -1,288 +0,0 @@ - - - - - - -LuaSocket: FTP support - - - - - - - - - - - -

FTP

- -

-FTP (File Transfer Protocol) is a protocol used to transfer files -between hosts. The ftp namespace offers thorough support -to FTP, under a simple interface. The implementation conforms to -RFC 959. -

- -

-High level functions are provided supporting the most common operations. -These high level functions are implemented on top of a lower level -interface. Using the low-level interface, users can easily create their -own functions to access any operation supported by the FTP -protocol. For that, check the implementation. -

- -

-To really benefit from this module, a good understanding of - -LTN012, Filters sources and sinks is necessary. -

- -

-To obtain the ftp namespace, run: -

- -

--- loads the FTP module and any libraries it requires
-local ftp = require("socket.ftp")
-

- -

-URLs MUST conform to -RFC 1738, -that is, an URL is a string in the form: -

- -

--[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i] -

- -

-The following constants in the namespace can be set to control the default behavior of -the FTP module: -

- -

PASSWORD: default anonymous password.
TIMEOUT: sets the timeout for all I/O operations;
USER: default anonymous user;

- - - - -

-ftp.get(url)
-ftp.get{
-  host = string,
-  sink = LTN12 sink,
-  argument or path = string,
-  [user = string,]
-  [password = string]
-  [command = string,]
-  [port = number,]
-  [type = string,]
-  [step = LTN12 pump step,]
-  [create = function]
-} -

- -

-The get function has two forms. The simple form has fixed -functionality: it downloads the contents of a URL and returns it as a -string. The generic form allows a lot more control, as explained -below. -

- -

-If the argument of the get function is a table, the function -expects at least the fields host, sink, and one of -argument or path (argument takes -precedence). Host is the server to connect to. Sink is -the simple -LTN12 -sink that will receive the downloaded data. Argument or -path give the target path to the resource in the server. The -optional arguments are the following: -

user, password: User name and password used for -authentication. Defaults to "ftp:anonymous@anonymous.org";
command: The FTP command used to obtain data. Defaults to -"retr", but see example below;
port: The port to used for the control connection. Defaults to 21;
type: The transfer mode. Can take values "i" or -"a". Defaults to whatever is the server default;
step: -LTN12 -pump step function used to pass data from the -server to the sink. Defaults to the LTN12 pump.step function;
create: An optional function to be used instead of -socket.tcp when the communications socket is created.

- -

-If successful, the simple version returns the URL contents as a -string, and the generic function returns 1. In case of error, both -functions return nil and an error message describing the -error. -

- -

--- load the ftp support
-local ftp = require("socket.ftp")
-
--- Log as user "anonymous" on server "ftp.tecgraf.puc-rio.br",
--- and get file "lua.tar.gz" from directory "pub/lua" as binary.
-f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")
-

- -

--- load needed modules
-local ftp = require("socket.ftp")
-local ltn12 = require("ltn12")
-local url = require("socket.url")
-
--- a function that returns a directory listing
-function nlst(u)
-    local t = {}
-    local p = url.parse(u)
-    p.command = "nlst"
-    p.sink = ltn12.sink.table(t)
-    local r, e = ftp.get(p)
-    return r and table.concat(t), e
-end
-

- - - -

-ftp.put(url, content)
-ftp.put{
-  host = string,
-  source = LTN12 sink,
-  argument or path = string,
-  [user = string,]
-  [password = string]
-  [command = string,]
-  [port = number,]
-  [type = string,]
-  [step = LTN12 pump step,]
-  [create = function]
-} -

- -

-The put function has two forms. The simple form has fixed -functionality: it uploads a string of content into a URL. The generic form -allows a lot more control, as explained below. -

- -

-If the argument of the put function is a table, the function -expects at least the fields host, source, and one of -argument or path (argument takes -precedence). Host is the server to connect to. Source is -the simple -LTN12 -source that will provide the contents to be uploaded. -Argument or -path give the target path to the resource in the server. The -optional arguments are the following: -

user, password: User name and password used for -authentication. Defaults to "ftp:anonymous@anonymous.org";
command: The FTP command used to send data. Defaults to -"stor", but see example below;
port: The port to used for the control connection. Defaults to 21;
type: The transfer mode. Can take values "i" or -"a". Defaults to whatever is the server default;
step: -LTN12 -pump step function used to pass data from the -server to the sink. Defaults to the LTN12 pump.step function;
create: An optional function to be used instead of -socket.tcp when the communications socket is created.

- -

-Both functions return 1 if successful, or nil and an error -message describing the reason for failure. -

- -

--- load the ftp support
-local ftp = require("socket.ftp")
-
--- Log as user "fulano" on server "ftp.example.com",
--- using password "silva", and store a file "README" with contents
--- "wrong password, of course"
-f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README",
-    "wrong password, of course")
-

- -

--- load the ftp support
-local ftp = require("socket.ftp")
-local ltn12 = require("ltn12")
-
--- Log as user "fulano" on server "ftp.example.com",
--- using password "silva", and append to the remote file "LOG", sending the
--- contents of the local file "LOCAL-LOG"
-f, e = ftp.put{
-  host = "ftp.example.com",
-  user = "fulano",
-  password = "silva",
-  command = "appe",
-  argument = "LOG",
-  source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
-}
-

- - - - - - - - diff --git a/doc/http.html b/doc/http.html deleted file mode 100644 index 52b8a30..0000000 --- a/doc/http.html +++ /dev/null @@ -1,339 +0,0 @@ - - - - - - -LuaSocket: HTTP support - - - - - - - - - - - -

HTTP

- -

-HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange -information between web-browsers and servers. The http -namespace offers full support for the client side of the HTTP -protocol (i.e., -the facilities that would be used by a web-browser implementation). The -implementation conforms to the HTTP/1.1 standard, -RFC 2616. -

- -

-The module exports functions that provide HTTP functionality in different -levels of abstraction. From the simple -string oriented requests, through generic -LTN12 based, down to even lower-level if you bother to look through the source code. -

- -

-To obtain the http namespace, run: -

- -

--- loads the HTTP module and any libraries it requires
-local http = require("socket.http")
-

- -

-URLs must conform to -RFC 1738, -that is, an URL is a string in the form: -

- -

-[http://][<user>[:<password>]@]<host>[:<port>][/<path>]
-

- -

-MIME headers are represented as a Lua table in the form: -

- -

- - -
-headers = { - field-1-name = field-1-value, - field-2-name = field-2-value, - field-3-name = field-3-value, - ... - field-n-name = field-n-value -} -
-

- -

-Field names are case insensitive (as specified by the standard) and all -functions work with lowercase field names (but see -socket.headers.canonic). -Field values are left unmodified. -

- -

-Note: MIME headers are independent of order. Therefore, there is no problem -in representing them in a Lua table. -

- -

-The following constants can be set to control the default behavior of -the HTTP module: -

- -

PROXY: default proxy used for connections;
TIMEOUT: sets the timeout for all I/O operations;
USERAGENT: default user agent reported to server.

- -

-Note: These constants are global. Changing them will also -change the behavior other code that might be using LuaSocket. -

- - - -

-http.request(url [, body])
-http.request{
-  url = string,
-  [sink = LTN12 sink,]
-  [method = string,]
-  [headers = header-table,]
-  [source = LTN12 source],
-  [step = LTN12 pump step,]
-  [proxy = string,]
-  [redirect = boolean,]
-  [create = function,]
-  [maxredirects = number]
-} -

- -

-The request function has two forms. The simple form downloads -a URL using the GET or POST method and is based -on strings. The generic form performs any HTTP method and is -LTN12 based. -

- -

-If the first argument of the request function is a string, it -should be an url. In that case, if a body -is provided as a string, the function will perform a POST method -in the url. Otherwise, it performs a GET in the -url -

- -

-If the first argument is instead a table, the most important fields are -the url and the simple -LTN12 -sink that will receive the downloaded content. -Any part of the url can be overridden by including -the appropriate field in the request table. -If authentication information is provided, the function -uses the Basic Authentication Scheme (see note) -to retrieve the document. If sink is nil, the -function discards the downloaded data. The optional parameters are the -following: -

method: The HTTP request method. Defaults to "GET";
headers: Any additional HTTP headers to send with the request;
source: simple -LTN12 -source to provide the request body. If there -is a body, you need to provide an appropriate "content-length" -request header field, or the function will attempt to send the body as -"chunked" (something few servers support). Defaults to the empty source;
step: -LTN12 -pump step function used to move data. -Defaults to the LTN12 pump.step function.
proxy: The URL of a proxy server to use. Defaults to no proxy;
redirect: Set to false to prevent the -function from automatically following 301 or 302 server redirect messages;
create: An optional function to be used instead of -socket.tcp when the communications socket is created.
maxredirects: An optional number specifying the maximum number of - redirects to follow. Defaults to 5 if not specified. A boolean - false value means no maximum (unlimited).

- -

-In case of failure, the function returns nil followed by an -error message. If successful, the simple form returns the response -body as a string, followed by the response status code, the response -headers and the response status line. The generic function returns the same -information, except the first return value is just the number 1 (the body -goes to the sink). -

- -

-Even when the server fails to provide the contents of the requested URL (URL not found, for example), -it usually returns a message body (a web page informing the -URL was not found or some other useless page). To make sure the -operation was successful, check the returned status code. For -a list of the possible values and their meanings, refer to RFC 2616. -

- -

-Here are a few examples with the simple interface: -

- -

--- load the http module
-local io = require("io")
-local http = require("socket.http")
-local ltn12 = require("ltn12")
-
--- connect to server "www.cs.princeton.edu" and retrieves this manual
--- file from "~diego/professional/luasocket/http.html" and print it to stdout
-http.request{
-    url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html",
-    sink = ltn12.sink.file(io.stdout)
-}
-
--- connect to server "www.example.com" and tries to retrieve
--- "/private/index.html". Fails because authentication is needed.
-b, c, h = http.request("http://www.example.com/private/index.html")
--- b returns some useless page telling about the denied access,
--- h returns authentication information
--- and c returns with value 401 (Authentication Required)
-
--- tries to connect to server "wrong.host" to retrieve "/"
--- and fails because the host does not exist.
-r, e = http.request("http://wrong.host/")
--- r is nil, and e returns with value "host not found"
-

- -

-And here is an example using the generic interface: -

- -

--- load the http module
-http = require("socket.http")
-
--- Requests information about a document, without downloading it.
--- Useful, for example, if you want to display a download gauge and need
--- to know the size of the document in advance
-r, c, h = http.request {
-  method = "HEAD",
-  url = "http://www.tecgraf.puc-rio.br/~diego"
-}
--- r is 1, c is 200, and h would return the following headers:
--- h = {
---   date = "Tue, 18 Sep 2001 20:42:21 GMT",
---   server = "Apache/1.3.12 (Unix)  (Red Hat/Linux)",
---   ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
---   ["content-length"] = 15652,
---   ["connection"] = "close",
---   ["content-Type"] = "text/html"
--- }
-

- -

-Note: When sending a POST request, simple interface adds a -"Content-type: application/x-www-form-urlencoded" -header to the request. This is the type used by -HTML forms. If you need another type, use the generic -interface. -

- -

-Note: Some URLs are protected by their -servers from anonymous download. For those URLs, the server must receive -some sort of authentication along with the request or it will deny -download and return status "401 Authentication Required". -

- -

-The HTTP/1.1 standard defines two authentication methods: the Basic -Authentication Scheme and the Digest Authentication Scheme, both -explained in detail in -RFC 2068. -

- -

The Basic Authentication Scheme sends -<user> and -<password> unencrypted to the server and is therefore -considered unsafe. Unfortunately, by the time of this implementation, -the wide majority of servers and browsers support the Basic Scheme only. -Therefore, this is the method used by the toolkit whenever -authentication is required. -

- -

--- load required modules
-http = require("socket.http")
-mime = require("mime")
-
--- Connect to server "www.example.com" and tries to retrieve
--- "/private/index.html", using the provided name and password to
--- authenticate the request
-b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html")
-
--- Alternatively, one could fill the appropriate header and authenticate
--- the request directly.
-r, c = http.request {
-  url = "http://www.example.com/private/index.html",
-  headers = { authorization = "Basic " .. (mime.b64("fulano:silva")) }
-}
-

- - - - - - - diff --git a/doc/index.html b/doc/index.html deleted file mode 100644 index e92b4d4..0000000 --- a/doc/index.html +++ /dev/null @@ -1,215 +0,0 @@ - - - - - - -LuaSocket: Network support for the Lua language - - - - - - - - - - - -

What is LuaSocket?

- -

-The core support has been implemented so that it is both efficient and -simple to use. It is available to any Lua application once it has been -properly initialized by the interpreter in use. The code has been tested -and runs well on several Windows and UNIX platforms.

- -

-Among the support modules, the most commonly used implement the -SMTP -(sending e-mails), -HTTP -(WWW access) and -FTP -(uploading and downloading files) client -protocols. These provide a very natural and generic interface to the -functionality defined by each protocol. -In addition, you will find that the -MIME (common encodings), -URL -(anything you could possible want to do with one) and -LTN12 -(filters, sinks, sources and pumps) modules can be very handy. -

- -

-The library is available under the same - -terms and conditions as the Lua language, the MIT license. The idea is -that if you can use Lua in a project, you should also be able to use -LuaSocket. -

- -

-Copyright © 1999-2013 Diego Nehab. All rights reserved.
-Author: Diego Nehab -

- - - -

Download

- -

-LuaSocket version 3.0-rc1 is now available for download! -It is compatible with Lua 5.1 and 5.2, and has -been tested on Windows XP, Linux, and Mac OS X. Chances -are it works well on most UNIX distributions and Windows flavors. -

- -

-The current version of the library can be found at -the LuaSocket -project page on GitHub. Besides the full C and Lua source code -for the library, the distribution contains several examples, -this user's manual and basic test procedures. -

- -

Take a look at the installation section of the -manual to find out how to properly install the library. -

- - - -

Special thanks

- -

-This marks the first release of LuaSocket that -wholeheartedly embraces the open-source development -philosophy. After a long hiatus, Matthew Wild finally -convinced me it was time for a release including IPv6 and -Lua 5.2 support. It was more work than we anticipated. -Special thanks to Sam Roberts, Florian Zeitz, and Paul -Aurich, Liam Devine, Alexey Melnichuk, and everybody else -that has helped bring this library back to life. -

- - - -

What's New

- -

-Main changes for LuaSocket 3.0-rc1 are IPv6 support -and Lua 5.2 compatibility. -

- -

Added: Compatible with Lua 5.2

Note that unless you define LUA_COMPAT_MODULE, -package tables will not be exported as globals!

Added: IPv6 support;

Socket.connect and socket.bind support IPv6 addresses;
Getpeername and getsockname support -IPv6 addresses, and return the socket family as a third value;
URL module updated to support IPv6 host names;
New socket.tcp6 and socket.udp6 functions;
New socket.dns.getaddrinfo and - socket.dns.getnameinfo functions;

Added: getoption method;
Fixed: url.unescape was returning additional values;
Fixed: mime.qp, mime.unqp, - mime.b64, and mime.unb64 could - mistaking their own stack slots for functions arguments;
Fixed: Receiving zero-length datagram is now possible;
Improved: Hidden all internal library symbols;
Improved: Better error messages;
Improved: Better documentation of socket options.
Fixed: manual sample of HTTP authentication now uses correct - "authorization" header (Alexandre Ittner);
Fixed: failure on bind() was destroying the socket (Sam Roberts);
Fixed: receive() returns immediatelly if prefix can satisfy - bytes requested (M Joonas Pihlaja);
Fixed: multicast didn't work on Windows, or anywhere - else for that matter (Herbert Leuwer, Adrian Sietsma);
Fixed: select() now reports an error when called with more - sockets than FD_SETSIZE (Lorenzo Leonini);
Fixed: manual links to home.html changed to index.html -(Robert Hahn);
Fixed: mime.unb64() would return an empty string on results that started - with a null character (Robert Raschke);
Fixed: HTTP now automatically redirects on 303 and 307 (Jonathan Gray);
Fixed: calling sleep() with negative numbers could - block forever, wasting CPU. Now it returns immediately (MPB);
Improved: FTP commands are now sent in upper case to - help buggy servers (Anders Eurenius);
Improved: known headers now sent in canonic - capitalization to help buggy servers (Joseph Stewart);
Improved: Clarified tcp:receive() in the manual (MPB);
Improved: Decent makefiles (LHF).
Fixed: RFC links in documentation now point to IETF (Cosmin Apreutesei).

- - - -

Old Versions

- -

-All previous versions of the LuaSocket library can be downloaded -here. Although these versions are no longer supported, they are -still available for those that have compatibility issues. -

- - - - - - - diff --git a/doc/installation.html b/doc/installation.html deleted file mode 100644 index 28a9fbb..0000000 --- a/doc/installation.html +++ /dev/null @@ -1,127 +0,0 @@ - - - - - - -LuaSocket: Installation - - - - - - - - - - - -

Installation

- -

Here we describe the standard distribution. If the -standard doesn't meet your needs, we refer you to the Lua -discussion list, where any question about the package scheme -will likely already have been answered.

- -

Directory structure

- -

On Unix systems, the standard distribution uses two base -directories, one for system dependent files, and another for system -independent files. Let's call these directories <CDIR> -and <LDIR>, respectively. -For example, in my laptp, Lua 5.1 is configured to -use '/usr/local/lib/lua/5.1' for -<CDIR> and '/usr/local/share/lua/5.1' for -<LDIR>. On Windows, <CDIR> -usually points to the directory where the Lua executable is -found, and <LDIR> points to a -lua/ directory inside <CDIR>. (These -settings can be overridden by environment variables -LUA_PATH and LUA_CPATH. See the Lua -documentation for details.) Here is the standard LuaSocket -distribution directory structure:

- -

-<LDIR>/ltn12.lua
-<LDIR>/socket.lua
-<CDIR>/socket/core.dll
-<LDIR>/socket/http.lua
-<LDIR>/socket/tp.lua
-<LDIR>/socket/ftp.lua
-<LDIR>/socket/smtp.lua
-<LDIR>/socket/url.lua
-<LDIR>/mime.lua
-<CDIR>/mime/core.dll
-

- -

Naturally, on Unix systems, core.dll -would be replaced by core.so. -

- -

Using LuaSocket

- -

With the above setup, and an interpreter with shared library support, -it should be easy to use LuaSocket. Just fire the interpreter and use the -require function to gain access to whatever module you need:

- -

-Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
-> socket = require("socket")
-> print(socket._VERSION)
---> LuaSocket 3.0-rc1
-

- -

Each module loads their dependencies automatically, so you only need to -load the modules you directly depend upon:

- -

-Lua 5.2.2  Copyright (C) 1994-2013 Lua.org, PUC-Rio
-> http = require("socket.http")
-> print(http.request("http://www.impa.br/~diego/software/luasocket"))
---> homepage gets dumped to terminal
-

- - - - - - - diff --git a/doc/introduction.html b/doc/introduction.html deleted file mode 100644 index fd22f48..0000000 --- a/doc/introduction.html +++ /dev/null @@ -1,333 +0,0 @@ - - - - - - -LuaSocket: Introduction to the core - - - - - - - - - - - -

Introduction

- -

-LuaSocket is a Lua extension library -that is composed by two parts: a C core that provides support for the TCP -and UDP transport layers, and a set of Lua modules that add support for -the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and -downloading files) protocols and other functionality commonly needed by -applications that deal with the Internet. This introduction is about the C -core. -

- -

-Communication in LuaSocket is performed via I/O objects. These can -represent different network domains. Currently, support is provided for TCP -and UDP, but nothing prevents other developers from implementing SSL, Local -Domain, Pipes, File Descriptors etc. I/O objects provide a standard -interface to I/O across different domains and operating systems. -

- -

-The API design had two goals in mind. First, users -experienced with the C API to sockets should feel comfortable using LuaSocket. -Second, the simplicity and the feel of the Lua language should be -preserved. To achieve these goals, the LuaSocket API keeps the function names and semantics the C API whenever possible, but their usage in Lua has been greatly simplified. -

- - -

-One of the simplifications is the receive pattern capability. -Applications can read data from stream domains (such as TCP) -line by line, block by block, or until the connection is closed. -All I/O reads are buffered and the performance differences between -different receive patterns are negligible. -

- -

-Another advantage is the flexible timeout control -mechanism. As in C, all I/O operations are blocking by default. For -example, the send, -receive and -accept methods -of the TCP domain will block the caller application until -the operation is completed (if ever!). However, with a call to the -settimeout -method, an application can specify upper limits on -the time it can be blocked by LuaSocket (the "total" timeout), on -the time LuaSocket can internally be blocked by any OS call (the -"block" timeout) or a combination of the two. Each LuaSocket -call might perform several OS calls, so that the two timeout values are -not equivalent. -

- -

-Finally, the host name resolution is transparent, meaning that most -functions and methods accept both IP addresses and host names. In case a -host name is given, the library queries the system's resolver and -tries the main IP address returned. Note that direct use of IP addresses -is more efficient, of course. The -toip -and tohostname -functions from the DNS module are provided to convert between host names and IP addresses. -

- -

-Together, these changes make network programming in LuaSocket much simpler -than it is in C, as the following sections will show. -

- - - -

TCP

- -

-TCP (Transfer Control Protocol) is reliable stream protocol. In other -words, applications communicating through TCP can send and receive data as -an error free stream of bytes. Data is split in one end and -reassembled transparently on the other end. There are no boundaries in -the data transfers. The library allows users to read data from the -sockets in several different granularities: patterns are available for -lines, arbitrary sized blocks or "read up to connection closed", all with -good performance. -

- -

-The library distinguishes three types of TCP sockets: master, -client and server sockets. -

- -

-Master sockets are newly created TCP sockets returned by the function -socket.tcp. A master socket is -transformed into a server socket -after it is associated with a local address by a call to the -bind method followed by a call to the -listen. Conversely, a master socket -can be changed into a client socket with the method -connect, -which associates it with a remote address. -

- -

-On server sockets, applications can use the -accept method -to wait for a client connection. Once a connection is established, a -client socket object is returned representing this connection. The -other methods available for server socket objects are -getsockname, -setoption, -settimeout, and -close. -

- -

-Client sockets are used to exchange data between two applications over -the Internet. Applications can call the methods -send and -receive -to send and receive data. The other methods -available for client socket objects are -getsockname, -getpeername, -setoption, -settimeout, -shutdown, and -close. -

- -

-Example: -

-
-A simple echo server, using LuaSocket. The program binds to an ephemeral -port (one that is chosen by the operating system) on the local host and -awaits client connections on that port. When a connection is established, -the program reads a line from the remote end and sends it back, closing -the connection immediately. You can test it using the telnet -program. -
- -
--- load namespace
-local socket = require("socket")
--- create a TCP socket and bind it to the local host, at any port
-local server = assert(socket.bind("*", 0))
--- find out which port the OS chose for us
-local ip, port = server:getsockname()
--- print a message informing what's up
-print("Please telnet to localhost on port " .. port)
-print("After connecting, you have 10s to enter a line to be echoed")
--- loop forever waiting for clients
-while 1 do
-  -- wait for a connection from any client
-  local client = server:accept()
-  -- make sure we don't block waiting for this client's line
-  client:settimeout(10)
-  -- receive the line
-  local line, err = client:receive()
-  -- if there was no error, send it back to the client
-  if not err then client:send(line .. "\n") end
-  -- done with client, close the object
-  client:close()
-end
-
-

- - - -

UDP

- -

-UDP (User Datagram Protocol) is a non-reliable datagram protocol. In -other words, applications communicating through UDP send and receive -data as independent blocks, which are not guaranteed to reach the other -end. Even when they do reach the other end, they are not guaranteed to be -error free. Data transfers are atomic, one datagram at a time. Reading -only part of a datagram discards the rest, so that the following read -operation will act on the next datagram. The advantages are in -simplicity (no connection setup) and performance (no error checking or -error correction). -

- -

-Note that although no guarantees are made, these days -networks are so good that, under normal circumstances, few errors -happen in practice. -

- -

-An UDP socket object is created by the -socket.udp function. UDP -sockets do not need to be connected before use. The method -sendto -can be used immediately after creation to -send a datagram to IP address and port. Host names are not allowed -because performing name resolution for each packet would be forbiddingly -slow. Methods -receive and -receivefrom -can be used to retrieve datagrams, the latter returning the IP and port of -the sender as extra return values (thus being slightly less -efficient). -

- -

-When communication is performed repeatedly with a single peer, an -application should call the -setpeername method to specify a -permanent partner. Methods -sendto and -receivefrom -can no longer be used, but the method -send can be used to send data -directly to the peer, and the method -receive -will only return datagrams originating -from that peer. There is about 30% performance gain due to this practice. -

- -

-To associate an UDP socket with a local address, an application calls the -setsockname -method before sending any datagrams. Otherwise, the socket is -automatically bound to an ephemeral address before the first data -transmission and once bound the local address cannot be changed. -The other methods available for UDP sockets are -getpeername, -getsockname, -settimeout, -setoption and -close. -

- -

-Example: -

-A simple daytime client, using LuaSocket. The program connects to a remote -server and tries to retrieve the daytime, printing the answer it got or an -error message. -

- -

--- change here to the host an port you want to contact
-local host, port = "localhost", 13
--- load namespace
-local socket = require("socket")
--- convert host name to ip address
-local ip = assert(socket.dns.toip(host))
--- create a new UDP object
-local udp = assert(socket.udp())
--- contact daytime host
-assert(udp:sendto("anything", ip, port))
--- retrieve the answer and print results
-io.write(assert(udp:receive()))
-

- - - -

Support modules

- -

Although not covered in the introduction, LuaSocket offers -much more than TCP and UDP functionality. As the library -evolved, support for HTTP, FTP, -and SMTP were built on top of these. These modules -and many others are covered by the reference manual. -

- - - - - - - diff --git a/doc/ltn12.html b/doc/ltn12.html deleted file mode 100644 index fe3e3a0..0000000 --- a/doc/ltn12.html +++ /dev/null @@ -1,440 +0,0 @@ - - - - - - -LuaSocket: LTN12 module - - - - - - - - - - - -

LTN12

- -

The ltn12 namespace implements the ideas described in - -LTN012, Filters sources and sinks. This manual simply describes the -functions. Please refer to the LTN for a deeper explanation of the -functionality provided by this module. -

- -

-To obtain the ltn12 namespace, run: -

- -

--- loads the LTN21 module
-local ltn12 = require("ltn12")
-

- - - -

Filters

- - - -

-ltn12.filter.chain(filter₁, filter₂ -[, ... filter_N]) -

- -

-Returns a filter that passes all data it receives through each of a -series of given filters. -

- -

-Filter₁ to filter_N are simple -filters. -

- -

-The function returns the chained filter. -

- -

-The nesting of filters can be arbitrary. For instance, the useless filter -below doesn't do anything but return the data that was passed to it, -unaltered. -

- -

--- load required modules
-local ltn12 = require("ltn12")
-local mime = require("mime")
-
--- create a silly identity filter
-id = ltn12.filter.chain(
-  mime.encode("quoted-printable"),
-  mime.encode("base64"),
-  mime.decode("base64"),
-  mime.decode("quoted-printable")
-)
-

- - - -

-ltn12.filter.cycle(low [, ctx, extra]) -

- -

-Returns a high-level filter that cycles though a low-level filter by -passing it each chunk and updating a context between calls. -

- -

-Low is the low-level filter to be cycled, -ctx is the initial context and extra is any extra -argument the low-level filter might take. -

- -

-The function returns the high-level filter. -

- -

--- load the ltn12 module
-local ltn12 = require("ltn12")
-
--- the base64 mime filter factory
-encodet['base64'] = function()
-    return ltn12.filter.cycle(b64, "")
-end
-

- - - -

Pumps

- - - -

-ltn12.pump.all(source, sink) -

- -

-Pumps all data from a source to a sink. -

- -

-If successful, the function returns a value that evaluates to -true. In case -of error, the function returns a false value, followed by an error message. -

- - - -

-ltn12.pump.step(source, sink) -

- -

-Pumps one chunk of data from a source to a sink. -

- -

-If successful, the function returns a value that evaluates to -true. In case -of error, the function returns a false value, followed by an error message. -

- - - -

Sinks

- - - -

-ltn12.sink.chain(filter, sink) -

- -

-Creates and returns a new sink that passes data through a filter before sending it to a given sink. -

- - - -

-ltn12.sink.error(message) -

- -

-Creates and returns a sink that aborts transmission with the error -message. -

- - - -

-ltn12.sink.file(handle, message) -

- -

-Creates a sink that sends data to a file. -

- -

-Handle is a file handle. If handle is nil, -message should give the reason for failure. -

- -

-The function returns a sink that sends all data to the given handle -and closes the file when done, or a sink that aborts the transmission with -the error message -

- -

-In the following example, notice how the prototype is designed to -fit nicely with the io.open function. -

- -

--- load the ltn12 module
-local ltn12 = require("ltn12")
-
--- copy a file
-ltn12.pump.all(
-  ltn12.source.file(io.open("original.png", "rb")),
-  ltn12.sink.file(io.open("copy.png", "wb"))
-)
-

- - - -

-ltn12.sink.null() -

- -

-Returns a sink that ignores all data it receives. -

- - - -

-ltn12.sink.simplify(sink) -

- -

-Creates and returns a simple sink given a fancy sink. -

- - - -

-ltn12.sink.table([table]) -

- -

-Creates a sink that stores all chunks in a table. The chunks can later be -efficiently concatenated into a single string. -

- -

-Table is used to hold the chunks. If -nil, the function creates its own table. -

- -

-The function returns the sink and the table used to store the chunks. -

- -

--- load needed modules
-local http = require("socket.http")
-local ltn12 = require("ltn12")
-
--- a simplified http.get function
-function http.get(u)
-  local t = {}
-  local respt = request{
-    url = u,
-    sink = ltn12.sink.table(t)
-  }
-  return table.concat(t), respt.headers, respt.code
-end
-

- - - -

Sources

- - - -

-ltn12.source.cat(source₁ [, source₂, ..., -source_N]) -

- -

-Creates a new source that produces the concatenation of the data produced -by a number of sources. -

- -

-Source₁ to source_N are the original -sources. -

- -

-The function returns the new source. -

- - - -

-ltn12.source.chain(source, filter) -

- -

-Creates a new source that passes data through a filter -before returning it. -

- -

-The function returns the new source. -

- - - -

-ltn12.source.empty() -

- -

-Creates and returns an empty source. -

- - - -

-ltn12.source.error(message) -

- -

-Creates and returns a source that aborts transmission with the error -message. -

- - - -

-ltn12.source.file(handle, message) -

- -

-Creates a source that produces the contents of a file. -

- -

-Handle is a file handle. If handle is nil, -message should give the reason for failure. -

- -

-The function returns a source that reads chunks of data from -given handle and returns it to the user, -closing the file when done, or a source that aborts the transmission with -the error message -

- -

-In the following example, notice how the prototype is designed to -fit nicely with the io.open function. -

- -

--- load the ltn12 module
-local ltn12 = require("ltn12")
-
--- copy a file
-ltn12.pump.all(
-  ltn12.source.file(io.open("original.png", "rb")),
-  ltn12.sink.file(io.open("copy.png", "wb"))
-)
-

- - - -

-ltn12.source.simplify(source) -

- -

-Creates and returns a simple source given a fancy source. -

- - - -

-ltn12.source.string(string) -

- -

-Creates and returns a source that produces the contents of a -string, chunk by chunk. -

- - - -

-ltn12.source.table(table) -

- -

-Creates and returns a source that produces the numerically-indexed values of a table 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. -

- - - - - - - diff --git a/doc/lua05.ppt b/doc/lua05.ppt deleted file mode 100644 index e2b7ab4..0000000 Binary files a/doc/lua05.ppt and /dev/null differ diff --git a/doc/luasocket.png b/doc/luasocket.png deleted file mode 100644 index d24a954..0000000 Binary files a/doc/luasocket.png and /dev/null differ diff --git a/doc/mime.html b/doc/mime.html deleted file mode 100644 index ff4d8e8..0000000 --- a/doc/mime.html +++ /dev/null @@ -1,477 +0,0 @@ - - - - - - -LuaSocket: MIME module - - - - - - - - - - - -

MIME

- -

-The mime namespace offers filters that apply and remove common -content transfer encodings, such as Base64 and Quoted-Printable. -It also provides functions to break text into lines and change -the end-of-line convention. -MIME is described mainly in -RFC 2045, -2046, -2047, -2048, and -2049. -

- -

-All functionality provided by the MIME module -follows the ideas presented in - -LTN012, Filters sources and sinks. -

- -

-To obtain the mime namespace, run: -

- -

--- loads the MIME module and everything it requires
-local mime = require("mime")
-

- - - - -

High-level filters

- - - - -

-mime.decode("base64")
-mime.decode("quoted-printable") -

- -

-Returns a filter that decodes data from a given transfer content -encoding. -

- - - -

-mime.encode("base64")
-mime.encode("quoted-printable" [, mode]) -

- -

-Returns a filter that encodes data according to a given transfer content -encoding. -

- -

-In the Quoted-Printable case, the user can specify whether the data is -textual or binary, by passing the mode strings "text" or -"binary". Mode defaults to "text". -

- -

-Although both transfer content encodings specify a limit for the line -length, the encoding filters do not break text into lines (for -added flexibility). -Below is a filter that converts binary data to the Base64 transfer content -encoding and breaks it into lines of the correct size. -

- -

-base64 = ltn12.filter.chain(
-  mime.encode("base64"),
-  mime.wrap("base64")
-)
-

- -

-Note: Text data has to be converted to canonic form -before being encoded. -

- -

-base64 = ltn12.filter.chain(
-  mime.normalize(),
-  mime.encode("base64"),
-  mime.wrap("base64")
-)
-

- - - -

-mime.normalize([marker]) -

- -

-Converts most common end-of-line markers to a specific given marker. -

- -

-Marker is the new marker. It defaults to CRLF, the canonic -end-of-line marker defined by the MIME standard. -

- -

-The function returns a filter that performs the conversion. -

- -

-Note: There is no perfect solution to this problem. Different end-of-line -markers are an evil that will probably plague developers forever. -This function, however, will work perfectly for text created with any of -the most common end-of-line markers, i.e. the Mac OS (CR), the Unix (LF), -or the DOS (CRLF) conventions. Even if the data has mixed end-of-line -markers, the function will still work well, although it doesn't -guarantee that the number of empty lines will be correct. -

- - - -

-mime.stuff()
-

- -

-Creates and returns a filter that performs stuffing of SMTP messages. -

- -

-Note: The smtp.send function -uses this filter automatically. You don't need to chain it with your -source, or apply it to your message body. -

- - - -

-mime.wrap("text" [, length])
-mime.wrap("base64")
-mime.wrap("quoted-printable") -

- -

-Returns a filter that breaks data into lines. -

- -

-The "text" line-wrap filter simply breaks text into lines by -inserting CRLF end-of-line markers at appropriate positions. -Length defaults 76. -The "base64" line-wrap filter works just like the default -"text" line-wrap filter with default length. -The function can also wrap "quoted-printable" lines, taking care -not to break lines in the middle of an escaped character. In that case, the -line length is fixed at 76. -

- -

-For example, to create an encoding filter for the Quoted-Printable transfer content encoding of text data, do the following: -

- -

-qp = ltn12.filter.chain(
-  mime.normalize(),
-  mime.encode("quoted-printable"),
-  mime.wrap("quoted-printable")
-)
-

- -

-Note: To break into lines with a different end-of-line convention, apply -a normalization filter after the line break filter. -

- - - -

Low-level filters

- - - -

-A, B = mime.b64(C [, D]) -

- -

-Low-level filter to perform Base64 encoding. -

- -

-Note: The simplest use of this function is to encode a string into it's -Base64 transfer content encoding. Notice the extra parenthesis around the -call to mime.b64, to discard the second return value. -

- -

-print((mime.b64("diego:password")))
---> ZGllZ286cGFzc3dvcmQ=
-

- - -

-A, n = mime.dot(m [, B]) -

- -

-Low-level filter to perform SMTP stuffing and enable transmission of -messages containing the sequence "CRLF.CRLF". -

- -

-A is the stuffed version of B. 'n' gives the -number of characters from the sequence CRLF seen in the end of B. -'m' should tell the same, but for the previous chunk. -

- -

Note: The message body is defined to begin with -an implicit CRLF. Therefore, to stuff a message correctly, the -first m should have the value 2. -

- -

-print((string.gsub(mime.dot(2, ".\r\nStuffing the message.\r\n.\r\n."), "\r\n", "\\n")))
---> ..\nStuffing the message.\n..\n..
-

- -

-Note: The smtp.send function -uses this filter automatically. You don't need to -apply it again. -

- - - -

-A, B = mime.eol(C [, D, marker]) -

- -

-Low-level filter to perform end-of-line marker translation. -For each chunk, the function needs to know if the last character of the -previous chunk could be part of an end-of-line marker or not. This is the -context the function receives besides the chunk. An updated version of -the context is returned after each new chunk. -

- -

-A is the translated version of D. C is the -ASCII value of the last character of the previous chunk, if it was a -candidate for line break, or 0 otherwise. -B is the same as C, but for the current -chunk. Marker gives the new end-of-line marker and defaults to CRLF. -

- -

--- translates the end-of-line marker to UNIX
-unix = mime.eol(0, dos, "\n")
-

- - - -

-A, B = mime.qp(C [, D, marker]) -

- -

-Low-level filter to perform Quoted-Printable encoding. -

- -

-A is the encoded version of the largest prefix of -C..D -that can be encoded unambiguously. B has the remaining bytes of -C..D, before encoding. -If D is nil, A is padded with -the encoding of the remaining bytes of C. -Throughout encoding, occurrences of CRLF are replaced by the -marker, which itself defaults to CRLF. -

- -

-Note: The simplest use of this function is to encode a string into it's -Quoted-Printable transfer content encoding. -Notice the extra parenthesis around the call to mime.qp, to discard the second return value. -

- -

-print((mime.qp("ma��")))
---> ma=E7=E3=
-

- - - -

-A, m = mime.qpwrp(n [, B, length]) -

- -

-Low-level filter to break Quoted-Printable text into lines. -

- -

-A is a copy of B, broken into lines of at most -length bytes (defaults to 76). -'n' should tell how many bytes are left for the first -line of B and 'm' returns the number of bytes -left in the last line of A. -

- -

-Note: Besides breaking text into lines, this function makes sure the line -breaks don't fall in the middle of an escaped character combination. Also, -this function only breaks lines that are bigger than length bytes. -

- - - -

-A, B = mime.unb64(C [, D]) -

- -

-Low-level filter to perform Base64 decoding. -

- -

-A is the decoded version of the largest prefix of -C..D -that can be decoded unambiguously. B has the remaining bytes of -C..D, before decoding. -If D is nil, A is the empty string -and B returns whatever couldn't be decoded. -

- -

-Note: The simplest use of this function is to decode a string from it's -Base64 transfer content encoding. -Notice the extra parenthesis around the call to mime.unqp, to discard the second return value. -

- -

-print((mime.unb64("ZGllZ286cGFzc3dvcmQ=")))
---> diego:password
-

- - - -

-A, B = mime.unqp(C [, D]) -

- -

-Low-level filter to remove the Quoted-Printable transfer content encoding -from data. -

- -

-A is the decoded version of the largest prefix of -C..D -that can be decoded unambiguously. B has the remaining bytes of -C..D, before decoding. -If D is nil, A is augmented with -the encoding of the remaining bytes of C. -

- -

-Note: The simplest use of this function is to decode a string from it's -Quoted-Printable transfer content encoding. -Notice the extra parenthesis around the call to mime.unqp, to discard the second return value. -

- -

-print((mime.qp("ma=E7=E3=")))
---> ma��
-

- - - -

-A, m = mime.wrp(n [, B, length]) -

- -

-Low-level filter to break text into lines with CRLF marker. -Text is assumed to be in the normalize form. -

- -

-Note: This function only breaks lines that are bigger than -length bytes. The resulting line length does not include the CRLF -marker. -

- - - - - - - - diff --git a/doc/reference.css b/doc/reference.css deleted file mode 100644 index 04e38cf..0000000 --- a/doc/reference.css +++ /dev/null @@ -1,55 +0,0 @@ -body { - margin-left: 1em; - margin-right: 1em; - font-family: "Verdana", sans-serif; - background: #ffffff; -} - -tt { - font-family: "Andale Mono", monospace; -} - -h1, h2, h3, h4 { margin-left: 0em; } - - -h3 { padding-top: 1em; } - -p { margin-left: 1em; } - -p.name { - font-family: "Andale Mono", monospace; - padding-top: 1em; - margin-left: 0em; -} - -a[href] { color: #00007f; } - -blockquote { margin-left: 3em; } - -pre.example { - background: #ccc; - padding: 1em; - margin-left: 1em; - font-family: "Andale Mono", monospace; - font-size: small; -} - -hr { - margin-left: 0em; - background: #00007f; - border: 0px; - height: 1px; -} - -ul { list-style-type: disc; } - -table.index { border: 1px #00007f; } -table.index td { text-align: left; vertical-align: top; } -table.index ul { padding-top: 0em; margin-top: 0em; } - -h1:first-letter, -h2:first-letter, -h2:first-letter, -h3:first-letter { color: #00007f; } - -div.header, div.footer { margin-left: 0em; } diff --git a/doc/reference.html b/doc/reference.html deleted file mode 100644 index 2bc5f78..0000000 --- a/doc/reference.html +++ /dev/null @@ -1,261 +0,0 @@ - - - - - - -LuaSocket: Index to reference manual - - - - - - - - - - - -

Reference

- -

-DNS (in socket) -
-getaddrinfo, -gethostname, -tohostname, -toip. -
-

- - - -

-FTP -
-get, -put. -
-

- - - -

-HTTP -
-request. -
-

- - - -

-LTN12 -
-filter: -chain, -cycle. -
-
-pump: -all, -step. -
-
-sink: -chain, -error, -file, -null, -simplify, -table. -
-
-source: -cat, -chain, -empty, -error, -file, -simplify, -string, -table. -
-

- - - -

-MIME -
-high-level: -decode, -encode, -normalize, -stuff, -wrap. -
-
-low-level: -b64, -dot, -eol, -qp, -qpwrp, -unb64, -unqp, -wrp. -
-

- - - -

-SMTP -
-message, -send. -
-

- - - -

-Socket -
-bind, -connect, -connect4, -connect6, -_DATAGRAMSIZE, -_DEBUG, -dns, -gettime, -headers.canonic, -newtry, -protect, -select, -sink, -skip, -sleep, -_SETSIZE, -_SOCKETINVALID, -source, -tcp, -tcp4, -tcp6, -try, -udp, -udp4, -udp6, -_VERSION. -
-

- - - -

-TCP (in socket) -
-accept, -bind, -close, -connect, -dirty, -getfd, -getoption, -getpeername, -getsockname, -getstats, -gettimeout, -listen, -receive, -send, -setfd, -setoption, -setstats, -settimeout, -shutdown. -
-

- - - -

-UDP (in socket) -
-close, -getoption, -getpeername, -getsockname, -gettimeout, -receive, -receivefrom, -send, -sendto, -setpeername, -setsockname, -setoption, -settimeout. -
-

- - - -

-URL -
-absolute, -build, -build_path, -escape, -parse, -parse_path, -unescape. -
-

- - - - - - - diff --git a/doc/smtp.html b/doc/smtp.html deleted file mode 100644 index 787d0b1..0000000 --- a/doc/smtp.html +++ /dev/null @@ -1,419 +0,0 @@ - - - - - - -LuaSocket: SMTP support - - - - - - - - - - - -

SMTP

- -

The smtp namespace provides functionality to send e-mail -messages. The high-level API consists of two functions: one to -define an e-mail message, and another to actually send the message. -Although almost all users will find that these functions provide more than -enough functionality, the underlying implementation allows for even more -control (if you bother to read the code). -

- -

The implementation conforms to the Simple Mail Transfer Protocol, -RFC 2821. -Another RFC of interest is RFC 2822, -which governs the Internet Message Format. -Multipart messages (those that contain attachments) are part -of the MIME standard, but described mainly -in RFC 2046.

- -

In the description below, good understanding of LTN012, Filters -sources and sinks and the MIME module is -assumed. In fact, the SMTP module was the main reason for their -creation.

- -

-To obtain the smtp namespace, run: -

- -

--- loads the SMTP module and everything it requires
-local smtp = require("socket.smtp")
-

- -

-MIME headers are represented as a Lua table in the form: -

- -

- - -
-headers = { - field-1-name = field-1-value, - field-2-name = field-2-value, - field-3-name = field-3-value, - ... - field-n-name = field-n-value -} -
-

- -

-Field names are case insensitive (as specified by the standard) and all -functions work with lowercase field names (but see -socket.headers.canonic). -Field values are left unmodified. -

- -

-Note: MIME headers are independent of order. Therefore, there is no problem -in representing them in a Lua table. -

- -

-The following constants can be set to control the default behavior of -the SMTP module: -

- -

DOMAIN: domain used to greet the server;
PORT: default port used for the connection;
SERVER: default server used for the connection;
TIMEOUT: default timeout for all I/O operations;
ZONE: default time zone.

- - - -

-smtp.message(mesgt) -

- -

-Returns a simple -LTN12 source that sends an SMTP message body, possibly multipart (arbitrarily deep). -

- -

-The only parameter of the function is a table describing the message. -Mesgt has the following form (notice the recursive structure): -

- -

- - -
-mesgt = { - headers = header-table, - body = LTN12 source or string or -multipart-mesgt -} - -multipart-mesgt = { - [preamble = string,] - [1] = mesgt, - [2] = mesgt, - ... - [n] = mesgt, - [epilogue = string,] -} -
-

- -

-For a simple message, all that is needed is a set of headers -and the body. The message body can be given as a string -or as a simple -LTN12 -source. For multipart messages, the body is a table that -recursively defines each part as an independent message, plus an optional -preamble and epilogue. -

- -

-The function returns a simple -LTN12 -source that produces the -message contents as defined by mesgt, chunk by chunk. -Hopefully, the following -example will make things clear. When in doubt, refer to the appropriate RFC -as listed in the introduction.

- -

--- load the smtp support and its friends
-local smtp = require("socket.smtp")
-local mime = require("mime")
-local ltn12 = require("ltn12")
-
--- creates a source to send a message with two parts. The first part is
--- plain text, the second part is a PNG image, encoded as base64.
-source = smtp.message{
-  headers = {
-     -- Remember that headers are *ignored* by smtp.send.
-     from = "Sicrano de Oliveira <sicrano@example.com>",
-     to = "Fulano da Silva <fulano@example.com>",
-     subject = "Here is a message with attachments"
-  },
-  body = {
-    preamble = "If your client doesn't understand attachments, \r\n" ..
-               "it will still display the preamble and the epilogue.\r\n" ..
-               "Preamble will probably appear even in a MIME enabled client.",
-    -- first part: no headers means plain text, us-ascii.
-    -- The mime.eol low-level filter normalizes end-of-line markers.
-    [1] = {
-      body = mime.eol(0, [[
-        Lines in a message body should always end with CRLF.
-        The smtp module will *NOT* perform translation. However, the
-        send function *DOES* perform SMTP stuffing, whereas the message
-        function does *NOT*.
-      ]])
-    },
-    -- second part: headers describe content to be a png image,
-    -- sent under the base64 transfer content encoding.
-    -- notice that nothing happens until the message is actually sent.
-    -- small chunks are loaded into memory right before transmission and
-    -- translation happens on the fly.
-    [2] = {
-      headers = {
-        ["content-type"] = 'image/png; name="image.png"',
-        ["content-disposition"] = 'attachment; filename="image.png"',
-        ["content-description"] = 'a beautiful image',
-        ["content-transfer-encoding"] = "BASE64"
-      },
-      body = ltn12.source.chain(
-        ltn12.source.file(io.open("image.png", "rb")),
-        ltn12.filter.chain(
-          mime.encode("base64"),
-          mime.wrap()
-        )
-      )
-    },
-    epilogue = "This might also show up, but after the attachments"
-  }
-}
-
--- finally send it
-r, e = smtp.send{
-    from = "<sicrano@example.com>",
-    rcpt = "<fulano@example.com>",
-    source = source,
-}
-

- - - - -

-smtp.send{
-  from = string,
-  rcpt = string or string-table,
-  source = LTN12 source,
-  [user = string,]
-  [password = string,]
-  [server = string,]
-  [port = number,]
-  [domain = string,]
-  [step = LTN12 pump step,]
-  [create = function]
-} -

- -

-Sends a message to a recipient list. Since sending messages is not as -simple as downloading an URL from a FTP or HTTP server, this function -doesn't have a simple interface. However, see the -message source factory for -a very powerful way to define the message contents. -

- - -

-The sender is given by the e-mail address in the from field. -Rcpt is a Lua table with one entry for each recipient e-mail -address, or a string -in case there is just one recipient. -The contents of the message are given by a simple -LTN12 -source. Several arguments are optional: -

user, password: User and password for -authentication. The function will attempt LOGIN and PLAIN authentication -methods if supported by the server (both are unsafe);
server: Server to connect to. Defaults to "localhost";
port: Port to connect to. Defaults to 25;
domain: Domain name used to greet the server; Defaults to the -local machine host name;
step: -LTN12 -pump step function used to pass data from the -source to the server. Defaults to the LTN12 pump.step function;
create: An optional function to be used instead of -socket.tcp when the communications socket is created.

- -

-If successful, the function returns 1. Otherwise, the function returns -nil followed by an error message. -

- -

-Note: SMTP servers can be very picky with the format of e-mail -addresses. To be safe, use only addresses of the form -"<fulano@example.com>" in the from and -rcpt arguments to the send function. In headers, e-mail -addresses can take whatever form you like.

- -

-Big note: There is a good deal of misconception with the use of the -destination address field headers, i.e., the 'To', 'Cc', -and, more importantly, the 'Bcc' headers. Do not add a -'Bcc' header to your messages because it will probably do the -exact opposite of what you expect. -

- -

-Only recipients specified in the rcpt list will receive a copy of the -message. Each recipient of an SMTP mail message receives a copy of the -message body along with the headers, and nothing more. The headers -are part of the message and should be produced by the -LTN12 -source function. The rcpt list is not -part of the message and will not be sent to anyone. -

- -

-RFC 2822 -has two important and short sections, "3.6.3. Destination address -fields" and "5. Security considerations", explaining the proper -use of these headers. Here is a summary of what it says: -

- -

To: contains the address(es) of the primary recipient(s) -of the message;
Cc: (where the "Cc" means "Carbon Copy" in the sense of -making a copy on a typewriter using carbon paper) contains the -addresses of others who are to receive the message, though the -content of the message may not be directed at them;
Bcc: (where the "Bcc" means "Blind Carbon -Copy") contains addresses of recipients of the message whose addresses are not -to be revealed to other recipients of the message.

- -

-The LuaSocket send function does not care or interpret the -headers you send, but it gives you full control over what is sent and -to whom it is sent: -

If someone is to receive the message, the e-mail address has -to be in the recipient list. This is the only parameter that controls who -gets a copy of the message;
If there are multiple recipients, none of them will automatically -know that someone else got that message. That is, the default behavior is -similar to the Bcc field of popular e-mail clients;
It is up to you to add the To header with the list of primary -recipients so that other recipients can see it;
It is also up to you to add the Cc header with the -list of additional recipients so that everyone else sees it;
Adding a header Bcc is nonsense, unless it is -empty. Otherwise, everyone receiving the message will see it and that is -exactly what you don't want to happen!

- -

-I hope this clarifies the issue. Otherwise, please refer to -RFC 2821 -and -RFC 2822. -

- -

--- load the smtp support
-local smtp = require("socket.smtp")
-
--- Connects to server "localhost" and sends a message to users
--- "fulano@example.com",  "beltrano@example.com",
--- and "sicrano@example.com".
--- Note that "fulano" is the primary recipient, "beltrano" receives a
--- carbon copy and neither of them knows that "sicrano" received a blind
--- carbon copy of the message.
-from = "<luasocket@example.com>"
-
-rcpt = {
-  "<fulano@example.com>",
-  "<beltrano@example.com>",
-  "<sicrano@example.com>"
-}
-
-mesgt = {
-  headers = {
-    to = "Fulano da Silva <fulano@example.com>",
-    cc = '"Beltrano F. Nunes" <beltrano@example.com>',
-    subject = "My first message"
-  },
-  body = "I hope this works. If it does, I can send you another 1000 copies."
-}
-
-r, e = smtp.send{
-  from = from,
-  rcpt = rcpt,
-  source = smtp.message(mesgt)
-}
-

- - - - - - - diff --git a/doc/socket.html b/doc/socket.html deleted file mode 100644 index c148114..0000000 --- a/doc/socket.html +++ /dev/null @@ -1,481 +0,0 @@ - - - - - - -LuaSocket: The socket namespace - - - - - - - - - - - -

The socket namespace

- -

-The socket namespace contains the core functionality of LuaSocket. -

- -

-To obtain the socket namespace, run: -

- -

--- loads the socket module
-local socket = require("socket")
-

- - - -

-socket.headers.canonic

- -

The socket.headers.canonic table -is used by the HTTP and SMTP modules to translate from -lowercase field names back into their canonic -capitalization. When a lowercase field name exists as a key -in this table, the associated value is substituted in -whenever the field name is sent out. -

- -

-You can obtain the headers namespace if case run-time -modifications are required by running: -

- -

--- loads the headers module
-local headers = require("headers")
-

- - - - -

-socket.bind(address, port [, backlog]) -

- -

-This function is a shortcut that creates and returns a TCP server object -bound to a local address and port, ready to -accept client connections. Optionally, -user can also specify the backlog argument to the -listen method (defaults to 32). -

- -

-Note: The server object returned will have the option "reuseaddr" -set to true. -

- - - -

-socket.connect[46](address, port [, locaddr] [, locport] [, family]) -

- -

-This function is a shortcut that creates and returns a TCP client object -connected to a remote address at a given port. Optionally, -the user can also specify the local address and port to bind -(locaddr and locport), or restrict the socket family -to "inet" or "inet6". -Without specifying family to connect, whether a tcp or tcp6 -connection is created depends on your system configuration. Two variations -of connect are defined as simple helper functions that restrict the -family, socket.connect4 and socket.connect6. -

- - - -

-socket._DEBUG -

- -

-This constant is set to true if the library was compiled -with debug support. -

- - - -

-socket._DATAGRAMSIZE -

- -

-Default datagram size used by calls to -receive and -receivefrom. -(Unless changed in compile time, the value is 8192.) -

- - - -

-socket.gettime() -

- -

-Returns the UNIX time in seconds. You should subtract the values returned by this function -to get meaningful values. -

- -

-t = socket.gettime()
--- do stuff
-print(socket.gettime() - t .. " seconds elapsed")
-

- - - -

-socket.newtry(finalizer) -

- -

-Creates and returns a clean -try -function that allows for cleanup before the exception -is raised. -

- -

-Finalizer is a function that will be called before -try throws the exception. -

- -

-The function returns your customized try function. -

- -

-Note: This idea saved a lot of work with the -implementation of protocols in LuaSocket: -

- -

-foo = socket.protect(function()
-    -- connect somewhere
-    local c = socket.try(socket.connect("somewhere", 42))
-    -- create a try function that closes 'c' on error
-    local try = socket.newtry(function() c:close() end)
-    -- do everything reassured c will be closed
-    try(c:send("hello there?\r\n"))
-    local answer = try(c:receive())
-    ...
-    try(c:send("good bye\r\n"))
-    c:close()
-end)
-

- - - - -

-socket.protect(func) -

- -

-Converts a function that throws exceptions into a safe function. This -function only catches exceptions thrown by the try -and newtry functions. It does not catch normal -Lua errors. -

- -

-Func is a function that calls -try (or assert, or error) -to throw exceptions. -

- -

-Returns an equivalent function that instead of throwing exceptions in case of -a failed try call, returns nil -followed by an error message. -

- - - -

-socket.select(recvt, sendt [, timeout]) -

- -

-Waits for a number of sockets to change status. -

- -

-Recvt is an array with the sockets to test for characters -available for reading. Sockets in the sendt array are watched to -see if it is OK to immediately write on them. Timeout is the -maximum amount of time (in seconds) to wait for a change in status. A -nil, negative or omitted timeout value allows the -function to block indefinitely. Recvt and sendt can also -be empty tables or nil. Non-socket values (or values with -non-numeric indices) in the arrays will be silently ignored. -

- -

The function returns a list with the sockets ready for -reading, a list with the sockets ready for writing and an error message. -The error message is "timeout" if a timeout -condition was met, "select failed" if the call -to select failed, and -nil otherwise. The returned tables are -doubly keyed both by integers and also by the sockets -themselves, to simplify the test if a specific socket has -changed status. -

- -

-Note: select can monitor a limited number -of sockets, as defined by the constant -socket._SETSIZE. This -number may be as high as 1024 or as low as 64 by default, -depending on the system. It is usually possible to change this -at compile time. Invoking select with a larger -number of sockets will raise an error. -

- -

-Important note: a known bug in WinSock causes select to fail -on non-blocking TCP sockets. The function may return a socket as -writable even though the socket is not ready for sending. -

- -

-Another important note: calling select with a server socket in the receive parameter before a call to accept does not guarantee -accept will return immediately. -Use the settimeout -method or accept might block forever. -

- -

-Yet another note: If you close a socket and pass -it to select, it will be ignored. -

- -

-Using select with non-socket objects: Any object that implements getfd and dirty can be used with select, allowing objects from other libraries to be used within a socket.select driven loop. -

- - - -

-socket._SETSIZE -

- -

-The maximum number of sockets that the select function can handle. -

- - - - -

-socket.sink(mode, socket) -

- -

-Creates an -LTN12 -sink from a stream socket object. -

- -

-Mode defines the behavior of the sink. The following -options are available: -

"http-chunked": sends data through socket after applying the -chunked transfer coding, closing the socket when done;
"close-when-done": sends all received data through the -socket, closing the socket when done;
"keep-open": sends all received data through the -socket, leaving it open when done.

-Socket is the stream socket object used to send the data. -

- -

-The function returns a sink with the appropriate behavior. -

- - - -

-socket.skip(d [, ret₁, ret₂ ... ret_N]) -

- -

-Drops a number of arguments and returns the remaining. -

- -

-D is the number of arguments to drop. Ret₁ to -ret_N are the arguments. -

- -

-The function returns ret_d+1 to ret_N. -

- -

-Note: This function is useful to avoid creation of dummy variables: -

- -

--- get the status code and separator from SMTP server reply
-local code, sep = socket.skip(2, string.find(line, "^(%d%d%d)(.?)"))
-

- - - -

-socket.sleep(time) -

- -

-Freezes the program execution during a given amount of time. -

- -

-Time is the number of seconds to sleep for. If -time is negative, the function returns immediately. -

- - - -

-socket.source(mode, socket [, length]) -

- -

-Creates an -LTN12 -source from a stream socket object. -

- -

-Mode defines the behavior of the source. The following -options are available: -

"http-chunked": receives data from socket and removes the -chunked transfer coding before returning the data;
"by-length": receives a fixed number of bytes from the -socket. This mode requires the extra argument length;
"until-closed": receives data from a socket until the other -side closes the connection.

-Socket is the stream socket object used to receive the data. -

- -

-The function returns a source with the appropriate behavior. -

- - - -

-socket._SOCKETINVALID -

- -

-The OS value for an invalid socket. This can be used with -tcp:getfd and tcp:setfd methods. -

- - - -

-socket.try(ret₁ [, ret₂ ... ret_N]) -

- -

-Throws an exception in case ret₁ is falsy, using -ret₂ as the error message. The exception is supposed to be caught -by a protected function only. -

- -

-Ret₁ to ret_N can be arbitrary -arguments, but are usually the return values of a function call -nested with try. -

- -

-The function returns ret₁ to ret_N if -ret₁ is not nil or false. -Otherwise, it calls error passing ret₂ wrapped -in a table with metatable used by protect to -distinguish exceptions from runtime errors. -

- -

--- connects or throws an exception with the appropriate error message
-c = socket.try(socket.connect("localhost", 80))
-

- - - -

-socket._VERSION -

- -

-This constant has a string describing the current LuaSocket version. -

- - - - - - - diff --git a/doc/tcp.html b/doc/tcp.html deleted file mode 100644 index 9cc173e..0000000 --- a/doc/tcp.html +++ /dev/null @@ -1,732 +0,0 @@ - - - - - - -LuaSocket: TCP/IP support - - - - - - - - - - - -

TCP

- - - -

-server:accept() -

- -

-Waits for a remote connection on the server -object and returns a client object representing that connection. -

- -

-If a connection is successfully initiated, a client object is returned. -If a timeout condition is met, the method returns nil -followed by the error string 'timeout'. Other errors are -reported by nil followed by a message describing the error. -

- -

-Note: calling socket.select -with a server object in -the recvt parameter before a call to accept does -not guarantee accept will return immediately. Use the settimeout method or accept -might block until another client shows up. -

- - - -

-master:bind(address, port) -

- -

-Binds a master object to address and port on the -local host. -

- -

-Address can be an IP address or a host name. -Port must be an integer number in the range [0..64K). -If address -is '*', the system binds to all local interfaces -using the INADDR_ANY constant or -IN6ADDR_ANY_INIT, according to the family. -If port is 0, the system automatically -chooses an ephemeral port. -

- -

-In case of success, the method returns 1. In case of error, the -method returns nil followed by an error message. -

- -

-Note: The function socket.bind -is available and is a shortcut for the creation of server sockets. -

- - - -

-master:close()
-client:close()
-server:close() -

- -

-Closes a TCP object. The internal socket used by the object is closed -and the local address to which the object was -bound is made available to other applications. No further operations -(except for further calls to the close method) are allowed on -a closed socket. -

- -

-Note: It is important to close all used sockets once they are not -needed, since, in many systems, each socket uses a file descriptor, -which are limited system resources. Garbage-collected objects are -automatically closed before destruction, though. -

- - - -

-master:connect(address, port) -

- -

-Attempts to connect a master object to a remote host, transforming it into a -client object. -Client objects support methods -send, -receive, -getsockname, -getpeername, -settimeout, -and close. -

- -

-Address can be an IP address or a host name. -Port must be an integer number in the range [1..64K). -

- -

-In case of error, the method returns nil followed by a string -describing the error. In case of success, the method returns 1. -

- -

-Note: The function socket.connect -is available and is a shortcut for the creation of client sockets. -

- -

-Note: Starting with LuaSocket 2.0, -the settimeout -method affects the behavior of connect, causing it to return -with an error in case of a timeout. If that happens, you can still call socket.select with the socket in the -sendt table. The socket will be writable when the connection is -established. -

- -

-Note: Starting with LuaSocket 3.0, the host name resolution -depends on whether the socket was created by -socket.tcp, -socket.tcp4 or -socket.tcp6. Addresses from -the appropriate family (or both) are tried in the order -returned by the resolver until the -first success or until the last failure. If the timeout was -set to zero, only the first address is tried. -

- - - -

-master:dirty()
-client:dirty()
-server:dirty() -

- -

-Check the read buffer status. -

- -

-Returns true if there is any data in the read buffer, false otherwise. -

- -

-Note: This is an internal method, use at your own risk. -

- - - - -

-master:getfd()
-client:getfd()
-server:getfd() -

- -

-Returns the underling socket descriptor or handle associated to the object. -

- -

-The descriptor or handle. In case the object has been closed, the return value -will be -1. For an invalid socket it will be -_SOCKETINVALID. -

- -

-Note: This is an internal method. Unlikely to be -portable. Use at your own risk. -

- - - - -

-client:getoption(option)
-server:getoption(option) -

- -

-Gets options for the TCP object. -See setoption for description of the -option names and values. -

- -

-Option is a string with the option name.

'keepalive'
'linger'
'reuseaddr'
'tcp-nodelay'

- -

-The method returns the option value in case of success, or -nil followed by an error message otherwise. -

- - - - -

-client:getpeername() -

- -

-Returns information about the remote side of a connected client object. -

- -

-Returns a string with the IP address of the peer, the -port number that peer is using for the connection, -and a string with the family ("inet" or "inet6"). -In case of error, the method returns nil. -

- -

-Note: It makes no sense to call this method on server objects. -

- - - -

-master:getsockname()
-client:getsockname()
-server:getsockname() -

- -

-Returns the local address information associated to the object. -

- -

-The method returns a string with local IP address, a number with -the local port, -and a string with the family ("inet" or "inet6"). -In case of error, the method returns nil. -

- - - -

-master:getstats()
-client:getstats()
-server:getstats()
-

- -

-Returns accounting information on the socket, useful for throttling -of bandwidth. -

- -

-The method returns the number of bytes received, the number of bytes sent, -and the age of the socket object in seconds. -

- - - -

-master:gettimeout()
-client:gettimeout()
-server:gettimeout() -

- -

-Returns the current block timeout followed by the curent -total timeout. -

- - - - -

-master:listen(backlog) -

- -

-Specifies the socket is willing to receive connections, transforming the -object into a server object. Server objects support the -accept, -getsockname, -setoption, -settimeout, -and close methods. -

- -

-The parameter backlog specifies the number of client -connections that can -be queued waiting for service. If the queue is full and another client -attempts connection, the connection is refused. -

- -

-In case of success, the method returns 1. In case of error, the -method returns nil followed by an error message. -

- - - -

-client:receive([pattern [, prefix]]) -

- -

-Reads data from a client object, according to the specified read -pattern. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. -

- -

-Pattern can be any of the following: -

- -

'*a': reads from the socket until the connection is -closed. No end-of-line translation is performed;
'*l': reads a line of text from the socket. The line is -terminated by a LF character (ASCII 10), optionally preceded by a -CR character (ASCII 13). The CR and LF characters are not included in -the returned line. In fact, all CR characters are -ignored by the pattern. This is the default pattern;
number: causes the method to read a specified number -of bytes from the socket.

- -

-Prefix is an optional string to be concatenated to the beginning -of any received data before return. -

- -

-If successful, the method returns the received pattern. In case of error, -the method returns nil followed by an error -message, followed by a (possibly empty) string containing -the partial that was received. The error message can be -the string 'closed' in case the connection was -closed before the transmission was completed or the string -'timeout' in case there was a timeout during the operation. -

- -

-Important note: This function was changed severely. It used -to support multiple patterns (but I have never seen this feature used) and -now it doesn't anymore. Partial results used to be returned in the same -way as successful results. This last feature violated the idea that all -functions should return nil on error. Thus it was changed -too. -

- - - -

-client:send(data [, i [, j]]) -

- -

-Sends data through client object. -

- -

-Data is the string to be sent. The optional arguments -i and j work exactly like the standard -string.sub Lua function to allow the selection of a -substring to be sent. -

- -

-If successful, the method returns the index of the last byte -within [i, j] that has been sent. Notice that, if -i is 1 or absent, this is effectively the total -number of bytes sent. In case of error, the method returns -nil, followed by an error message, followed -by the index of the last byte within [i, j] that -has been sent. You might want to try again from the byte -following that. The error message can be 'closed' -in case the connection was closed before the transmission -was completed or the string 'timeout' in case -there was a timeout during the operation. -

- -

-Note: Output is not buffered. For small strings, -it is always better to concatenate them in Lua -(with the '..' operator) and send the result in one call -instead of calling the method several times. -

- - - -

-client:setoption(option [, value])
-server:setoption(option [, value]) -

- -

-Sets options for the TCP object. Options are only needed by low-level or -time-critical applications. You should only modify an option if you -are sure you need it. -

- -

-Option is a string with the option name, and value -depends on the option being set:

- -

'keepalive': Setting this option to true enables -the periodic transmission of messages on a connected socket. Should the -connected party fail to respond to these messages, the connection is -considered broken and processes using the socket are notified;
'linger': Controls the action taken when unsent data are -queued on a socket and a close is performed. The value is a table with a -boolean entry 'on' and a numeric entry for the time interval -'timeout' in seconds. If the 'on' field is set to -true, the system will block the process on the close attempt until -it is able to transmit the data or until 'timeout' has passed. If -'on' is false and a close is issued, the system will -process the close in a manner that allows the process to continue as -quickly as possible. I do not advise you to set this to anything other than -zero;
'reuseaddr': Setting this option indicates that the rules -used in validating addresses supplied in a call to -bind should allow reuse of local addresses;
'tcp-nodelay': Setting this option to true -disables the Nagle's algorithm for the connection;
'tcp-keepidle': value in seconds for TCP_KEEPIDLE Linux only!!
'tcp-keepcnt': value for TCP_KEEPCNT Linux only!!
'tcp-keepintvl': value for TCP_KEEPINTVL Linux only!!
'ipv6-v6only': -Setting this option to true restricts an inet6 socket to -sending and receiving only IPv6 packets.

- -

-The method returns 1 in case of success, or nil -followed by an error message otherwise. -

- -

-Note: The descriptions above come from the man pages. -

- - - -

-master:setstats(received, sent, age)
-client:setstats(received, sent, age)
-server:setstats(received, sent, age)
-

- -

-Resets accounting information on the socket, useful for throttling -of bandwidth. -

- -

-Received is a number with the new number of bytes received. -Sent is a number with the new number of bytes sent. -Age is the new age in seconds. -

- -

-The method returns 1 in case of success and nil otherwise. -

- - - -

-master:settimeout(value [, mode])
-client:settimeout(value [, mode])
-server:settimeout(value [, mode]) -

- -

-Changes the timeout values for the object. By default, -all I/O operations are blocking. That is, any call to the methods -send, -receive, and -accept -will block indefinitely, until the operation completes. The -settimeout method defines a limit on the amount of time the -I/O methods can block. When a timeout is set and the specified amount of -time has elapsed, the affected methods give up and fail with an error code. -

- -

-The amount of time to wait is specified as the -value parameter, in seconds. There are two timeout modes and -both can be used together for fine tuning: -

- -

'b': block timeout. Specifies the upper limit on -the amount of time LuaSocket can be blocked by the operating system -while waiting for completion of any single I/O operation. This is the -default mode;
't': total timeout. Specifies the upper limit on -the amount of time LuaSocket can block a Lua script before returning from -a call.

- -

-The nil timeout value allows operations to block -indefinitely. Negative timeout values have the same effect. -

- -

-Note: although timeout values have millisecond precision in LuaSocket, -large blocks can cause I/O functions not to respect timeout values due -to the time the library takes to transfer blocks to and from the OS -and to and from the Lua interpreter. Also, function that accept host names -and perform automatic name resolution might be blocked by the resolver for -longer than the specified timeout value. -

- -

-Note: The old timeout method is deprecated. The name has been -changed for sake of uniformity, since all other method names already -contained verbs making their imperative nature obvious. -

- - - -

-client:shutdown(mode)
-

- -

-Shuts down part of a full-duplex connection. -

- -

-Mode tells which way of the connection should be shut down and can -take the value: -

"both": disallow further sends and receives on the object. -This is the default mode;
"send": disallow further sends on the object;
"receive": disallow further receives on the object.

- -

-This function returns 1. -

- - - -

-master:setfd(fd)
-client:setfd(fd)
-server:setfd(fd) -

- -

-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. -To set it as invalid use _SOCKETINVALID. -

- -

-No return value. -

- -

-Note: This is an internal method. Unlikely to be -portable. Use at your own risk. -

- - - -

-socket.tcp() -

- -

-Creates and returns an TCP master object. A master object can -be transformed into a server object with the method -listen (after a call to bind) or into a client object with -the method connect. The only other -method supported by a master object is the -close method.

- -

-In case of success, a new master object is returned. In case of error, -nil is returned, followed by an error message. -

- -

-Note: The choice between IPv4 and IPv6 happens during a call to -bind or connect, depending on the address -family obtained from the resolver. -

- -

-Note: Before the choice between IPv4 and IPv6 happens, -the internal socket object is invalid and therefore setoption will fail. -

- - - -

-socket.tcp4() -

- -

-Creates and returns an IPv4 TCP master object. A master object can -be transformed into a server object with the method -listen (after a call to bind) or into a client object with -the method connect. The only other -method supported by a master object is the -close method.

- -

-In case of success, a new master object is returned. In case of error, -nil is returned, followed by an error message. -

- - - -

-socket.tcp6() -

- -

-Creates and returns an IPv6 TCP master object. A master object can -be transformed into a server object with the method -listen (after a call to bind) or into a client object with -the method connect. The only other -method supported by a master object is the -close method.

- -

-In case of success, a new master object is returned. In case of error, -nil is returned, followed by an error message. -

- -

-Note: The TCP object returned will have the option -"ipv6-v6only" set to true. -

- - - - - - - - - diff --git a/doc/udp.html b/doc/udp.html deleted file mode 100644 index db711cb..0000000 --- a/doc/udp.html +++ /dev/null @@ -1,596 +0,0 @@ - - - - - - -LuaSocket: UDP support - - - - - - - - - - - - -

UDP

- - - -

-connected:close()
-unconnected:close() -

- -

-Closes a UDP object. The internal socket -used by the object is closed and the local address to which the -object was bound is made available to other applications. No -further operations (except for further calls to the close -method) are allowed on a closed socket. -

- -

-Note: It is important to close all used sockets -once they are not needed, since, in many systems, each socket uses -a file descriptor, which are limited system resources. -Garbage-collected objects are automatically closed before -destruction, though. -

- - - -

-connected:getoption()
-unconnected:getoption() -

- -

-Gets an option value from the UDP object. -See setoption for -description of the option names and values. -

- -

Option is a string with the option name. -

'dontroute'
'broadcast'
'reuseaddr'
'reuseport'
'ip-multicast-loop'
'ipv6-v6only'
'ip-multicast-if'
'ip-multicast-ttl'
'ip-add-membership'
'ip-drop-membership'

- -

-The method returns the option value in case of -success, or -nil followed by an error message otherwise. -

- - - -

-connected:getpeername() -

- -

-Retrieves information about the peer -associated with a connected UDP object. -

- - -

- -

-Note: It makes no sense to call this method on unconnected objects. -

- - - -

-connected:getsockname()
-unconnected:getsockname() -

- -

-Returns the local address information associated to the object. -

- - -

-The method returns a string with local IP address, a number with -the local port, -and a string with the family ("inet" or "inet6"). -In case of error, the method returns nil. -

- -

-Note: UDP sockets are not bound to any address -until the setsockname or the -sendto method is called for the -first time (in which case it is bound to an ephemeral port and the -wild-card address). -

- - - -

-connected:settimeout(value)
-unconnected:settimeout(value) -

- -

-Returns the current timeout value. -

- - - - -

-connected:receive([size])
-unconnected:receive([size]) -

- -

-Receives a datagram from the UDP object. If -the UDP object is connected, only datagrams coming from the peer -are accepted. Otherwise, the returned datagram can come from any -host. -

- -

-The optional size parameter -specifies the maximum size of the datagram to be retrieved. If -there are more than size bytes available in the datagram, -the excess bytes are discarded. If there are less then -size bytes available in the current datagram, the -available bytes are returned. -If size is omitted, the -compile-time constant -socket._DATAGRAMSIZE is used -(it defaults to 8192 bytes). Larger sizes will cause a -temporary buffer to be allocated for the operation. -

- -

-In case of success, the method returns the -received datagram. In case of timeout, the method returns -nil followed by the string 'timeout'. -

- - - -

-unconnected:receivefrom([size]) -

- -

-Works exactly as the receive -method, except it returns the IP -address and port as extra return values (and is therefore slightly less -efficient). -

- - - -

-connected:send(datagram) -

- -

-Sends a datagram to the UDP peer of a connected object. -

- -

-Datagram is a string with the datagram contents. -The maximum datagram size for UDP is 64K minus IP layer overhead. -However datagrams larger than the link layer packet size will be -fragmented, which may deteriorate performance and/or reliability. -

- -

-If successful, the method returns 1. In case of -error, the method returns nil followed by an error message. -

- -

-Note: In UDP, the send method never blocks -and the only way it can fail is if the underlying transport layer -refuses to send a message to the specified address (i.e. no -interface accepts the address). -

- - - -

-unconnected:sendto(datagram, ip, port) -

- -

-Sends a datagram to the specified IP address and port number. -

- -

-Datagram is a string with the -datagram contents. -The maximum datagram size for UDP is 64K minus IP layer overhead. -However datagrams larger than the link layer packet size will be -fragmented, which may deteriorate performance and/or reliability. -Ip is the IP address of the recipient. -Host names are not allowed for performance reasons. - -Port is the port number at the recipient. -

- -

-If successful, the method returns 1. In case of -error, the method returns nil followed by an error message. -

- -

- - - -

-connected:setoption(option [, value])
-unconnected:setoption(option [, value]) -

- -

-Sets options for the UDP object. Options are -only needed by low-level or time-critical applications. You should -only modify an option if you are sure you need it.

Option is a string with the option -name, and value depends on the option being set: -

- -

'dontroute': Indicates that outgoing -messages should bypass the standard routing facilities. -Receives a boolean value;
'broadcast': Requests permission to send -broadcast datagrams on the socket. -Receives a boolean value;
'reuseaddr': Indicates that the rules used in -validating addresses supplied in a bind() call -should allow reuse of local addresses. -Receives a boolean value;
'reuseport': Allows completely duplicate -bindings by multiple processes if they all set -'reuseport' before binding the port. -Receives a boolean value;
'ip-multicast-loop': -Specifies whether or not a copy of an outgoing multicast -datagram is delivered to the sending host as long as it is a -member of the multicast group. -Receives a boolean value;
'ipv6-v6only': -Specifies whether to restrict inet6 sockets to -sending and receiving only IPv6 packets. -Receive a boolean value;
'ip-multicast-if': -Sets the interface over which outgoing multicast datagrams -are sent. -Receives an IP address;
'ip-multicast-ttl': -Sets the Time To Live in the IP header for outgoing -multicast datagrams. -Receives a number;
'ip-add-membership': -Joins the multicast group specified. -Receives a table with fields -multiaddr and interface, each containing an -IP address;
'ip-drop-membership': Leaves the multicast -group specified. -Receives a table with fields -multiaddr and interface, each containing an -IP address.

- -

-The method returns 1 in case of success, or -nil followed by an error message otherwise. -

- -

-Note: The descriptions above come from the man pages. -

- - - - -

-connected:setpeername('*')
-unconnected:setpeername(address, port) -

- -

-Changes the peer of a UDP object. This -method turns an unconnected UDP object into a connected UDP -object or vice versa. -

- -

-For connected objects, outgoing datagrams -will be sent to the specified peer, and datagrams received from -other peers will be discarded by the OS. Connected UDP objects must -use the send and -receive methods instead of -sendto and -receivefrom. -

- -

-Address can be an IP address or a -host name. Port is the port number. If address is -'*' and the object is connected, the peer association is -removed and the object becomes an unconnected object again. In that -case, the port argument is ignored. -

- -

-In case of error the method returns -nil followed by an error message. In case of success, the -method returns 1. -

- -

-Note: Since the address of the peer does not have -to be passed to and from the OS, the use of connected UDP objects -is recommended when the same peer is used for several transmissions -and can result in up to 30% performance gains. -

- -

-Note: Starting with LuaSocket 3.0, the host name resolution -depends on whether the socket was created by socket.udp or socket.udp6. Addresses from -the appropriate family are tried in succession until the -first success or until the last failure. -

- - - -

-unconnected:setsockname(address, port) -

- -

-Binds the UDP object to a local address. -

- -

-Address can be an IP address or a -host name. If address is '*' the system binds to -all local interfaces using the constant INADDR_ANY. If -port is 0, the system chooses an ephemeral port. -

- -

-If successful, the method returns 1. In case of -error, the method returns nil followed by an error -message. -

- -

-Note: This method can only be called before any -datagram is sent through the UDP object, and only once. Otherwise, -the system automatically binds the object to all local interfaces -and chooses an ephemeral port as soon as the first datagram is -sent. After the local address is set, either automatically by the -system or explicitly by setsockname, it cannot be -changed. -

- - - -

-connected:settimeout(value)
-unconnected:settimeout(value) -

- -

-Changes the timeout values for the object. By default, the -receive and -receivefrom -operations are blocking. That is, any call to the methods will block -indefinitely, until data arrives. The settimeout function defines -a limit on the amount of time the functions can block. When a timeout is -set and the specified amount of time has elapsed, the affected methods -give up and fail with an error code. -

- -

-The amount of time to wait is specified as -the value parameter, in seconds. The nil timeout -value allows operations to block indefinitely. Negative -timeout values have the same effect. -

- -

-Note: In UDP, the send -and sendto methods never block (the -datagram is just passed to the OS and the call returns -immediately). Therefore, the settimeout method has no -effect on them. -

- -

-Note: The old timeout method is -deprecated. The name has been changed for sake of uniformity, since -all other method names already contained verbs making their -imperative nature obvious. -

- - - -

-socket.udp() -

- -

-Creates and returns an unconnected UDP object. -Unconnected objects support the -sendto, -receive, -receivefrom, -getoption, -getsockname, -setoption, -settimeout, -setpeername, -setsockname, and -close. -The setpeername -is used to connect the object. -

- -

-In case of success, a new unconnected UDP object -returned. In case of error, nil is returned, followed by -an error message. -

- -

-Note: The choice between IPv4 and IPv6 happens during a call to -sendto, setpeername, or sockname, depending on the address -family obtained from the resolver. -

- -

-Note: Before the choice between IPv4 and IPv6 happens, -the internal socket object is invalid and therefore setoption will fail. -

- - - -

-socket.udp4() -

- -

-Creates and returns an unconnected IPv4 UDP object. -Unconnected objects support the -sendto, -receive, -receivefrom, -getoption, -getsockname, -setoption, -settimeout, -setpeername, -setsockname, and -close. -The setpeername -is used to connect the object. -

- -

-In case of success, a new unconnected UDP object -returned. In case of error, nil is returned, followed by -an error message. -

- - - -

-socket.udp6() -

- -

-Creates and returns an unconnected IPv6 UDP object. -Unconnected objects support the -sendto, -receive, -receivefrom, -getoption, -getsockname, -setoption, -settimeout, -setpeername, -setsockname, and -close. -The setpeername -is used to connect the object. -

- -

-In case of success, a new unconnected UDP object -returned. In case of error, nil is returned, followed by -an error message. -

- -

-Note: The TCP object returned will have the option -"ipv6-v6only" set to true. -

- - - - - - - - - diff --git a/doc/url.html b/doc/url.html deleted file mode 100644 index 6ff673d..0000000 --- a/doc/url.html +++ /dev/null @@ -1,328 +0,0 @@ - - - - - - -LuaSocket: URL support - - - - - - - - - - - -

URL

- -

-The url namespace provides functions to parse, protect, -and build URLs, as well as functions to compose absolute URLs -from base and relative URLs, according to -RFC 2396. -

- -

-To obtain the url namespace, run: -

- -

--- loads the URL module 
-local url = require("socket.url")
-

- -

-An URL is defined by the following grammar: -

- -

--<url> ::= [<scheme>:][//<authority>][/<path>][;<params>][?<query>][#<fragment>] -<authority> ::= [<userinfo>@]<host>[:<port>] -<userinfo> ::= <user>[:<password>] -<path> ::= {<segment>/}<segment> - -

- - - -

-url.absolute(base, relative) -

- -

-Builds an absolute URL from a base URL and a relative URL. -

- -

-Base is a string with the base URL or -a parsed URL table. Relative is a -string with the relative URL. -

- -

-The function returns a string with the absolute URL. -

- -

-Note: The rules that -govern the composition are fairly complex, and are described in detail in -RFC 2396. -The example bellow should give an idea of what the rules are. -

- -

-http://a/b/c/d;p?q
-
-+
-
-g:h      =  g:h
-g        =  http://a/b/c/g
-./g      =  http://a/b/c/g
-g/       =  http://a/b/c/g/
-/g       =  http://a/g
-//g      =  http://g
-?y       =  http://a/b/c/?y
-g?y      =  http://a/b/c/g?y
-#s       =  http://a/b/c/d;p?q#s
-g#s      =  http://a/b/c/g#s
-g?y#s    =  http://a/b/c/g?y#s
-;x       =  http://a/b/c/;x
-g;x      =  http://a/b/c/g;x
-g;x?y#s  =  http://a/b/c/g;x?y#s
-.        =  http://a/b/c/
-./       =  http://a/b/c/
-..       =  http://a/b/
-../      =  http://a/b/
-../g     =  http://a/b/g
-../..    =  http://a/
-../../   =  http://a/
-../../g  =  http://a/g
-

- - - -

-url.build(parsed_url) -

- -

-Rebuilds an URL from its parts. -

- -

-Parsed_url is a table with same components returned by -parse. -Lower level components, if specified, -take precedence over high level components of the URL grammar. -

- -

-The function returns a string with the built URL. -

- - - -

-url.build_path(segments, unsafe) -

- -

-Builds a <path> component from a list of -<segment> parts. -Before composition, any reserved characters found in a segment are escaped into -their protected form, so that the resulting path is a valid URL path -component. -

- -

-Segments is a list of strings with the <segment> -parts. If unsafe is anything but nil, reserved -characters are left untouched. -

- -

-The function returns a string with the -built <path> component. -

- - - -

-url.escape(content) -

- -

-Applies the URL escaping content coding to a string -Each byte is encoded as a percent character followed -by the two byte hexadecimal representation of its integer -value. -

- -

-Content is the string to be encoded. -

- -

-The function returns the encoded string. -

- -

--- load url module
-url = require("socket.url")
-
-code = url.escape("/#?;")
--- code = "%2f%23%3f%3b"
-

- - - -

-url.parse(url, default) -

- -

-Parses an URL given as a string into a Lua table with its components. -

- -

-Url is the URL to be parsed. If the default table is -present, it is used to store the parsed fields. Only fields present in the -URL are overwritten. Therefore, this table can be used to pass default -values for each field. -

- -

-The function returns a table with all the URL components: -

- -

-parsed_url = { - url = string, - scheme = string, - authority = string, - path = string, - params = string, - query = string, - fragment = string, - userinfo = string, - host = string, - port = string, - user = string, - password = string -} -

- -

--- load url module
-url = require("socket.url")
-
-parsed_url = url.parse("http://www.example.com/cgilua/index.lua?a=2#there")
--- parsed_url = {
---   scheme = "http",
---   authority = "www.example.com",
---   path = "/cgilua/index.lua"
---   query = "a=2",
---   fragment = "there",
---   host = "www.puc-rio.br",
--- }
-
-parsed_url = url.parse("ftp://root:passwd@unsafe.org/pub/virus.exe;type=i")
--- parsed_url = {
---   scheme = "ftp",
---   authority = "root:passwd@unsafe.org",
---   path = "/pub/virus.exe",
---   params = "type=i",
---   userinfo = "root:passwd",
---   host = "unsafe.org",
---   user = "root",
---   password = "passwd",
--- }
-

- - - -

-url.parse_path(path) -

- -

-Breaks a <path> URL component into all its -<segment> parts. -

- -

-Path is a string with the path to be parsed. -

- -

-Since some characters are reserved in URLs, they must be escaped -whenever present in a <path> component. Therefore, before -returning a list with all the parsed segments, the function removes -escaping from all of them. -

- - - -

-url.unescape(content) -

- -

-Removes the URL escaping content coding from a string. -

- -

-Content is the string to be decoded. -

- -

-The function returns the decoded string. -

- - - - - - - -- cgit v1.2.3-55-g6feb