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 --- 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 ++++++++++++++++++++++ 17 files changed, 5274 insertions(+) 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 (limited to 'docs') 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. +

+ + + + + + + -- 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(-) (limited to 'docs') 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 From f7f0a77a3dbcd066c2f228ada63ee78546a01f78 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Fri, 25 Mar 2022 10:09:13 +0300 Subject: docs: Drop obsolete changelog from docs index --- docs/index.html | 76 --------------------------------------------------------- 1 file changed, 76 deletions(-) (limited to 'docs') diff --git a/docs/index.html b/docs/index.html index 0364070..5982071 100644 --- a/docs/index.html +++ b/docs/index.html @@ -121,76 +121,6 @@ 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. -

- -- cgit v1.2.3-55-g6feb From 88c8a85cb6528232288ec590910b7a966aace52b Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Fri, 25 Mar 2022 09:56:50 +0300 Subject: chore: Release v3.0.0 --- CHANGELOG.md | 2 +- docs/index.html | 7 +- rockspecs/luasocket-3.0.0-1.rockspec | 134 +++++++++++++++++++++++++++++++++++ 3 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 rockspecs/luasocket-3.0.0-1.rockspec (limited to 'docs') diff --git a/CHANGELOG.md b/CHANGELOG.md index 931bfa4..0de05f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## [v3.0.0](https://github.com/lunarmodules/luasocket/releases/v3.0.0) — unreleased +## [v3.0.0](https://github.com/lunarmodules/luasocket/releases/v3.0.0) — 2022-03-25 The last time LuaSocket had a stable release tag was 14 years ago when 2.0.2 was tagged. A v3 release candidate was tagged 9 years ago. diff --git a/docs/index.html b/docs/index.html index 5982071..31e18ad 100644 --- a/docs/index.html +++ b/docs/index.html @@ -87,10 +87,9 @@ 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. +LuaSocket version 3.0.0 is now available for download! +It is compatible with Lua 5.1 through 5.4. +Chances are it works well on most UNIX distributions and Windows flavors.

