Blame doc/socket.html

Packit b53373
Packit b53373
    "http://www.w3.org/TR/html4/strict.dtd">
Packit b53373
<html>
Packit b53373
Packit b53373
<head>
Packit b53373
<meta name="description" content="LuaSocket: The core namespace">
Packit b53373
<meta name="keywords" content="Lua, LuaSocket, Socket, Network, Library, Support"> 
Packit b53373
<title>LuaSocket: The socket namespace</title>
Packit b53373
<link rel="stylesheet" href="reference.css" type="text/css">
Packit b53373
</head>
Packit b53373
Packit b53373
<body>
Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
<center>
Packit b53373
Packit b53373
Packit b53373
LuaSocket
Packit b53373
Packit b53373
Network support for the Lua language
Packit b53373
Packit b53373
Packit b53373

Packit b53373
home ·
Packit b53373
download ·
Packit b53373
installation ·
Packit b53373
introduction ·
Packit b53373
reference 
Packit b53373

Packit b53373
</center>
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373
Packit b53373

The socket namespace

Packit b53373
Packit b53373

Packit b53373
The <tt>socket</tt> namespace contains the core functionality of LuaSocket. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
To obtain the <tt>socket</tt> namespace, run:
Packit b53373

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

Packit b53373
socket.bind(address, port [, backlog])
Packit b53373

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373

Packit b53373
Note: The server object returned will have the option "<tt>reuseaddr</tt>" 
Packit b53373
set to <tt>true</tt>.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

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

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
socket._DEBUG
Packit b53373

Packit b53373
Packit b53373

Packit b53373
This constant is set to <tt>true</tt> if the library was compiled
Packit b53373
with debug support.
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
socket.gettime()
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Returns the time in seconds, relative to the origin of the 
Packit b53373
universe. You should subtract the values returned by this function
Packit b53373
to get meaningful values. 
Packit b53373

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

Packit b53373
socket.headers.canonic

Packit b53373
Packit b53373

The <tt>socket.headers.canonic</tt> table

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

Packit b53373
Packit b53373

Packit b53373
You can obtain the <tt>headers</tt> namespace if case run-time
Packit b53373
modifications are required by running:
Packit b53373

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

Packit b53373
socket.newtry(finalizer)
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Creates and returns a clean 
Packit b53373
<tt>try</tt>
Packit b53373
function that allows for cleanup before the exception 
Packit b53373
is  raised. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>Finalizer</tt> is a function that will be called before
Packit b53373
<tt>try</tt> throws the exception. It will be called 
Packit b53373
in protected mode.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
The function returns your customized <tt>try</tt> function. 
Packit b53373

Packit b53373
Packit b53373

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

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

Packit b53373
socket.protect(func)
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Converts a function that throws exceptions into a safe function. This
Packit b53373
function only catches exceptions thrown by the <tt>try</tt>
Packit b53373
and <tt>newtry</tt> functions. It does not catch normal 
Packit b53373
Lua errors.
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>Func</tt> is a function that calls 
Packit b53373
<tt>try</tt> (or <tt>assert</tt>, or <tt>error</tt>) 
Packit b53373
to throw exceptions. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Returns an equivalent function that instead of throwing exceptions,
Packit b53373
returns <tt>nil</tt> followed by an error message. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Note: Beware that if your function performs some illegal operation that
Packit b53373
raises an error, the protected function will catch the error and return it
Packit b53373
as a string. This is because the <tt>try</tt> function
Packit b53373
uses errors as the mechanism to throw exceptions.  
Packit b53373

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
socket.select(recvt, sendt [, timeout])
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Waits for a number of sockets to change status. 
Packit b53373

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373

The function returns a list with the sockets ready for

Packit b53373
reading, a list with the sockets ready for writing and an error message.
Packit b53373
The error message is "<tt>timeout</tt>" if a timeout condition was met and
Packit b53373
<tt>nil</tt> otherwise. The returned tables are
Packit b53373
doubly keyed both by integers and also by the sockets
Packit b53373
themselves, to simplify the test if a specific socket has
Packit b53373
changed status. 
Packit b53373

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373

Packit b53373
Yet another note: If you close a socket and pass
Packit b53373
it to <tt>select</tt>, it will be ignored.
Packit b53373

Packit b53373
Packit b53373

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

Packit b53373
Packit b53373
Packit b53373
Packit b53373

Packit b53373
socket.sink(mode, socket)
Packit b53373

Packit b53373
Packit b53373

Packit b53373
Creates an 
Packit b53373
LTN12
Packit b53373
sink from a stream socket object. 
Packit b53373

Packit b53373
Packit b53373

Packit b53373
<tt>Mode</tt> defines the behavior of the sink. The following
Packit b53373
options are available:
Packit b53373

