-- waits for input on three sockets and broadcasts any received lines
server = bind("localhost", 8080)
a = server:accept(); b = server:accept(); c = server:accept()
a:timeout(1); b:timeout(1); c:timeout(1)
while 1 do
  r, _, e = select({a,b,c}, nil)
  for i,v in r do
    l, e = v:receive()
    if e then exit() end
    _, s, e = select(nil, {a,b,c}, 1)
    for j,u in s do
      e = u:send(l, "\n") 
      if e then exit() end
    end
  end
end

options = {
  ["option-1-name"] = value-1,
  ["option-2-name"] = value-2,
  ["option-3-name"] = value-3,
         ...            ...
  ["option-n-name"] = value-n
}

headers = {
  to = "fulano@tecgraf.puc-rio.br, beltrano@tecgraf.puc-rio.br",
  subject = "LuaSocket test message"
}
from = "luasocket@tecgraf.puc-rio.br"
rcpt = {
  "fulano@tecgraf.puc-rio.br",
  "beltrano@tecgraf.puc-rio.br",
  "sicrano@tecgraf.puc-rio.br"
}
body = "This is a test message. Please ignore."
server = "local"
-- connects to server "local" and sends a message to users 
-- "fulano@tecgraf.puc-rio.br" and "beltrano@tecgraf.puc-rio.br"
-- "sicrano@tecgraf.puc-rio.br" receives a 'blind carbon copy' of the message.
e = smtp_mail(from, rcpt, headers, body, server)

The callback provided by the user will be repeatedly called by the library whenever new data is available. Each time it is called, the callback receives successive chunks of downloaded data. When the transmission is over, the function is called with an empty string (i.e. "") as the chunk. If an error occurs, the function receives a nil chunk and an error message as the err argument. The callback can abort transmission by returning nil as its first return value. In that case, it can also return an error message. Any non-nil return value proceeds with the transmission.

Examples:

-- saves incoming file to disk, receiving chunk by chunk
local file = openfile(tmpname(), "wb")       -- open temp file for writing
local receive_cb = function(chunk, err)
    if chunk and chunk ~= "" then
        local res, err = write(%file, chunk) -- try to write to disk
        if not res then return nil, err      -- woops! abort with error message
        else return 1 end                    -- all is ok, please go on
    else closefile(%file) end                -- we are done
end

-- print throughput feedback while receiving data
local aux = { start = _time(), got = 0 }     -- auxiliar table
local receive_cb = function(chunk, err)
    local dt = _time() - %aux.start          -- elapsed time since start
    if not chunk or chunk == "" then return end
    %aux.got = %aux.got + strlen(chunk)      -- total bytes received
    if dt < 0.1 then return 1 end            -- not enough time for estimate
    local rate = %aux.got / dt               -- get download rate
    write("\r" .. format("%.2f", rate))      -- print estimate
    return 1                                 -- ready for more
end

The callback provided by the user will be repeatedly called whenever the library needs more data to be sent. Each time the callback is called, it should return the next part of the information the library is expecting, followed by the total number of bytes to be sent. The callback can abort the process at any time by returning nil followed by an optional error message.

Obs: The need for the second return value comes from the fact that, with the HTTP protocol for instance, the library needs to know in advance the total number of bytes that will be sent.

Examples:

-- sends data from file, in blocks of 4096 bytes
local file = openfile("words", "rb")         -- open file for reading
local size = seek(file, "end")               -- get file size 
seek(file, "set")                            
local send_cb = function()
    local chunk = read(%file, 4096)          -- try to read chunk
    if not chunk then                        -- are we done?
        closefile(%file) 
        return "", %size 
    else return chunk, %size end             -- if not, send what we got
end

-- sends everything in the first call
local file = openfile("words", "rb")         -- open file for reading
local data = read(file, "*a")
closefile(file)
local send_cb = function()
    return %data, strlen(%data)              -- return everything
end

-- connect to server "www.tecgraf.puc-rio.br" and retrieves this manual
-- file from "~diego/luasocket/manual.html"
f, m, s, e = http_get("http://www.tecgraf.puc-rio.br/~diego/luasocket/manual.html")

-- connect to server "www.tecgraf.puc-rio.br" and tries to retrieve
-- "~diego/auth/index.html". Fails because authentication is needed.
f, m, s, e = http_get("http://www.tecgraf.puc-rio.br/~diego/auth/index.html")
-- s returns with value "401 Authentication Required"

-- log as user "anonymous" on server "ftp.tecgraf.puc-rio.br"
-- go to directory "pub/lua" and get file "lua.tar.gz" as binary.
f, e = ftp_get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz", "b")

-- log as user "anonymous" on server "ftp.tecgraf.puc-rio.br"
-- go to director "pub" and retrieve directory listing of directory "lua"
f, e = ftp_get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/")

-- log as user "diego", password "nehab", on server "derain.tecgraf.puc-rio.br"
-- go to directory "tec/luasocket/html" and retrieve file "manual.html"
-- (actually, fails because of wrong password :-)
f, e = ftp_get("ftp://diego:nehab@derain.tecgraf.puc-rio.br/tec/luasocket/html/manual.html")