diff --git a/rockspecs/luasocket-3.0.0-1.rockspec b/rockspecs/luasocket-3.0.0-1.rockspec new file mode 100644 index 0000000..4cf4acf --- /dev/null +++ b/rockspecs/luasocket-3.0.0-1.rockspec @@ -0,0 +1,134 @@ +package = "LuaSocket" +version = "3.0.0-1" +source = { + url = "git+https://github.com/lunarmodules/luasocket.git", + tag = "v3.0.0" +} +description = { + summary = "Network support for the Lua language", + detailed = [[ + LuaSocket is a Lua extension library composed of two parts: a set of C + modules that provide support for the TCP and UDP transport layers, and a + set of Lua modules that provide functions commonly needed by applications + that deal with the Internet. + ]], + homepage = "https://github.com/lunarmodules/luasocket", + license = "MIT" +} +dependencies = { + "lua >= 5.1" +} + +local function make_plat(plat) + local defines = { + unix = { + "LUASOCKET_DEBUG" + }, + macosx = { + "LUASOCKET_DEBUG", + "UNIX_HAS_SUN_LEN" + }, + win32 = { + "LUASOCKET_DEBUG", + "NDEBUG" + }, + mingw32 = { + "LUASOCKET_DEBUG", + "LUASOCKET_INET_PTON", + "WINVER=0x0501" + } + } + local modules = { + ["socket.core"] = { + sources = { + "src/luasocket.c" + , "src/timeout.c" + , "src/buffer.c" + , "src/io.c" + , "src/auxiliar.c" + , "src/options.c" + , "src/inet.c" + , "src/except.c" + , "src/select.c" + , "src/tcp.c" + , "src/udp.c" + , "src/compat.c" }, + defines = defines[plat], + incdir = "/src" + }, + ["mime.core"] = { + sources = { "src/mime.c", "src/compat.c" }, + defines = defines[plat], + incdir = "/src" + }, + ["socket.http"] = "src/http.lua", + ["socket.url"] = "src/url.lua", + ["socket.tp"] = "src/tp.lua", + ["socket.ftp"] = "src/ftp.lua", + ["socket.headers"] = "src/headers.lua", + ["socket.smtp"] = "src/smtp.lua", + ltn12 = "src/ltn12.lua", + socket = "src/socket.lua", + mime = "src/mime.lua" + } + if plat == "unix" + or plat == "macosx" + or plat == "haiku" + then + modules["socket.core"].sources[#modules["socket.core"].sources+1] = "src/usocket.c" + if plat == "haiku" then + modules["socket.core"].libraries = {"network"} + end + modules["socket.unix"] = { + sources = { + "src/buffer.c" + , "src/compat.c" + , "src/auxiliar.c" + , "src/options.c" + , "src/timeout.c" + , "src/io.c" + , "src/usocket.c" + , "src/unix.c" + , "src/unixdgram.c" + , "src/unixstream.c" }, + defines = defines[plat], + incdir = "/src" + } + modules["socket.serial"] = { + sources = { + "src/buffer.c" + , "src/compat.c" + , "src/auxiliar.c" + , "src/options.c" + , "src/timeout.c" + , "src/io.c" + , "src/usocket.c" + , "src/serial.c" }, + defines = defines[plat], + incdir = "/src" + } + end + if plat == "win32" + or plat == "mingw32" + then + modules["socket.core"].sources[#modules["socket.core"].sources+1] = "src/wsocket.c" + modules["socket.core"].libraries = { "ws2_32" } + end + return { modules = modules } +end + +build = { + type = "builtin", + platforms = { + unix = make_plat("unix"), + macosx = make_plat("macosx"), + haiku = make_plat("haiku"), + win32 = make_plat("win32"), + mingw32 = make_plat("mingw32") + }, + copy_directories = { + "docs" + , "samples" + , "etc" + , "test" } +} -- cgit v1.2.3-55-g6feb From 1d61853ab84f0724502205f45849c2347d6a49ac Mon Sep 17 00:00:00 2001 From: Robert Scheck Date: Mon, 28 Mar 2022 13:53:32 +0200 Subject: chore: Update internal version references to match release (#370) --- docs/installation.html | 2 +- makefile.dist | 2 +- src/luasocket.h | 2 +- src/makefile | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/installation.html b/docs/installation.html index 28a9fbb..dcf9d36 100644 --- a/docs/installation.html +++ b/docs/installation.html @@ -89,7 +89,7 @@ it should be easy to use LuaSocket. Just fire the interpreter and use the Lua 5.2.2 Copyright (C) 1994-2013 Lua.org, PUC-Rio > socket = require("socket") > print(socket._VERSION) ---> LuaSocket 3.0-rc1 +--> LuaSocket 3.0.0

Each module loads their dependencies automatically, so you only need to diff --git a/makefile.dist b/makefile.dist index 3a2e100..a27ba57 100644 --- a/makefile.dist +++ b/makefile.dist @@ -1,7 +1,7 @@ #-------------------------------------------------------------------------- # Distribution makefile #-------------------------------------------------------------------------- -DIST = luasocket-3.0-rc1 +DIST = luasocket-3.0.0 TEST = \ test/README \ diff --git a/src/luasocket.h b/src/luasocket.h index d22b1be..1017fba 100644 --- a/src/luasocket.h +++ b/src/luasocket.h @@ -10,7 +10,7 @@ /*-------------------------------------------------------------------------* \ * Current socket library version \*-------------------------------------------------------------------------*/ -#define LUASOCKET_VERSION "LuaSocket 3.0-rc1" +#define LUASOCKET_VERSION "LuaSocket 3.0.0" #define LUASOCKET_COPYRIGHT "Copyright (C) 1999-2013 Diego Nehab" /*-------------------------------------------------------------------------*\ diff --git a/src/makefile b/src/makefile index f95498a..06f4d19 100755 --- a/src/makefile +++ b/src/makefile @@ -272,7 +272,7 @@ SOCKET_win64=wsocket.obj # SO=$(SO_$(PLAT)) O=$(O_$(PLAT)) -SOCKET_V=3.0-rc1 +SOCKET_V=3.0.0 MIME_V=1.0.3 SOCKET_SO=socket-$(SOCKET_V).$(SO) MIME_SO=mime-$(MIME_V).$(SO) -- cgit v1.2.3-55-g6feb From ec7d7a2b8feead992f0f9197ae299fe410ec16a0 Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Wed, 23 Mar 2022 15:57:45 +0100 Subject: cleanup; delete unreferenced powerpoint file from docs --- docs/lua05.ppt | Bin 304128 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/lua05.ppt (limited to 'docs') diff --git a/docs/lua05.ppt b/docs/lua05.ppt deleted file mode 100644 index e2b7ab4..0000000 Binary files a/docs/lua05.ppt and /dev/null differ -- cgit v1.2.3-55-g6feb From 0fc0122df8050db8cbb75f75927ab3ace0fc60bd Mon Sep 17 00:00:00 2001 From: Thijs Schreijer Date: Wed, 23 Mar 2022 15:58:50 +0100 Subject: cleanup; move logo file into docs, more appropriate --- docs/logo.ps | 210 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ logo.ps | 210 ----------------------------------------------------------- 2 files changed, 210 insertions(+), 210 deletions(-) create mode 100644 docs/logo.ps delete mode 100644 logo.ps (limited to 'docs') diff --git a/docs/logo.ps b/docs/logo.ps new file mode 100644 index 0000000..8b5809a --- /dev/null +++ b/docs/logo.ps @@ -0,0 +1,210 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%Title: Lua logo +%%Creator: lua@tecgraf.puc-rio.br +%%CreationDate: Wed Nov 29 19:04:04 EDT 2000 +%%BoundingBox: -45 0 1035 1080 +%%Pages: 1 +%%EndComments +%%EndProlog + +%------------------------------------------------------------------------------ +% +% Copyright (C) 1998-2000. All rights reserved. +% Graphic design by Alexandre Nakonechny (nako@openlink.com.br). +% PostScript programming by the Lua team (lua@tecgraf.puc-rio.br). +% +% Permission is hereby granted, without written agreement and without license +% or royalty fees, to use, copy, and distribute this logo for any purpose, +% including commercial applications, subject to the following conditions: +% +% * The origin of this logo must not be misrepresented; you must not +% claim that you drew the original logo. We recommend that you give credit +% to the graphics designer in all printed matter that includes the logo. +% +% * The only modification you can make is to adapt the orbiting text to +% your product name. +% +% * The logo can be used in any scale as long as the relative proportions +% of its elements are maintained. +% +%------------------------------------------------------------------------------ + +/LABEL (tekcoS) def + +%-- DO NOT CHANGE ANYTHING BELOW THIS LINE ------------------------------------ + +/PLANETCOLOR {0 0 0.5 setrgbcolor} bind def +/HOLECOLOR {1.0 setgray} bind def +/ORBITCOLOR {0.5 setgray} bind def +/LOGOFONT {/Helvetica 0.90} def +/LABELFONT {/Helvetica 0.36} def + +%------------------------------------------------------------------------------ + +/MOONCOLOR {PLANETCOLOR} bind def +/LOGOCOLOR {HOLECOLOR} bind def +/LABELCOLOR {ORBITCOLOR} bind def + +/LABELANGLE 325 def +/LOGO (Lua) def + +/DASHANGLE 10 def +/HALFDASHANGLE DASHANGLE 2 div def + +% moon radius. planet radius is 1. +/r 1 2 sqrt 2 div sub def + +/D {0 360 arc fill} bind def +/F {exch findfont exch scalefont setfont} bind def + +% place it nicely on the paper +/RESOLUTION 1024 def +RESOLUTION 2 div dup translate +RESOLUTION 2 div 2 sqrt div dup scale + +%-------------------------------------------------------------------- planet -- +PLANETCOLOR +0 0 1 D + +%---------------------------------------------------------------------- hole -- +HOLECOLOR +1 2 r mul sub dup r D + +%---------------------------------------------------------------------- moon -- +MOONCOLOR +1 1 r D + +%---------------------------------------------------------------------- logo -- +LOGOCOLOR +LOGOFONT +F +LOGO stringwidth pop 2 div neg +-0.5 moveto +LOGO show + +%------------------------------------------------------------------------------ +% based on code from Blue Book Program 10, on pages 167--169 +% available at ftp://ftp.adobe.com/pub/adobe/displaypostscript/bluebook.shar + +% str ptsize centerangle radius outsidecircletext -- +/outsidecircletext { + circtextdict begin + /radius exch def + /centerangle exch def + /ptsize exch def + /str exch def + + gsave + str radius ptsize findhalfangle + centerangle + add rotate + str + { /charcode exch def + ( ) dup 0 charcode put outsideplacechar + } forall + + grestore + end +} def + +% string radius ptsize findhalfangle halfangle +/findhalfangle { + 4 div add + exch + stringwidth pop 2 div + exch + 2 mul 3.1415926535 mul div 360 mul +} def + +/circtextdict 16 dict def +circtextdict begin + + /outsideplacechar { + /char exch def + /halfangle char radius ptsize findhalfangle def + gsave + halfangle neg rotate + 1.4 0 translate + 90 rotate + char stringwidth pop 2 div neg 0 moveto + char show + grestore + halfangle 2 mul neg rotate + } def + +end + +%--------------------------------------------------------------------- label -- +LABELFONT +F + +/LABELSIZE LABELFONT exch pop def +/LABELRADIUS LABELSIZE 3 div 1 r add sub neg 1.02 mul def + + +/HALFANGLE + LABEL LABELRADIUS LABELSIZE findhalfangle + HALFDASHANGLE div ceiling HALFDASHANGLE mul +def + +/LABELANGLE + 60 LABELANGLE HALFANGLE sub + lt + { + HALFANGLE + HALFANGLE DASHANGLE div floor DASHANGLE mul + eq + {LABELANGLE DASHANGLE div ceiling DASHANGLE mul} + {LABELANGLE HALFDASHANGLE sub DASHANGLE div round DASHANGLE mul HALFDASHANGLE add} + ifelse + } + {HALFANGLE 60 add} + ifelse +def + +LABELCOLOR +LABEL +LABELSIZE +LABELANGLE +LABELRADIUS +outsidecircletext + +%--------------------------------------------------------------------- orbit -- +ORBITCOLOR +0.03 setlinewidth +[1 r add 3.1415926535 180 div HALFDASHANGLE mul mul] 0 setdash +newpath +0 0 +1 r add +3 copy +30 +LABELANGLE HALFANGLE add +arcn +stroke +60 +LABELANGLE HALFANGLE sub +2 copy +lt {arc stroke} {4 {pop} repeat} ifelse + +%------------------------------------------------------------------ copyright -- +/COPYRIGHT +(Graphic design by A. Nakonechny. Copyright (c) 1998, All rights reserved.) +def + +LABELCOLOR +LOGOFONT +32 div +F +2 sqrt 0.99 mul +dup +neg +moveto +COPYRIGHT +90 rotate +%show + +%---------------------------------------------------------------------- done -- +showpage + +%%Trailer +%%EOF diff --git a/logo.ps b/logo.ps deleted file mode 100644 index 8b5809a..0000000 --- a/logo.ps +++ /dev/null @@ -1,210 +0,0 @@ -%!PS-Adobe-2.0 EPSF-2.0 -%%Title: Lua logo -%%Creator: lua@tecgraf.puc-rio.br -%%CreationDate: Wed Nov 29 19:04:04 EDT 2000 -%%BoundingBox: -45 0 1035 1080 -%%Pages: 1 -%%EndComments -%%EndProlog - -%------------------------------------------------------------------------------ -% -% Copyright (C) 1998-2000. All rights reserved. -% Graphic design by Alexandre Nakonechny (nako@openlink.com.br). -% PostScript programming by the Lua team (lua@tecgraf.puc-rio.br). -% -% Permission is hereby granted, without written agreement and without license -% or royalty fees, to use, copy, and distribute this logo for any purpose, -% including commercial applications, subject to the following conditions: -% -% * The origin of this logo must not be misrepresented; you must not -% claim that you drew the original logo. We recommend that you give credit -% to the graphics designer in all printed matter that includes the logo. -% -% * The only modification you can make is to adapt the orbiting text to -% your product name. -% -% * The logo can be used in any scale as long as the relative proportions -% of its elements are maintained. -% -%------------------------------------------------------------------------------ - -/LABEL (tekcoS) def - -%-- DO NOT CHANGE ANYTHING BELOW THIS LINE ------------------------------------ - -/PLANETCOLOR {0 0 0.5 setrgbcolor} bind def -/HOLECOLOR {1.0 setgray} bind def -/ORBITCOLOR {0.5 setgray} bind def -/LOGOFONT {/Helvetica 0.90} def -/LABELFONT {/Helvetica 0.36} def - -%------------------------------------------------------------------------------ - -/MOONCOLOR {PLANETCOLOR} bind def -/LOGOCOLOR {HOLECOLOR} bind def -/LABELCOLOR {ORBITCOLOR} bind def - -/LABELANGLE 325 def -/LOGO (Lua) def - -/DASHANGLE 10 def -/HALFDASHANGLE DASHANGLE 2 div def - -% moon radius. planet radius is 1. -/r 1 2 sqrt 2 div sub def - -/D {0 360 arc fill} bind def -/F {exch findfont exch scalefont setfont} bind def - -% place it nicely on the paper -/RESOLUTION 1024 def -RESOLUTION 2 div dup translate -RESOLUTION 2 div 2 sqrt div dup scale - -%-------------------------------------------------------------------- planet -- -PLANETCOLOR -0 0 1 D - -%---------------------------------------------------------------------- hole -- -HOLECOLOR -1 2 r mul sub dup r D - -%---------------------------------------------------------------------- moon -- -MOONCOLOR -1 1 r D - -%---------------------------------------------------------------------- logo -- -LOGOCOLOR -LOGOFONT -F -LOGO stringwidth pop 2 div neg --0.5 moveto -LOGO show - -%------------------------------------------------------------------------------ -% based on code from Blue Book Program 10, on pages 167--169 -% available at ftp://ftp.adobe.com/pub/adobe/displaypostscript/bluebook.shar - -% str ptsize centerangle radius outsidecircletext -- -/outsidecircletext { - circtextdict begin - /radius exch def - /centerangle exch def - /ptsize exch def - /str exch def - - gsave - str radius ptsize findhalfangle - centerangle - add rotate - str - { /charcode exch def - ( ) dup 0 charcode put outsideplacechar - } forall - - grestore - end -} def - -% string radius ptsize findhalfangle halfangle -/findhalfangle { - 4 div add - exch - stringwidth pop 2 div - exch - 2 mul 3.1415926535 mul div 360 mul -} def - -/circtextdict 16 dict def -circtextdict begin - - /outsideplacechar { - /char exch def - /halfangle char radius ptsize findhalfangle def - gsave - halfangle neg rotate - 1.4 0 translate - 90 rotate - char stringwidth pop 2 div neg 0 moveto - char show - grestore - halfangle 2 mul neg rotate - } def - -end - -%--------------------------------------------------------------------- label -- -LABELFONT -F - -/LABELSIZE LABELFONT exch pop def -/LABELRADIUS LABELSIZE 3 div 1 r add sub neg 1.02 mul def - - -/HALFANGLE - LABEL LABELRADIUS LABELSIZE findhalfangle - HALFDASHANGLE div ceiling HALFDASHANGLE mul -def - -/LABELANGLE - 60 LABELANGLE HALFANGLE sub - lt - { - HALFANGLE - HALFANGLE DASHANGLE div floor DASHANGLE mul - eq - {LABELANGLE DASHANGLE div ceiling DASHANGLE mul} - {LABELANGLE HALFDASHANGLE sub DASHANGLE div round DASHANGLE mul HALFDASHANGLE add} - ifelse - } - {HALFANGLE 60 add} - ifelse -def - -LABELCOLOR -LABEL -LABELSIZE -LABELANGLE -LABELRADIUS -outsidecircletext - -%--------------------------------------------------------------------- orbit -- -ORBITCOLOR -0.03 setlinewidth -[1 r add 3.1415926535 180 div HALFDASHANGLE mul mul] 0 setdash -newpath -0 0 -1 r add -3 copy -30 -LABELANGLE HALFANGLE add -arcn -stroke -60 -LABELANGLE HALFANGLE sub -2 copy -lt {arc stroke} {4 {pop} repeat} ifelse - -%------------------------------------------------------------------ copyright -- -/COPYRIGHT -(Graphic design by A. Nakonechny. Copyright (c) 1998, All rights reserved.) -def - -LABELCOLOR -LOGOFONT -32 div -F -2 sqrt 0.99 mul -dup -neg -moveto -COPYRIGHT -90 rotate -%show - -%---------------------------------------------------------------------- done -- -showpage - -%%Trailer -%%EOF -- cgit v1.2.3-55-g6feb From 0c7df119c2b71bed814db7b3da8fc379131433fe Mon Sep 17 00:00:00 2001 From: Kim Alvefur Date: Wed, 27 Jul 2022 08:16:43 +0200 Subject: feat(tcp): Add support for TCP Fast Open --- docs/tcp.html | 4 ++++ src/options.c | 16 ++++++++++++++++ src/options.h | 7 +++++++ src/tcp.c | 6 ++++++ 4 files changed, 33 insertions(+) (limited to 'docs') diff --git a/docs/tcp.html b/docs/tcp.html index 9cc173e..f15196c 100644 --- a/docs/tcp.html +++ b/docs/tcp.html @@ -485,6 +485,10 @@ disables the Nagle's algorithm for the connection;

'tcp-keepintvl': value for TCP_KEEPINTVL Linux only!!

'tcp-fastopen': value for TCP_FASTOPEN Linux only!!

+ +

'tcp-fastopen-connect': value for TCP_FASTOPEN_CONNECT Linux only!!

'ipv6-v6only': Setting this option to true restricts an inet6 socket to sending and receiving only IPv6 packets.

diff --git a/src/options.c b/src/options.c index 2b53c67..51ea351 100644 --- a/src/options.c +++ b/src/options.c @@ -190,6 +190,22 @@ int opt_set_send_buf_size(lua_State *L, p_socket ps) return opt_setint(L, ps, SOL_SOCKET, SO_SNDBUF); } +// /*------------------------------------------------------*/ + +#ifdef TCP_FASTOPEN +int opt_set_tcp_fastopen(lua_State *L, p_socket ps) +{ + return opt_setint(L, ps, IPPROTO_TCP, TCP_FASTOPEN); +} +#endif + +#ifdef TCP_FASTOPEN_CONNECT +int opt_set_tcp_fastopen_connect(lua_State *L, p_socket ps) +{ + return opt_setint(L, ps, IPPROTO_TCP, TCP_FASTOPEN_CONNECT); +} +#endif + /*------------------------------------------------------*/ int opt_set_ip6_unicast_hops(lua_State *L, p_socket ps) { diff --git a/src/options.h b/src/options.h index 41f7337..a4d5d75 100644 --- a/src/options.h +++ b/src/options.h @@ -64,6 +64,13 @@ int opt_get_recv_buf_size(lua_State *L, p_socket ps); int opt_set_send_buf_size(lua_State *L, p_socket ps); int opt_get_send_buf_size(lua_State *L, p_socket ps); +#ifdef TCP_FASTOPEN +int opt_set_tcp_fastopen(lua_State *L, p_socket ps); +#endif +#ifdef TCP_FASTOPEN_CONNECT +int opt_set_tcp_fastopen_connect(lua_State *L, p_socket ps); +#endif + int opt_set_ip6_unicast_hops(lua_State *L, p_socket ps); int opt_get_ip6_unicast_hops(lua_State *L, p_socket ps); diff --git a/src/tcp.c b/src/tcp.c index 5876bfb..e24cb0c 100644 --- a/src/tcp.c +++ b/src/tcp.c @@ -109,6 +109,12 @@ static t_opt optset[] = { {"linger", opt_set_linger}, {"recv-buffer-size", opt_set_recv_buf_size}, {"send-buffer-size", opt_set_send_buf_size}, +#ifdef TCP_FASTOPEN + {"tcp-fastopen", opt_set_tcp_fastopen}, +#endif +#ifdef TCP_FASTOPEN_CONNECT + {"tcp-fastopen-connect", opt_set_tcp_fastopen_connect}, +#endif {NULL, NULL} }; -- cgit v1.2.3-55-g6feb From d1ad8160cba9e504c9d17665492044a93efdc3ab Mon Sep 17 00:00:00 2001 From: Kim Alvefur Date: Wed, 27 Jul 2022 08:40:18 +0200 Subject: feat(tcp): Add support for TCP Defer Accept This makes it so that a listening socket does not become readable for accept() until a connection has been fully established *and* started sending something, thus the program doesn't have to wait for the first data. This only makes sense for client-speaks-first protocols. Co-authored-by: Caleb Maclennan --- docs/tcp.html | 2 ++ src/options.c | 9 +++++++++ src/options.h | 4 ++++ src/tcp.c | 3 +++ 4 files changed, 18 insertions(+) (limited to 'docs') diff --git a/docs/tcp.html b/docs/tcp.html index f15196c..a26228d 100644 --- a/docs/tcp.html +++ b/docs/tcp.html @@ -485,6 +485,8 @@ disables the Nagle's algorithm for the connection;

