| <!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> · |
| <a href="home.html#download">download</a> · |
| <a href="installation.html">installation</a> · |
| <a href="introduction.html">introduction</a> · |
| <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> · |
| <a href="home.html#down">download</a> · |
| <a href="installation.html">installation</a> · |
| <a href="introduction.html">introduction</a> · |
| <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> |