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 --------------------- docs/dns.html | 183 ++++++++++++ docs/ftp.html | 288 +++++++++++++++++++ docs/http.html | 339 ++++++++++++++++++++++ docs/index.html | 215 ++++++++++++++ docs/installation.html | 127 ++++++++ docs/introduction.html | 333 +++++++++++++++++++++ docs/ltn12.html | 440 ++++++++++++++++++++++++++++ docs/lua05.ppt | Bin 0 -> 304128 bytes docs/luasocket.png | Bin 0 -> 11732 bytes docs/mime.html | 477 ++++++++++++++++++++++++++++++ docs/reference.css | 55 ++++ docs/reference.html | 261 +++++++++++++++++ docs/smtp.html | 419 +++++++++++++++++++++++++++ docs/socket.html | 481 +++++++++++++++++++++++++++++++ docs/tcp.html | 732 +++++++++++++++++++++++++++++++++++++++++++++++ docs/udp.html | 596 ++++++++++++++++++++++++++++++++++++++ docs/url.html | 328 +++++++++++++++++++++ luasocket-scm-3.rockspec | 2 +- makefile.dist | 38 +-- 36 files changed, 5294 insertions(+), 5294 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 create mode 100644 docs/dns.html create mode 100644 docs/ftp.html create mode 100644 docs/http.html create mode 100644 docs/index.html create mode 100644 docs/installation.html create mode 100644 docs/introduction.html create mode 100644 docs/ltn12.html create mode 100644 docs/lua05.ppt create mode 100644 docs/luasocket.png create mode 100644 docs/mime.html create mode 100644 docs/reference.css create mode 100644 docs/reference.html create mode 100644 docs/smtp.html create mode 100644 docs/socket.html create mode 100644 docs/tcp.html create mode 100644 docs/udp.html create mode 100644 docs/url.html 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. -

- - - - - - - diff --git a/docs/dns.html b/docs/dns.html new file mode 100644 index 0000000..56ce3ba --- /dev/null +++ b/docs/dns.html @@ -0,0 +1,183 @@ + + + + + + +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/docs/ftp.html b/docs/ftp.html new file mode 100644 index 0000000..7f7da2e --- /dev/null +++ b/docs/ftp.html @@ -0,0 +1,288 @@ + + + + + + +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/docs/http.html b/docs/http.html new file mode 100644 index 0000000..52b8a30 --- /dev/null +++ b/docs/http.html @@ -0,0 +1,339 @@ + + + + + + +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/docs/index.html b/docs/index.html new file mode 100644 index 0000000..e92b4d4 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,215 @@ + + + + + + +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/docs/installation.html b/docs/installation.html new file mode 100644 index 0000000..28a9fbb --- /dev/null +++ b/docs/installation.html @@ -0,0 +1,127 @@ + + + + + + +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/docs/introduction.html b/docs/introduction.html new file mode 100644 index 0000000..fd22f48 --- /dev/null +++ b/docs/introduction.html @@ -0,0 +1,333 @@ + + + + + + +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/docs/ltn12.html b/docs/ltn12.html new file mode 100644 index 0000000..fe3e3a0 --- /dev/null +++ b/docs/ltn12.html @@ -0,0 +1,440 @@ + + + + + + +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/docs/lua05.ppt b/docs/lua05.ppt new file mode 100644 index 0000000..e2b7ab4 Binary files /dev/null and b/docs/lua05.ppt differ diff --git a/docs/luasocket.png b/docs/luasocket.png new file mode 100644 index 0000000..d24a954 Binary files /dev/null and b/docs/luasocket.png differ diff --git a/docs/mime.html b/docs/mime.html new file mode 100644 index 0000000..ff4d8e8 --- /dev/null +++ b/docs/mime.html @@ -0,0 +1,477 @@ + + + + + + +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/docs/reference.css b/docs/reference.css new file mode 100644 index 0000000..04e38cf --- /dev/null +++ b/docs/reference.css @@ -0,0 +1,55 @@ +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/docs/reference.html b/docs/reference.html new file mode 100644 index 0000000..2bc5f78 --- /dev/null +++ b/docs/reference.html @@ -0,0 +1,261 @@ + + + + + + +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/docs/smtp.html b/docs/smtp.html new file mode 100644 index 0000000..787d0b1 --- /dev/null +++ b/docs/smtp.html @@ -0,0 +1,419 @@ + + + + + + +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/docs/socket.html b/docs/socket.html new file mode 100644 index 0000000..c148114 --- /dev/null +++ b/docs/socket.html @@ -0,0 +1,481 @@ + + + + + + +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/docs/tcp.html b/docs/tcp.html new file mode 100644 index 0000000..9cc173e --- /dev/null +++ b/docs/tcp.html @@ -0,0 +1,732 @@ + + + + + + +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/docs/udp.html b/docs/udp.html new file mode 100644 index 0000000..db711cb --- /dev/null +++ b/docs/udp.html @@ -0,0 +1,596 @@ + + + + + + +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/docs/url.html b/docs/url.html new file mode 100644 index 0000000..6ff673d --- /dev/null +++ b/docs/url.html @@ -0,0 +1,328 @@ + + + + + + +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. +