'tcp-keepintvl': value for TCP_KEEPINTVL Linux only!!

'tcp-defer-accept': value for TCP_DEFER_ACCEPT Linux only!!

'tcp-fastopen': value for TCP_FASTOPEN Linux only!!

'tcp-fastopen-connect': value for TCP_FASTOPEN_CONNECT Linux only!!

diff --git a/src/options.c b/src/options.c index 51ea351..3280c51 100644 --- a/src/options.c +++ b/src/options.c @@ -206,6 +206,15 @@ int opt_set_tcp_fastopen_connect(lua_State *L, p_socket ps) } #endif +/*------------------------------------------------------*/ + +#ifdef TCP_DEFER_ACCEPT +int opt_set_tcp_defer_accept(lua_State *L, p_socket ps) +{ + return opt_setint(L, ps, IPPROTO_TCP, TCP_DEFER_ACCEPT); +} +#endif + /*------------------------------------------------------*/ int opt_set_ip6_unicast_hops(lua_State *L, p_socket ps) { diff --git a/src/options.h b/src/options.h index a4d5d75..456eeb5 100644 --- a/src/options.h +++ b/src/options.h @@ -49,6 +49,10 @@ int opt_set_tcp_keepintvl(lua_State *L, p_socket ps); int opt_get_tcp_keepintvl(lua_State *L, p_socket ps); #endif +#ifdef TCP_DEFER_ACCEPT +int opt_set_tcp_defer_accept(lua_State *L, p_socket ps); +#endif + int opt_set_keepalive(lua_State *L, p_socket ps); int opt_get_keepalive(lua_State *L, p_socket ps); diff --git a/src/tcp.c b/src/tcp.c index e24cb0c..e84db84 100644 --- a/src/tcp.c +++ b/src/tcp.c @@ -109,6 +109,9 @@ static t_opt optset[] = { {"linger", opt_set_linger}, {"recv-buffer-size", opt_set_recv_buf_size}, {"send-buffer-size", opt_set_send_buf_size}, +#ifdef TCP_DEFER_ACCEPT + {"tcp-defer-accept", opt_set_tcp_defer_accept}, +#endif #ifdef TCP_FASTOPEN {"tcp-fastopen", opt_set_tcp_fastopen}, #endif -- cgit v1.2.3-55-g6feb From 95b7efa9da506ef968c1347edf3fc56370f0deed Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 27 Jul 2022 10:06:54 +0300 Subject: chore: Release v3.1.0 --- CHANGELOG.md | 7 ++ docs/index.html | 2 +- rockspecs/luasocket-3.1.0-1.rockspec | 135 +++++++++++++++++++++++++++++++++++ 3 files changed, 143 insertions(+), 1 deletion(-) create mode 100644 rockspecs/luasocket-3.1.0-1.rockspec (limited to 'docs') diff --git a/CHANGELOG.md b/CHANGELOG.md index 0de05f3..3a25186 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## [v3.1.0](https://github.com/lunarmodules/luasocket/releases/v3.1.0) — 2022-07-27 + +* Add support for TCP Defer Accept – @Zash +* Add support for TCP Fast Open – @Zash +* Fix Windows (mingw32) builds – @goldenstein64 +* Avoid build warnings on 64-bit Windows – @rpatters1 + ## [v3.0.0](https://github.com/lunarmodules/luasocket/releases/v3.0.0) — 2022-03-25 The last time LuaSocket had a stable release tag was 14 years ago when 2.0.2 was tagged. diff --git a/docs/index.html b/docs/index.html index 31e18ad..ad92687 100644 --- a/docs/index.html +++ b/docs/index.html @@ -87,7 +87,7 @@ Author: Diego Nehab

