PageRenderTime 48ms CodeModel.GetById 25ms RepoModel.GetById 1ms app.codeStats 0ms

HTML | 333 lines | 289 code | 38 blank | 6 comment | 0 complexity | d71c3a29ef77463115631b38d041008f MD5 | raw file
Possible License(s): GPL-2.0, MIT
  2. "">
  3. <html>
  4. <head>
  5. <meta name="description" content="LuaSocket: Introduction to the core">
  6. <meta name="keywords" content="Lua, LuaSocket, TCP, UDP, Network,
  7. Library, Support">
  8. <title>LuaSocket: Introduction to the core</title>
  9. <link rel="stylesheet" href="reference.css" type="text/css">
  10. </head>
  11. <body>
  12. <!-- header +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  13. <div class=header>
  14. <hr>
  15. <center>
  16. <table summary="LuaSocket logo">
  17. <tr><td align=center><a href="">
  18. <img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
  19. </a></td></tr>
  20. <tr><td align=center valign=top>Network support for the Lua language
  21. </td></tr>
  22. </table>
  23. <p class=bar>
  24. <a href="home.html">home</a> &middot;
  25. <a href="home.html#download">download</a> &middot;
  26. <a href="installation.html">installation</a> &middot;
  27. <a href="introduction.html">introduction</a> &middot;
  28. <a href="reference.html">reference</a>
  29. </p>
  30. </center>
  31. <hr>
  32. </div>
  33. <!-- introduction +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  34. <h2>Introduction</h2>
  35. <p>
  36. LuaSocket is a <a href="">Lua</a> extension library
  37. that is composed by two parts: a C core that provides support for the TCP
  38. and UDP transport layers, and a set of Lua modules that add support for
  39. the SMTP (sending e-mails), HTTP (WWW access) and FTP (uploading and
  40. downloading files) protocols and other functionality commonly needed by
  41. applications that deal with the Internet. This introduction is about the C
  42. core.
  43. </p>
  44. <p>
  45. Communication in LuaSocket is performed via I/O objects. These can
  46. represent different network domains. Currently, support is provided for TCP
  47. and UDP, but nothing prevents other developers from implementing SSL, Local
  48. Domain, Pipes, File Descriptors etc. I/O objects provide a standard
  49. interface to I/O across different domains and operating systems.
  50. </p>
  51. <p>
  52. The API design had two goals in mind. First, users
  53. experienced with the C API to sockets should feel comfortable using LuaSocket.
  54. Second, the simplicity and the feel of the Lua language should be
  55. 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.
  56. </p>
  57. <p>
  58. One of the simplifications is the receive pattern capability.
  59. Applications can read data from stream domains (such as TCP)
  60. line by line, block by block, or until the connection is closed.
  61. All I/O reads are buffered and the performance differences between
  62. different receive patterns are negligible.
  63. </p>
  64. <p>
  65. Another advantage is the flexible timeout control
  66. mechanism. As in C, all I/O operations are blocking by default. For
  67. example, the <a href=tcp.html#send><tt>send</tt></a>,
  68. <a href=tcp.html#receive><tt>receive</tt></a> and
  69. <a href=tcp.html#accept><tt>accept</tt></a> methods
  70. of the TCP domain will block the caller application until
  71. the operation is completed (if ever!). However, with a call to the
  72. <a href=tcp.html#settimeout><tt>settimeout</tt></a>
  73. method, an application can specify upper limits on
  74. the time it can be blocked by LuaSocket (the "<tt>total</tt>" timeout), on
  75. the time LuaSocket can internally be blocked by any OS call (the
  76. "<tt>block</tt>" timeout) or a combination of the two. Each LuaSocket
  77. call might perform several OS calls, so that the two timeout values are
  78. <em>not</em> equivalent.
  79. </p>
  80. <p>
  81. Finally, the host name resolution is transparent, meaning that most
  82. functions and methods accept both IP addresses and host names. In case a
  83. host name is given, the library queries the system's resolver and
  84. tries the main IP address returned. Note that direct use of IP addresses
  85. is more efficient, of course. The
  86. <a href=dns.html#toip><tt>toip</tt></a>
  87. and <a href=dns.html#tohostname><tt>tohostname</tt></a>
  88. functions from the DNS module are provided to convert between host names and IP addresses.
  89. </p>
  90. <p>
  91. Together, these changes make network programming in LuaSocket much simpler
  92. than it is in C, as the following sections will show.
  93. </p>
  94. <!-- tcp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  95. <h3 id=tcp>TCP</h3>
  96. <p>
  97. TCP (Transfer Control Protocol) is reliable stream protocol. In other
  98. words, applications communicating through TCP can send and receive data as
  99. an error free stream of bytes. Data is split in one end and
  100. reassembled transparently on the other end. There are no boundaries in
  101. the data transfers. The library allows users to read data from the
  102. sockets in several different granularities: patterns are available for
  103. lines, arbitrary sized blocks or "read up to connection closed", all with
  104. good performance.
  105. </p>
  106. <p>
  107. The library distinguishes three types of TCP sockets: <em>master</em>,
  108. <em>client</em> and <em>server</em> sockets.
  109. </p>
  110. <p>
  111. Master sockets are newly created TCP sockets returned by the function
  112. <a href=tcp.html#tcp><tt>socket.tcp</tt></a>. A master socket is
  113. transformed into a server socket
  114. after it is associated with a <em>local</em> address by a call to the
  115. <a href=tcp.html#bind><tt>bind</tt></a> method followed by a call to the
  116. <a href=tcp.html#listen><tt>listen</tt></a>. Conversely, a master socket
  117. can be changed into a client socket with the method
  118. <a href=tcp.html#connect><tt>connect</tt></a>,
  119. which associates it with a <em>remote</em> address.
  120. </p>
  121. <p>
  122. On server sockets, applications can use the
  123. <a href=tcp.html#accept><tt>accept</tt></a> method
  124. to wait for a client connection. Once a connection is established, a
  125. client socket object is returned representing this connection. The
  126. other methods available for server socket objects are
  127. <a href=tcp.html#getsockname><tt>getsockname</tt></a>,
  128. <a href=tcp.html#setoption><tt>setoption</tt></a>,
  129. <a href=tcp.html#settimeout><tt>settimeout</tt></a>, and
  130. <a href=tcp.html#close><tt>close</tt></a>.
  131. </p>
  132. <p>
  133. Client sockets are used to exchange data between two applications over
  134. the Internet. Applications can call the methods
  135. <a href=tcp.html#send><tt>send</tt></a> and
  136. <a href=tcp.html#receive><tt>receive</tt></a>
  137. to send and receive data. The other methods
  138. available for client socket objects are
  139. <a href=tcp.html#getsockname><tt>getsockname</tt></a>,
  140. <a href=tcp.html#getpeername><tt>getpeername</tt></a>,
  141. <a href=tcp.html#setoption><tt>setoption</tt></a>,
  142. <a href=tcp.html#settimeout><tt>settimeout</tt></a>,
  143. <a href=tcp.html#shutdown><tt>shutdown</tt></a>, and
  144. <a href=tcp.html#close><tt>close</tt></a>.
  145. </p>
  146. <p>
  147. Example:
  148. </p>
  149. <blockquote>
  150. <p>
  151. A simple echo server, using LuaSocket. The program binds to an ephemeral
  152. port (one that is chosen by the operating system) on the local host and
  153. awaits client connections on that port. When a connection is established,
  154. the program reads a line from the remote end and sends it back, closing
  155. the connection immediately. You can test it using the telnet
  156. program.
  157. </p>
  158. <pre class=example>
  159. -- load namespace
  160. local socket = require("socket")
  161. -- create a TCP socket and bind it to the local host, at any port
  162. local server = assert(socket.bind("*", 0))
  163. -- find out which port the OS chose for us
  164. local ip, port = server:getsockname()
  165. -- print a message informing what's up
  166. print("Please telnet to localhost on port " .. port)
  167. print("After connecting, you have 10s to enter a line to be echoed")
  168. -- loop forever waiting for clients
  169. while 1 do
  170. -- wait for a connection from any client
  171. local client = server:accept()
  172. -- make sure we don't block waiting for this client's line
  173. client:settimeout(10)
  174. -- receive the line
  175. local line, err = client:receive()
  176. -- if there was no error, send it back to the client
  177. if not err then client:send(line .. "\n") end
  178. -- done with client, close the object
  179. client:close()
  180. end
  181. </pre>
  182. </blockquote>
  183. <!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  184. <h3 id=udp>UDP</h3>
  185. <p>
  186. UDP (User Datagram Protocol) is a non-reliable datagram protocol. In
  187. other words, applications communicating through UDP send and receive
  188. data as independent blocks, which are not guaranteed to reach the other
  189. end. Even when they do reach the other end, they are not guaranteed to be
  190. error free. Data transfers are atomic, one datagram at a time. Reading
  191. only part of a datagram discards the rest, so that the following read
  192. operation will act on the next datagram. The advantages are in
  193. simplicity (no connection setup) and performance (no error checking or
  194. error correction).
  195. </p>
  196. <p>
  197. Note that although no guarantees are made, these days
  198. networks are so good that, under normal circumstances, few errors
  199. happen in practice.
  200. </p>
  201. <p>
  202. An UDP socket object is created by the
  203. <a href=udp.html#udp><tt>socket.udp</tt></a> function. UDP
  204. sockets do not need to be connected before use. The method
  205. <a href=udp.html#sendto><tt>sendto</tt></a>
  206. can be used immediately after creation to
  207. send a datagram to IP address and port. Host names are not allowed
  208. because performing name resolution for each packet would be forbiddingly
  209. slow. Methods
  210. <a href=udp.html#receive><tt>receive</tt></a> and
  211. <a href=udp.html#receivefrom><tt>receivefrom</tt></a>
  212. can be used to retrieve datagrams, the latter returning the IP and port of
  213. the sender as extra return values (thus being slightly less
  214. efficient).
  215. </p>
  216. <p>
  217. When communication is performed repeatedly with a single peer, an
  218. application should call the
  219. <a href=udp.html#setpeername><tt>setpeername</tt></a> method to specify a
  220. permanent partner. Methods
  221. <a href=udp.html#sendto><tt>sendto</tt></a> and
  222. <a href=udp.html#receivefrom><tt>receivefrom</tt></a>
  223. can no longer be used, but the method
  224. <a href=udp.html#send><tt>send</tt></a> can be used to send data
  225. directly to the peer, and the method
  226. <a href=udp.html#receive><tt>receive</tt></a>
  227. will only return datagrams originating
  228. from that peer. There is about 30% performance gain due to this practice.
  229. </p>
  230. <p>
  231. To associate an UDP socket with a local address, an application calls the
  232. <a href=udp.html#setsockname><tt>setsockname</tt></a>
  233. method <em>before</em> sending any datagrams. Otherwise, the socket is
  234. automatically bound to an ephemeral address before the first data
  235. transmission and once bound the local address cannot be changed.
  236. The other methods available for UDP sockets are
  237. <a href=udp.html#getpeername><tt>getpeername</tt></a>,
  238. <a href=udp.html#getsockname><tt>getsockname</tt></a>,
  239. <a href=udp.html#settimeout><tt>settimeout</tt></a>,
  240. <a href=udp.html#setoption><tt>setoption</tt></a> and
  241. <a href=udp.html#close><tt>close</tt></a>.
  242. </p>
  243. <p>
  244. Example:
  245. </p>
  246. <blockquote>
  247. <p>
  248. A simple daytime client, using LuaSocket. The program connects to a remote
  249. server and tries to retrieve the daytime, printing the answer it got or an
  250. error message.
  251. </p>
  252. <pre class=example>
  253. -- change here to the host an port you want to contact
  254. local host, port = "localhost", 13
  255. -- load namespace
  256. local socket = require("socket")
  257. -- convert host name to ip address
  258. local ip = assert(socket.dns.toip(host))
  259. -- create a new UDP object
  260. local udp = assert(socket.udp())
  261. -- contact daytime host
  262. assert(udp:sendto("anything", ip, port))
  263. -- retrieve the answer and print results
  264. io.write(assert(udp:receive()))
  265. </pre>
  266. </blockquote>
  267. <!-- More +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  268. <h3 id=more>Support modules</h3>
  269. <p> Although not covered in the introduction, LuaSocket offers
  270. much more than TCP and UDP functionality. As the library
  271. evolved, support for <a href=http.html>HTTP</a>, <a href=ftp.html>FTP</a>,
  272. and <a href=smtp.html>SMTP</a> were built on top of these. These modules
  273. and many others are covered by the <a href=reference.html>reference manual</a>.
  274. </p>
  275. <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
  276. <div class=footer>
  277. <hr>
  278. <center>
  279. <p class=bar>
  280. <a href="home.html">home</a> &middot;
  281. <a href="home.html#down">download</a> &middot;
  282. <a href="installation.html">installation</a> &middot;
  283. <a href="introduction.html">introduction</a> &middot;
  284. <a href="reference.html">reference</a>
  285. </p>
  286. <p>
  287. <small>
  288. Last modified by Diego Nehab on <br>
  289. Thu Apr 20 00:25:36 EDT 2006
  290. </small>
  291. </p>
  292. </center>
  293. </div>
  294. </body>
  295. </html>