<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
    "http://www.w3.org/TR/html4/strict.dtd">
<html>

<head>
<meta name="description" content="LuaSocket: Introduction to the core">
<meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network,
Library, Support"> 
<title>LuaSocket: Introduction to the core</title>
<link rel="stylesheet" href="reference.css" type="text/css">
</head>

<body>

<!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<div class=header>
<hr>
<center>
<table summary="LuaSocket logo">
<tr><td align=center><a href="http://www.lua.org">
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
</a></td></tr>
<tr><td align=center valign=top>Network support for the Lua language
</td></tr>
</table>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#download">download</a> &middot;
<a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a> 
</p>
</center>
<hr>
</div>

<!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<h2>Introduction</h2>

<p>
LuaSocket  is a  <a href="http://www.lua.org">Lua</a>  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.
</p>

<p>
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.
</p>

<p>
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.  
</p>


<p>
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.  
</p>

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

<p>
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 
<a href=dns.html#toip><tt>toip</tt></a> 
and <a href=dns.html#tohostname><tt>tohostname</tt></a> 
functions from the DNS module are provided to convert between host names and IP addresses. 
</p>

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

<!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<h3 id=tcp>TCP</h3>

<p>
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. 
</p>

<p>
The library distinguishes  three types of TCP sockets:  <em>master</em>, 
<em>client</em> and <em>server</em> sockets. 
</p>

<p>
Master sockets are newly created TCP sockets returned by the function
<a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is 
transformed into a server socket
after it is associated with a <em>local</em> address by a call to the
<a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the 
<a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket 
can be changed into a client socket with the method 
<a href=tcp.html#connect><tt>connect</tt></a>, 
which associates it with a <em>remote</em> address. 
</p>

<p>
On server sockets, applications can use the 
<a href=tcp.html#accept><tt>accept</tt></a> 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
<a href=tcp.html#getsockname><tt>getsockname</tt></a>,  
<a href=tcp.html#setoption><tt>setoption</tt></a>,
<a href=tcp.html#settimeout><tt>settimeout</tt></a>, and 
<a href=tcp.html#close><tt>close</tt></a>. 
</p>

<p>
Client sockets are  used to exchange data between  two applications over
the Internet. Applications can call the  methods 
<a href=tcp.html#send><tt>send</tt></a> and
<a href=tcp.html#receive><tt>receive</tt></a> 
to send and  receive data.  The other methods
available for  client socket objects are 
<a href=tcp.html#getsockname><tt>getsockname</tt></a>,
<a href=tcp.html#getpeername><tt>getpeername</tt></a>, 
<a href=tcp.html#setoption><tt>setoption</tt></a>,
<a href=tcp.html#settimeout><tt>settimeout</tt></a>,
<a href=tcp.html#shutdown><tt>shutdown</tt></a>, and
<a href=tcp.html#close><tt>close</tt></a>.
</p>

<p>
Example:
</p>
<blockquote>
<p>
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. 
</p>

<pre class=example>
-- 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
</pre>
</blockquote>

<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<h3 id=udp>UDP</h3>

<p>
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). 
</p>

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

<p>
An UDP socket object is  created by the 
<a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
sockets  do   not  need   to  be  connected   before  use.   The  method
<a href=udp.html#sendto><tt>sendto</tt></a>  
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 
<a href=udp.html#receive><tt>receive</tt></a>  and 
<a href=udp.html#receivefrom><tt>receivefrom</tt></a>
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). 
</p>

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

<p>
To associate  an UDP socket with  a local address, an  application calls the   
<a href=udp.html#setsockname><tt>setsockname</tt></a> 
method <em>before</em> 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
<a href=udp.html#getpeername><tt>getpeername</tt></a>,  
<a href=udp.html#getsockname><tt>getsockname</tt></a>, 
<a href=udp.html#settimeout><tt>settimeout</tt></a>,
<a href=udp.html#setoption><tt>setoption</tt></a> and 
<a href=udp.html#close><tt>close</tt></a>. 
</p>

<p>
Example: 
</p>
<blockquote>
<p>
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. 
</p>

<pre class=example>
-- 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()))
</pre>
</blockquote>

<!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<h3 id=more>Support modules</h3>

<p> Although not covered in the introduction, LuaSocket offers 
much more than TCP and UDP functionality. As the library
evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>,
and <a href=smtp.html>SMTP</a> were built on top of these. These modules
and many others are covered by the <a href=reference.html>reference manual</a>. 
</p>

<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<div class=footer>
<hr>
<center>
<p class=bar>
<a href="home.html">home</a> &middot;
<a href="home.html#down">download</a> &middot;
<a href="installation.html">installation</a> &middot;
<a href="introduction.html">introduction</a> &middot;
<a href="reference.html">reference</a>
</p>
<p>
<small>
Last modified by Diego Nehab on <br>
Thu Apr 20 00:25:36 EDT 2006
</small>
</p>
</center>
</div>

</body>
</html>