Packit b53373
    Packit b53373
  • <tt>"http-chunked"</tt>: sends data through socket after applying the
  • Packit b53373
    chunked transfer coding, closing the socket when done;
    Packit b53373
  • <tt>"close-when-done"</tt>: sends all received data through the
  • Packit b53373
    socket, closing the socket when done; 
    Packit b53373
  • <tt>"keep-open"</tt>: sends all received data through the
  • Packit b53373
    socket, leaving it open when done. 
    Packit b53373
    Packit b53373

    Packit b53373
    <tt>Socket</tt> is the stream socket object used to send the data. 
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    The function returns a sink with the appropriate behavior. 
    Packit b53373

    Packit b53373
    Packit b53373
    Packit b53373
    Packit b53373

    Packit b53373
    socket.skip(d [, ret<sub>1</sub>, ret<sub>2</sub> ...  ret<sub>N</sub>])
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    Drops a number of arguments and returns the remaining.
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    <tt>D</tt> is the number of arguments to drop. <tt>Ret<sub>1</sub></tt> to
    Packit b53373
    <tt>ret<sub>N</sub></tt> are the arguments.
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    The function returns <tt>ret<sub>d+1</sub></tt> to <tt>ret<sub>N</sub></tt>.
    Packit b53373

    Packit b53373
    Packit b53373

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

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

    Packit b53373
    socket.sleep(time)
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    Freezes the program execution during a given amount of time.
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    <tt>Time</tt> is the number of seconds to sleep for. If
    Packit b53373
    <tt>time</tt> is negative, the function returns immediately.
    Packit b53373

    Packit b53373
    Packit b53373
    Packit b53373
    Packit b53373

    Packit b53373
    socket.source(mode, socket [, length])
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    Creates an 
    Packit b53373
    LTN12
    Packit b53373
    source from a stream socket object. 
    Packit b53373

    Packit b53373
    Packit b53373

    Packit b53373
    <tt>Mode</tt> defines the behavior of the source. The following
    Packit b53373
    options are available:
    Packit b53373

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

      Packit b53373
      <tt>Socket</tt> is the stream socket object used to receive the data. 
      Packit b53373

      Packit b53373
      Packit b53373

      Packit b53373
      The function returns a source with the appropriate behavior. 
      Packit b53373

      Packit b53373
      Packit b53373
      Packit b53373
      Packit b53373

      Packit b53373
      socket._SETSIZE
      Packit b53373

      Packit b53373
      Packit b53373

      Packit b53373
      The maximum number of sockets that the 
      Packit b53373
      href=#select><tt>select</tt> function can handle. 
      Packit b53373

      Packit b53373
      Packit b53373
      Packit b53373
      Packit b53373

      Packit b53373
      socket.try(ret<sub>1</sub> [, ret<sub>2</sub> ... ret<sub>N</sub>])
      Packit b53373

      Packit b53373
      Packit b53373

      Packit b53373
      Throws an exception in case of error. The exception can only be caught 
      Packit b53373
      by the <tt>protect</tt> function. It does not explode
      Packit b53373
      into an error message.
      Packit b53373

      Packit b53373
      Packit b53373

      Packit b53373
      <tt>Ret<sub>1</sub></tt> to <tt>ret<sub>N</sub></tt> can be arbitrary
      Packit b53373
      arguments, but are usually the return values of a function call 
      Packit b53373
      nested with <tt>try</tt>. 
      Packit b53373

      Packit b53373
      Packit b53373

      Packit b53373
      The function returns <tt>ret</tt><sub>1</sub> to <tt>ret</tt><sub>N</sub> if
      Packit b53373
      <tt>ret</tt><sub>1</sub> is not <tt>nil</tt>. Otherwise, it calls <tt>error</tt> passing <tt>ret</tt><sub>2</sub>.
      Packit b53373

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

      Packit b53373
      socket._VERSION
      Packit b53373

      Packit b53373
      Packit b53373

      Packit b53373
      This constant has a string describing the current LuaSocket version. 
      Packit b53373

      Packit b53373
      Packit b53373
      Packit b53373
      Packit b53373
      Packit b53373

      Packit b53373
      <center>
      Packit b53373

      Packit b53373
      home ·
      Packit b53373
      download ·
      Packit b53373
      installation ·
      Packit b53373
      introduction ·
      Packit b53373
      reference
      Packit b53373

      Packit b53373

      Packit b53373
      <small>
      Packit b53373
      Last modified by Diego Nehab on 
      Packit b53373
      Thu Apr 20 00:25:54 EDT 2006
      Packit b53373
      </small>
      Packit b53373

      Packit b53373
      </center>
      Packit b53373
      Packit b53373
      Packit b53373
      </body>
      Packit b53373
      </html>