diff options
Diffstat (limited to 'Build/source/texk/web2c/luatexdir/luasocket/doc/introduction.html')
-rw-r--r-- | Build/source/texk/web2c/luatexdir/luasocket/doc/introduction.html | 333 |
1 files changed, 0 insertions, 333 deletions
diff --git a/Build/source/texk/web2c/luatexdir/luasocket/doc/introduction.html b/Build/source/texk/web2c/luatexdir/luasocket/doc/introduction.html deleted file mode 100644 index fd22f483deb..00000000000 --- a/Build/source/texk/web2c/luatexdir/luasocket/doc/introduction.html +++ /dev/null @@ -1,333 +0,0 @@ -<!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="index.html">home</a> · -<a href="index.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="index.html">home</a> · -<a href="index.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> |