Download

-LuaSocket version 3.0.0 is now available for download! +LuaSocket version 3.1.0 is now available for download! It is compatible with Lua 5.1 through 5.4. Chances are it works well on most UNIX distributions and Windows flavors.

diff --git a/rockspecs/luasocket-3.1.0-1.rockspec b/rockspecs/luasocket-3.1.0-1.rockspec new file mode 100644 index 0000000..2d724ac --- /dev/null +++ b/rockspecs/luasocket-3.1.0-1.rockspec @@ -0,0 +1,135 @@ +package = "LuaSocket" +version = "3.1.0-1" +source = { + url = "git+https://github.com/lunarmodules/luasocket.git", + tag = "v3.1.0" +} +description = { + summary = "Network support for the Lua language", + detailed = [[ + LuaSocket is a Lua extension library composed of two parts: a set of C + modules that provide support for the TCP and UDP transport layers, and a + set of Lua modules that provide functions commonly needed by applications + that deal with the Internet. + ]], + homepage = "https://github.com/lunarmodules/luasocket", + license = "MIT" +} +dependencies = { + "lua >= 5.1" +} + +local function make_plat(plat) + local defines = { + unix = { + "LUASOCKET_DEBUG" + }, + macosx = { + "LUASOCKET_DEBUG", + "UNIX_HAS_SUN_LEN" + }, + win32 = { + "LUASOCKET_DEBUG", + "NDEBUG" + }, + mingw32 = { + "LUASOCKET_DEBUG", + -- "LUASOCKET_INET_PTON", + "WINVER=0x0501" + } + } + local modules = { + ["socket.core"] = { + sources = { + "src/luasocket.c" + , "src/timeout.c" + , "src/buffer.c" + , "src/io.c" + , "src/auxiliar.c" + , "src/options.c" + , "src/inet.c" + , "src/except.c" + , "src/select.c" + , "src/tcp.c" + , "src/udp.c" + , "src/compat.c" }, + defines = defines[plat], + incdir = "/src" + }, + ["mime.core"] = { + sources = { "src/mime.c", "src/compat.c" }, + defines = defines[plat], + incdir = "/src" + }, + ["socket.http"] = "src/http.lua", + ["socket.url"] = "src/url.lua", + ["socket.tp"] = "src/tp.lua", + ["socket.ftp"] = "src/ftp.lua", + ["socket.headers"] = "src/headers.lua", + ["socket.smtp"] = "src/smtp.lua", + ltn12 = "src/ltn12.lua", + socket = "src/socket.lua", + mime = "src/mime.lua" + } + if plat == "unix" + or plat == "macosx" + or plat == "haiku" + then + modules["socket.core"].sources[#modules["socket.core"].sources+1] = "src/usocket.c" + if plat == "haiku" then + modules["socket.core"].libraries = {"network"} + end + modules["socket.unix"] = { + sources = { + "src/buffer.c" + , "src/compat.c" + , "src/auxiliar.c" + , "src/options.c" + , "src/timeout.c" + , "src/io.c" + , "src/usocket.c" + , "src/unix.c" + , "src/unixdgram.c" + , "src/unixstream.c" }, + defines = defines[plat], + incdir = "/src" + } + modules["socket.serial"] = { + sources = { + "src/buffer.c" + , "src/compat.c" + , "src/auxiliar.c" + , "src/options.c" + , "src/timeout.c" + , "src/io.c" + , "src/usocket.c" + , "src/serial.c" }, + defines = defines[plat], + incdir = "/src" + } + end + if plat == "win32" + or plat == "mingw32" + then + modules["socket.core"].sources[#modules["socket.core"].sources+1] = "src/wsocket.c" + modules["socket.core"].libraries = { "ws2_32" } + modules["socket.core"].libdirs = {} + end + return { modules = modules } +end + +build = { + type = "builtin", + platforms = { + unix = make_plat("unix"), + macosx = make_plat("macosx"), + haiku = make_plat("haiku"), + win32 = make_plat("win32"), + mingw32 = make_plat("mingw32") + }, + copy_directories = { + "docs" + , "samples" + , "etc" + , "test" } +} -- cgit v1.2.3-55-g6feb