+ + + + + + + diff --git a/luasocket-scm-3.rockspec b/luasocket-scm-3.rockspec index 4e1669c..0e1b0f9 100644 --- a/luasocket-scm-3.rockspec +++ b/luasocket-scm-3.rockspec @@ -127,7 +127,7 @@ build = { mingw32 = make_plat("mingw32") }, copy_directories = { - "doc" + "docs" , "samples" , "etc" , "test" } diff --git a/makefile.dist b/makefile.dist index 45a8866..83c303e 100644 --- a/makefile.dist +++ b/makefile.dist @@ -92,23 +92,23 @@ MAKE = \ socket.vcxproj \ mime.vcxproj -DOC = \ - doc/dns.html \ - doc/ftp.html \ - doc/index.html \ - doc/http.html \ - doc/installation.html \ - doc/introduction.html \ - doc/ltn12.html \ - doc/luasocket.png \ - doc/mime.html \ - doc/reference.css \ - doc/reference.html \ - doc/smtp.html \ - doc/socket.html \ - doc/tcp.html \ - doc/udp.html \ - doc/url.html +DOCS = \ + docs/dns.html \ + docs/ftp.html \ + docs/index.html \ + docs/http.html \ + docs/installation.html \ + docs/introduction.html \ + docs/ltn12.html \ + docs/luasocket.png \ + docs/mime.html \ + docs/reference.css \ + docs/reference.html \ + docs/smtp.html \ + docs/socket.html \ + docs/tcp.html \ + docs/udp.html \ + docs/url.html dist: mkdir -p $(DIST) @@ -123,8 +123,8 @@ dist: mkdir -p $(DIST)/src cp -vf $(SRC) $(DIST)/src - mkdir -p $(DIST)/doc - cp -vf $(DOC) $(DIST)/doc + mkdir -p $(DIST)/docs + cp -vf $(DOCS) $(DIST)/docs mkdir -p $(DIST)/samples cp -vf $(SAMPLES) $(DIST)/samples -- cgit v1.2.3-55-g6feb From 2eac8950396247b412c4089c23a46015c8cc12bb Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 23 Mar 2022 00:16:23 +0300 Subject: Update URL references to source repository --- README | 8 ++++---- docs/index.html | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README b/README index cd8ee59..7354ea0 100644 --- a/README +++ b/README @@ -1,11 +1,11 @@ This is the LuaSocket 3.0-rc1. It has been tested on Windows 7, Mac OS X, -and Linux. +and Linux. -Please use the project page at GitHub +Please use the project page at GitHub - https://github.com/diegonehab/luasocket + https://github.com/lunarmodules/luasocket -to file bug reports or propose changes. +to file bug reports or propose changes. Have fun, Diego Nehab. diff --git a/docs/index.html b/docs/index.html index e92b4d4..0364070 100644 --- a/docs/index.html +++ b/docs/index.html @@ -95,7 +95,7 @@ are it works well on most UNIX distributions and Windows flavors.

The current version of the library can be found at -the LuaSocket +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. -- cgit v1.2.3-55-g6feb