12 files changed, 1411 insertions, 6 deletions
diff --git a/docs/dns.html b/docs/dns.html
index 56ce3ba..e8320e8 100644
--- a/docs/dns.html
+++ b/docs/dns.html
@@ -106,6 +106,32 @@ the  resolver.  In  case of error, the function returns <b><tt>nil</tt></b>
 followed by an error message.
 </p>
+<!-- getnameinfo ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="getnameinfo">
+socket.dns.<b>getnameinfo(</b>[host] [, service]<b>)</b>
+</p>
+<p class="description">
+Resolves a host and/or a service name through the system resolver and
+returns their canonical name form. At least one of <tt>host</tt> or
+<tt>service</tt> must be given.
+</p>
+<p class="parameters">
+<tt>Host</tt> is an optional string with a host name or IP address.
+<tt>Service</tt> is an optional string with a service name or port number.
+</p>
+<p class="return">
+If <tt>host</tt> was given, returns a numerically-indexed table with the
+canonical host name found for each address the resolver returns for
+<tt>host</tt>. If <tt>service</tt> was also given, the canonical service
+name is returned as an additional value; if only <tt>service</tt> was
+given, its canonical name is returned by itself. In case of error, the
+function returns <b><tt>nil</tt></b> followed by an error message.
+</p>
 <!-- gethostname ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <p class="name" id="gethostname">
diff --git a/docs/http.html b/docs/http.html
index c6423ba..316cd2e 100644
--- a/docs/http.html
+++ b/docs/http.html
@@ -114,7 +114,11 @@ the HTTP module:
 <ul>
 <li> <tt>PROXY</tt>: default proxy used for connections;</li>
 <li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;</li>
-<li> <tt>USERAGENT</tt>: default user agent reported to server.</li>
+<li> <tt>USERAGENT</tt>: default user agent reported to server;</li>
+<li> <tt>MAXHEADERLINE</tt>: maximum length, in bytes, of a single response
+header line. Defaults to 8192;</li>
+<li> <tt>MAXHEADERSIZE</tt>: maximum total size, in bytes, of all response
+header lines combined. Defaults to 65536.</li>
 </ul>
 <p class="note">
@@ -183,7 +187,8 @@ pump step function used to move data.
 Defaults to the LTN12 <tt>pump.step</tt> function.</li>
 <li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;</li>
 <li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
-function from  automatically following 301 or 302 server redirect messages;</li>
+function from automatically following 301, 302, 303, 307 or 308 server
+redirect messages;</li>
 <li><tt>create</tt>: An optional function to be used instead of
 <a href="tcp.html#socket.tcp"><tt>socket.tcp</tt></a> when the communications socket is created.</li>
 <li><tt>maxredirects</tt>: An optional number specifying the maximum number of
diff --git a/docs/index.html b/docs/index.html
index 3341f8d..7a22dd6 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -67,6 +67,8 @@ In addition, you will find that the
 (anything you could possible want to do with one) and
 <a href="ltn12.html">LTN12</a>
 (filters, sinks, sources and pumps) modules can be very handy.
+On Unix-like platforms, dedicated <a href="unix.html">Unix domain socket</a>
+and <a href="serial.html">serial port</a> modules are also available.
 </p>
 <p>
diff --git a/docs/installation.html b/docs/installation.html
index b56f50f..bdc8b1d 100644
--- a/docs/installation.html
+++ b/docs/installation.html
@@ -57,7 +57,7 @@ luarocks install luasocket
   print(socket._VERSION)
    </code></pre>
-<p>If you see output like <strong>LuaSocket 3.0</strong>, the installation was successful.</p>
+<p>If you see output like <strong>LuaSocket 3.1.0</strong>, the installation was successful.</p>
 <h3>More Information</h3>
 <p>For more details, visit the <a href="https://github.com/lunarmodules/luasocket" target="_blank">LuaSocket GitHub repository</a>.</p>
diff --git a/docs/introduction.html b/docs/introduction.html
index 51443a0..bc0d535 100644
--- a/docs/introduction.html
+++ b/docs/introduction.html
@@ -304,7 +304,10 @@ io.write(assert(udp:receive()))
 <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 <a href=smtp.html>SMTP</a> were built on top of these. On Unix-like
+platforms, the library also ships separate <a href=unix.html>Unix domain
+socket</a> and <a href=serial.html>serial port</a> modules, requirable as
+<tt>socket.unix</tt> and <tt>socket.serial</tt>. These modules
 and many others are covered by the <a href=reference.html>reference manual</a>.
 </p>
diff --git a/docs/ltn12.html b/docs/ltn12.html
index 30bc564..76b3984 100644
--- a/docs/ltn12.html
+++ b/docs/ltn12.html
@@ -55,6 +55,20 @@ To obtain the <tt>ltn12</tt> namespace, run:
 local ltn12 = require("ltn12")
 </pre>
+<!-- BLOCKSIZE +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="BLOCKSIZE">
+ltn12.<b>BLOCKSIZE</b>
+</p>
+<p class="description">
+The default chunk size, in bytes, used internally by the built-in sources
+and sinks (e.g. <a href="#source.string"><tt>source.string</tt></a>,
+<a href="#source.file"><tt>source.file</tt></a>) when they have no more
+natural chunk size of their own. Defaults to 2048. Changing it affects
+only sources/sinks created after the change.
+</p>
 <!-- filters ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <h3 id="filter">Filters</h3>
@@ -415,6 +429,30 @@ ltn12.source.<b>table(</b>table<b>)</b>
 Creates and returns a source that produces the numerically-indexed values of a <tt>table</tt> successively beginning at 1.  The source returns nil (end-of-stream) whenever a nil value is produced by the current index, which proceeds forward regardless.
 </p>
+<!-- rewind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="source.rewind">
+ltn12.source.<b>rewind(</b>source<b>)</b>
+</p>
+<p class="description">
+Wraps a <em>fancy</em> <tt>source</tt> to add chunk pushback, so previously
+produced chunks can be fed back in for a later read to consume again.
+</p>
+<p class="parameters">
+<tt>Source</tt> is the fancy source being wrapped.
+</p>
+<p class="return">
+The function returns a new fancy source. Calling it with no arguments reads
+the next chunk as usual: any chunks previously pushed back are returned
+first (most recently pushed back, first), and once none remain it falls
+through to <tt>source</tt>. Calling it <em>with</em> a chunk argument does
+not read anything: it pushes that chunk back onto the internal stack for a
+future no-argument call to return.
+</p>
 <!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <div class="footer">
diff --git a/docs/reference.html b/docs/reference.html
index 2bc5f78..7425716 100644
--- a/docs/reference.html
+++ b/docs/reference.html
@@ -43,6 +43,7 @@ Support, Manual">
 <a href="dns.html">DNS (in socket)</a>
 <blockquote>
 <a href="dns.html#getaddrinfo">getaddrinfo</a>,
+<a href="dns.html#getnameinfo">getnameinfo</a>,
 <a href="dns.html#gethostname">gethostname</a>,
 <a href="dns.html#tohostname">tohostname</a>,
 <a href="dns.html#toip">toip</a>.
@@ -73,6 +74,9 @@ Support, Manual">
 <blockquote>
 <a href="ltn12.html">LTN12</a>
 <blockquote>
+<a href="ltn12.html#BLOCKSIZE">BLOCKSIZE</a>.
+</blockquote>
+<blockquote>
 <a href="ltn12.html#filter">filter</a>:
 <a href="ltn12.html#filter.chain">chain</a>,
 <a href="ltn12.html#filter.cycle">cycle</a>.
@@ -98,6 +102,7 @@ Support, Manual">
 <a href="ltn12.html#source.empty">empty</a>,
 <a href="ltn12.html#source.error">error</a>,
 <a href="ltn12.html#source.file">file</a>,
+<a href="ltn12.html#source.rewind">rewind</a>,
 <a href="ltn12.html#source.simplify">simplify</a>,
 <a href="ltn12.html#source.string">string</a>,
 <a href="ltn12.html#source.table">table</a>.
@@ -129,6 +134,23 @@ Support, Manual">
 </blockquote>
 </blockquote>
+<!-- serial +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<blockquote>
+<a href="serial.html">Serial</a>
+<blockquote>
+<a href="serial.html#close">close</a>,
+<a href="serial.html#getfd">getfd</a>,
+<a href="serial.html#getstats">getstats</a>,
+<a href="serial.html#receive">receive</a>,
+<a href="serial.html#send">send</a>,
+<a href="serial.html#setfd">setfd</a>,
+<a href="serial.html#setstats">setstats</a>,
+<a href="serial.html#settimeout">settimeout</a>,
+<a href="serial.html#socket.serial">socket.serial</a>.
+</blockquote>
+</blockquote>
 <!-- smtp +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <blockquote>
@@ -153,6 +175,7 @@ Support, Manual">
 <a href="dns.html#dns">dns</a>,
 <a href="socket.html#gettime">gettime</a>,
 <a href="socket.html#headers.canonic">headers.canonic</a>,
+<a href="socket.html#headers.setcanonic">headers.setcanonic</a>,
 <a href="socket.html#newtry">newtry</a>,
 <a href="socket.html#protect">protect</a>,
 <a href="socket.html#select">select</a>,
@@ -183,6 +206,7 @@ Support, Manual">
 <a href="tcp.html#close">close</a>,
 <a href="tcp.html#connect">connect</a>,
 <a href="tcp.html#dirty">dirty</a>,
+<a href="tcp.html#getfamily">getfamily</a>,
 <a href="tcp.html#getfd">getfd</a>,
 <a href="tcp.html#getoption">getoption</a>,
 <a href="tcp.html#getpeername">getpeername</a>,
@@ -194,6 +218,8 @@ Support, Manual">
 <a href="tcp.html#send">send</a>,
 <a href="tcp.html#setfd">setfd</a>,
 <a href="tcp.html#setoption">setoption</a>,
+<a href="tcp.html#setpeername">setpeername</a>,
+<a href="tcp.html#setsockname">setsockname</a>,
 <a href="tcp.html#setstats">setstats</a>,
 <a href="tcp.html#settimeout">settimeout</a>,
 <a href="tcp.html#shutdown">shutdown</a>.
@@ -206,6 +232,9 @@ Support, Manual">
 <a href="udp.html">UDP (in socket)</a>
 <blockquote>
 <a href="udp.html#close">close</a>,
+<a href="udp.html#dirty">dirty</a>,
+<a href="udp.html#getfamily">getfamily</a>,
+<a href="udp.html#getfd">getfd</a>,
 <a href="udp.html#getoption">getoption</a>,
 <a href="udp.html#getpeername">getpeername</a>,
 <a href="udp.html#getsockname">getsockname</a>,
@@ -214,6 +243,7 @@ Support, Manual">
 <a href="udp.html#receivefrom">receivefrom</a>,
 <a href="udp.html#send">send</a>,
 <a href="udp.html#sendto">sendto</a>,
+<a href="udp.html#setfd">setfd</a>,
 <a href="udp.html#setpeername">setpeername</a>,
 <a href="udp.html#setsockname">setsockname</a>,
 <a href="udp.html#setoption">setoption</a>,
@@ -221,6 +251,48 @@ Support, Manual">
 </blockquote>
 </blockquote>
+<!-- unix +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<blockquote>
+<a href="unix.html">Unix</a>
+<blockquote>
+<a href="unix.html#socket.unix.stream">socket.unix.stream</a>:
+<a href="unix.html#stream.accept">accept</a>,
+<a href="unix.html#stream.bind">bind</a>,
+<a href="unix.html#stream.close">close</a>,
+<a href="unix.html#stream.connect">connect</a>,
+<a href="unix.html#stream.dirty">dirty</a>,
+<a href="unix.html#stream.getfd">getfd</a>,
+<a href="unix.html#stream.getsockname">getsockname</a>,
+<a href="unix.html#stream.getstats">getstats</a>,
+<a href="unix.html#stream.listen">listen</a>,
+<a href="unix.html#stream.receive">receive</a>,
+<a href="unix.html#stream.send">send</a>,
+<a href="unix.html#stream.setfd">setfd</a>,
+<a href="unix.html#stream.setoption">setoption</a>,
+<a href="unix.html#stream.setstats">setstats</a>,
+<a href="unix.html#stream.settimeout">settimeout</a>,
+<a href="unix.html#stream.shutdown">shutdown</a>.
+</blockquote>
+<blockquote>
+<a href="unix.html#socket.unix.dgram">socket.unix.dgram</a>:
+<a href="unix.html#dgram.bind">bind</a>,
+<a href="unix.html#dgram.close">close</a>,
+<a href="unix.html#dgram.connect">connect</a>,
+<a href="unix.html#dgram.dirty">dirty</a>,
+<a href="unix.html#dgram.getfd">getfd</a>,
+<a href="unix.html#dgram.getsockname">getsockname</a>,
+<a href="unix.html#dgram.gettimeout">gettimeout</a>,
+<a href="unix.html#dgram.receive">receive</a>,
+<a href="unix.html#dgram.receivefrom">receivefrom</a>,
+<a href="unix.html#dgram.send">send</a>,
+<a href="unix.html#dgram.sendto">sendto</a>,
+<a href="unix.html#dgram.setfd">setfd</a>,
+<a href="unix.html#dgram.setoption">setoption</a>,
+<a href="unix.html#dgram.settimeout">settimeout</a>.
+</blockquote>
+</blockquote>
 <!-- url ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <blockquote>
diff --git a/docs/serial.html b/docs/serial.html
new file mode 100644
index 0000000..8e123b0
--- /dev/null
+++ b/docs/serial.html
@@ -0,0 +1,308 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<meta name="description" content="LuaSocket: Serial port support">
+<meta name="keywords" content="Lua, LuaSocket, Serial, Port, TTY, Library, Support">
+<title>LuaSocket: Serial port support</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> &middot;
+<a href="index.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>
+<!-- serial +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<h2 id="serial">Serial port support</h2>
+<p>
+The <tt>socket.serial</tt> module opens a serial device (e.g.
+<tt>/dev/ttyUSB0</tt>) and exposes it through the same buffered,
+timeout-aware <tt>send</tt>/<tt>receive</tt> interface used by
+<a href="tcp.html">TCP</a> and <a href="unix.html">Unix domain</a>
+stream objects.
+</p>
+<p class="note">
+Note: This module is only built on Unix-like platforms (Linux, macOS,
+BSD, Haiku). It is not available on Windows.
+</p>
+<p>
+Serial port support is a separate module that must be required
+explicitly. Unlike most other LuaSocket modules, it returns a
+<em>function</em> directly &mdash; the constructor &mdash; rather than a
+table of functions:
+</p>
+<pre class="example">
+-- loads the socket.serial module; note this is the constructor itself
+local serial_open = require("socket.serial")
+-- open the device
+local port = assert(serial_open("/dev/ttyUSB0"))
+port:settimeout(1)
+assert(port:send("AT\r\n"))
+print(port:receive())
+port:close()
+</pre>
+<p class="note">
+Note: <b>There is currently no API to configure the serial line itself
+&mdash; baud rate, parity, data/stop bits or flow control.</b> The device
+is opened non-blocking with whatever settings the OS driver or a prior
+external configuration (e.g. <tt>stty</tt>) left it in. This is a known
+current limitation of the module, not a deliberate protection against
+misuse; a future version may add a <tt>setoption</tt>-style API for these
+settings the way <a href="tcp.html#setoption"><tt>tcp:setoption</tt></a>
+does for TCP.
+</p>
+<p>
+Until such an API exists, the workaround is to configure the line with
+the platform's own <tt>stty</tt> utility (via <tt>os.execute</tt>)
+<em>before</em> opening the device with <tt>socket.serial</tt>:
+</p>
+<pre class="example">
+local serial_open = require("socket.serial")
+local dev = "/dev/ttyUSB0"
+-- Linux: stty -F &lt;device&gt; ...
+local ok = os.execute(string.format(
+    "stty -F %s 115200 cs8 -cstopb -parenb raw -echo", dev))
+-- macOS/BSD use -f instead of -F:
+-- os.execute(string.format("stty -f %s 115200 cs8 -cstopb -parenb raw -echo", dev))
+assert(ok, "failed to configure serial line with stty")
+local port = assert(serial_open(dev))
+port:settimeout(1)
+assert(port:send("AT\r\n"))
+print(port:receive())
+port:close()
+</pre>
+<p class="note">
+Note: <tt>raw -echo</tt> puts the line in raw mode, which matters for
+LuaSocket's framing: without it, the TTY driver applies its own line
+editing/echo, which can interfere with <a href="#receive"><tt>receive</tt></a>
+patterns and <a href="#send"><tt>send</tt></a> content. Adjust the
+<tt>stty</tt> flags (baud rate, parity, stop bits, flow control) to match
+your device; consult <tt>man stty</tt> for the full option set on your
+platform, since flag names and defaults vary between Linux, macOS and the
+BSDs.
+</p>
+<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="close">
+port:<b>close()</b>
+</p>
+<p class="description">
+Closes a serial object. No further operations (except further calls to
+<tt>close</tt>) are allowed on a closed object.
+</p>
+<p class="note">
+Note: Garbage-collected objects are automatically closed before
+destruction.
+</p>
+<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dirty">
+port:<b>dirty()</b>
+</p>
+<p class="description">
+Check the read buffer status.
+</p>
+<p class="return">
+Returns <tt>true</tt> if there is any data in the read buffer,
+<tt>false</tt> otherwise.
+</p>
+<p class="note">
+Note: <b>This is an internal method, use at your own risk.</b>
+</p>
+<!-- getfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="getfd">
+port:<b>getfd()</b>
+</p>
+<p class="description">
+Returns the underlying file descriptor associated to the object.
+</p>
+<p class="return">
+The descriptor.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be portable. Use at your
+own risk.</b>
+</p>
+<!-- getstats ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="getstats">
+port:<b>getstats()</b>
+</p>
+<p class="description">
+Returns accounting information on the port, useful for throttling of
+bandwidth. Works exactly like
+<a href="tcp.html#getstats"><tt>tcp:getstats</tt></a>.
+</p>
+<p class="return">
+The method returns the number of bytes received, the number of bytes
+sent, and the age of the object in seconds.
+</p>
+<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="receive">
+port:<b>receive(</b>[pattern [, prefix [, maxsize]]]<b>)</b>
+</p>
+<p class="description">
+Reads data from the serial port, according to the specified <em>read
+pattern</em>. Works exactly like
+<a href="tcp.html#receive"><tt>tcp:receive</tt></a>, including the
+<tt>*a</tt>/<tt>*l</tt>/<tt>number</tt> patterns and the
+<tt>prefix</tt>/<tt>maxsize</tt> parameters.
+</p>
+<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="send">
+port:<b>send(</b>data [, i [, j]]<b>)</b>
+</p>
+<p class="description">
+Sends <tt>data</tt> through the serial port. Works exactly like
+<a href="tcp.html#send"><tt>tcp:send</tt></a>, including the optional
+<tt>i</tt>/<tt>j</tt> substring selection.
+</p>
+<!-- setfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="setfd">
+port:<b>setfd(</b>fd<b>)</b>
+</p>
+<p class="description">
+Sets the underlying file descriptor associated to the object. The current
+one is simply replaced, not closed, and no other change to the object
+state is made.
+</p>
+<p class="return">
+No return value.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be portable. Use at your
+own risk.</b>
+</p>
+<!-- setstats ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="setstats">
+port:<b>setstats(</b>received, sent, age<b>)</b>
+</p>
+<p class="description">
+Resets accounting information on the port, useful for throttling of
+bandwidth. Works exactly like
+<a href="tcp.html#setstats"><tt>tcp:setstats</tt></a>.
+</p>
+<p class="return">
+The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
+</p>
+<!-- settimeout ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="settimeout">
+port:<b>settimeout(</b>value [, mode]<b>)</b>
+</p>
+<p class="description">
+Changes the timeout values for the object. Works exactly like
+<a href="tcp.html#settimeout"><tt>tcp:settimeout</tt></a>, including the
+'<tt>b</tt>' (block) and '<tt>t</tt>' (total) modes.
+</p>
+<!-- socket.serial +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="socket.serial">
+serial_open(<b>path</b>)
+</p>
+<p class="description">
+Opens the serial device at <tt>path</tt> and returns a serial object.
+This is the value returned directly by <tt>require("socket.serial")</tt>
+&mdash; there is no separate module table to index into, unlike
+<tt>socket.unix.stream()</tt> or <tt>socket.tcp()</tt>.
+</p>
+<p class="parameters">
+<tt>Path</tt> is a string with the device path (e.g.
+<tt>"/dev/ttyUSB0"</tt> or <tt>"/dev/ttyS0"</tt>).
+</p>
+<p class="return">
+In case of success, a new serial object is returned. In case of error,
+the function returns <b><tt>nil</tt></b>, followed by an error message,
+followed by the numeric <tt>errno</tt> value.
+</p>
+<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<div class="footer">
+<hr>
+<center>
+<p class="bar">
+<a href="index.html">home</a> &middot;
+<a href="index.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>
+</div>
+</body>
+</html>
diff --git a/docs/socket.html b/docs/socket.html
index 570f6d5..de43135 100644
--- a/docs/socket.html
+++ b/docs/socket.html
@@ -51,6 +51,14 @@ To obtain the <tt>socket</tt> namespace, run:
 local socket = require("socket")
 </pre>
+<p>
+Two related transports are shipped as separate modules, loaded on demand
+with their own <tt>require</tt> call: <a href="unix.html">Unix domain
+sockets</a> (<tt>require("socket.unix")</tt>) and
+<a href="serial.html">serial ports</a> (<tt>require("socket.serial")</tt>).
+Both are only built on Unix-like platforms.
+</p>
 <!-- headers.canonic ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <p class="name" id="headers.canonic">
@@ -94,6 +102,27 @@ local headers = require("socket.headers")
 headers.setcanonic("X-Request-ID")
 </pre>
+<!-- headers.setcanonic +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="headers.setcanonic">
+socket.headers.<b>setcanonic(</b>name<b>)</b>
+</p>
+<p class="description">
+Registers a custom canonic capitalization for a header field name in
+<a href="#headers.canonic"><tt>socket.headers.canonic</tt></a>, for use
+when the automatic capitalize-first-letter-of-each-word rule would not
+reproduce it (e.g. an all-caps acronym).
+</p>
+<p class="parameters">
+<tt>Name</tt> is a string with the header field name in its desired
+canonic capitalization (e.g. <tt>"X-Request-ID"</tt>).
+</p>
+<p class="return">
+No return value.
+</p>
 <!-- bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
diff --git a/docs/tcp.html b/docs/tcp.html
index 715d28f..580bdcf 100644
--- a/docs/tcp.html
+++ b/docs/tcp.html
@@ -196,6 +196,25 @@ Note: <b>This is an internal method, use at your own risk.</b>
 </p>
+<!-- getfamily +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="getfamily">
+master:<b>getfamily()</b><br>
+client:<b>getfamily()</b><br>
+server:<b>getfamily()</b>
+</p>
+<p class="description">
+Returns the family of the underlying socket, as chosen when the object was
+created by <a href="socket.html#connect"><tt>socket.tcp</tt></a>,
+<a href="#socket.tcp4"><tt>socket.tcp4</tt></a> or
+<a href="#socket.tcp6"><tt>socket.tcp6</tt></a>.
+</p>
+<p class="return">
+The string "<tt>inet4</tt>" or "<tt>inet6</tt>".
+</p>
 <!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <p class="name" id="getfd">
@@ -651,6 +670,30 @@ This is the default mode;</li>
 This function returns 1.
 </p>
+<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="setpeername">
+master:<b>setpeername(</b>address, port<b>)</b>
+</p>
+<p class="description">
+Alias for <a href="#connect"><tt>connect</tt></a>, kept for naming symmetry
+with <a href="udp.html#setpeername"><tt>udp:setpeername</tt></a> and with
+<a href="#getpeername"><tt>getpeername</tt></a>.
+</p>
+<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="setsockname">
+master:<b>setsockname(</b>address, port<b>)</b>
+</p>
+<p class="description">
+Alias for <a href="#bind"><tt>bind</tt></a>, kept for naming symmetry
+with <a href="udp.html#setsockname"><tt>udp:setsockname</tt></a> and with
+<a href="#getsockname"><tt>getsockname</tt></a>.
+</p>
 <!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <p class="name" id="setfd">
diff --git a/docs/udp.html b/docs/udp.html
index 8d807a4..d2c169a 100644
--- a/docs/udp.html
+++ b/docs/udp.html
@@ -62,6 +62,66 @@ Garbage-collected objects are automatically closed before
 destruction, though.
 </p>
+<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dirty">
+connected:<b>dirty()</b><br>
+unconnected:<b>dirty()</b>
+</p>
+<p class="description">
+Check the read buffer status.
+</p>
+<p class="return">
+Returns <tt>false</tt>. UDP objects do not keep a read buffer, so this
+always reports no buffered data.
+</p>
+<p class="note">
+Note: <b>This is an internal method, use at your own risk.</b>
+</p>
+<!-- getfamily +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="getfamily">
+connected:<b>getfamily()</b><br>
+unconnected:<b>getfamily()</b>
+</p>
+<p class="description">
+Returns the family of the underlying socket, as chosen when the object was
+created by <a href="#socket.udp"><tt>socket.udp</tt></a>,
+<a href="#socket.udp4"><tt>socket.udp4</tt></a> or
+<a href="#socket.udp6"><tt>socket.udp6</tt></a>.
+</p>
+<p class="return">
+The string "<tt>inet4</tt>" or "<tt>inet6</tt>".
+</p>
+<!-- getfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="getfd">
+connected:<b>getfd()</b><br>
+unconnected:<b>getfd()</b>
+</p>
+<p class="description">
+Returns the underling socket descriptor or handle associated to the object.
+</p>
+<p class="return">
+The descriptor or handle. In case the object has been closed, the return value
+will be -1. For an invalid socket it will be <a href="socket.html#socketinvalid">
+<tt>_SOCKETINVALID</tt></a>.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be
+portable. Use at your own risk. </b>
+</p>
 <!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <p class="name" id="getoption">
@@ -321,8 +381,10 @@ Sets the unicast hop limit (the IPv6 equivalent of the IPv4 TTL)
 for outgoing packets.
 Receives a number;</li>
 <li> '<tt>ipv6-multicast-hops</tt>':
-Sets the hop limit for outgoing IPv6 multicast datagrams.
+<b>Known limitation:</b> this option is currently wired to the same
-Receives a number;</li>
+underlying setting as <tt>ipv6-unicast-hops</tt> instead of a separate
+multicast hop limit, so getting or setting one also gets or sets the
+other. Receives a number;</li>
 <li> '<tt>ipv6-multicast-loop</tt>':
 Specifies whether or not a copy of an outgoing IPv6 multicast
 datagram is delivered to the sending host as long as it is a
@@ -374,6 +436,28 @@ Note: The descriptions above come from the man pages.
 </p>
+<!-- setfd +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="setfd">
+connected:<b>setfd(</b>fd<b>)</b><br>
+unconnected:<b>setfd(</b>fd<b>)</b>
+</p>
+<p class="description">
+Sets the underling socket descriptor or handle associated to the object. The current one
+is simply replaced, not closed, and no other change to the object state is made.
+To set it as invalid use <a href="socket.html#socketinvalid"><tt>_SOCKETINVALID</tt></a>.
+</p>
+<p class="return">
+No return value.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be
+portable. Use at your own risk. </b>
+</p>
 <!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
 <p class="name" id="setpeername">
diff --git a/docs/unix.html b/docs/unix.html
new file mode 100644
index 0000000..de71925
--- /dev/null
+++ b/docs/unix.html
@@ -0,0 +1,795 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<meta name="description" content="LuaSocket: Unix domain socket support">
+<meta name="keywords" content="Lua, LuaSocket, Socket, Unix, Domain, IPC, Library, Support">
+<title>LuaSocket: Unix domain socket support</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> &middot;
+<a href="index.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>
+<!-- unix ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<h2 id="unix">Unix domain sockets</h2>
+<p>
+Unix domain sockets provide inter-process communication between processes
+on the same host, addressed by a path in the file system rather than by an
+IP address and port. LuaSocket supports both the stream (connection
+oriented, like TCP) and datagram (connectionless, like UDP) flavors.
+</p>
+<p class="note">
+Note: This module is only built on Unix-like platforms (Linux, macOS,
+BSD, Haiku). It is not available on Windows.
+</p>
+<p>
+Unlike the core <tt>socket</tt> namespace, Unix domain socket support is a
+separate module that must be required explicitly:
+</p>
+<pre class="example">
+-- loads the socket.unix module
+local unix = require("socket.unix")
+</pre>
+<p>
+The module table returned by <tt>require("socket.unix")</tt> exposes two
+constructors, <a href="#socket.unix.stream"><tt>unix.stream()</tt></a> and
+<a href="#socket.unix.dgram"><tt>unix.dgram()</tt></a>. For backwards
+compatibility, <tt>unix.tcp</tt> and <tt>unix.udp</tt> are aliases for
+<tt>stream</tt> and <tt>dgram</tt> respectively, and the module table
+itself can be called directly as a shortcut for <tt>unix.stream()</tt>
+(i.e. <tt>unix()</tt> is the same as <tt>unix.stream()</tt>).
+</p>
+<p class="note">
+Note: Paths passed to <a href="#stream.bind"><tt>bind</tt></a>,
+<a href="#stream.connect"><tt>connect</tt></a> and their datagram
+equivalents are limited by the platform's <tt>sun_path</tt> buffer size
+(commonly around 100&ndash;108 bytes). A path that does not fit returns
+<b><tt>nil</tt></b> followed by the error message '<tt>path too
+long</tt>'.
+</p>
+<!-- stream ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<h3 id="stream">Stream (<tt>socket.unix.stream</tt>)</h3>
+<p>
+Stream Unix domain sockets behave like TCP sockets (see
+<a href="tcp.html">TCP</a>): a freshly created object is a <em>master</em>
+object, which becomes a <em>client</em> object after a successful
+<a href="#stream.connect"><tt>connect</tt></a>, or a <em>server</em>
+object after a successful <a href="#stream.listen"><tt>listen</tt></a>
+(itself normally preceded by <a href="#stream.bind"><tt>bind</tt></a>).
+Server objects produce client objects via
+<a href="#stream.accept"><tt>accept</tt></a>. Most methods below work the
+same way as their TCP counterparts, just addressed by path instead of
+IP/port.
+</p>
+<!-- stream.accept ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.accept">
+server:<b>accept()</b>
+</p>
+<p class="description">
+Waits for a remote connection on the server object and returns a client
+object representing that connection. Works exactly like
+<a href="tcp.html#accept"><tt>tcp:accept</tt></a>.
+</p>
+<p class="return">
+If a connection is successfully accepted, a client object is returned. If a
+timeout condition is met, the method returns <b><tt>nil</tt></b> followed
+by the error string '<tt>timeout</tt>'. Other errors are reported by
+<b><tt>nil</tt></b> followed by a message describing the error.
+</p>
+<!-- stream.bind ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.bind">
+master:<b>bind(</b>path<b>)</b><br>
+master:<b>setsockname(</b>path<b>)</b>
+</p>
+<p class="description">
+Binds a master object to a file system <tt>path</tt>. <tt>setsockname</tt>
+is an alias for <tt>bind</tt>.
+</p>
+<p class="parameters">
+<tt>Path</tt> is a string with the file system path to bind to. The path
+must not already exist as a socket file &mdash; remove any stale socket
+file left over from a previous run before binding.
+</p>
+<p class="return">
+In case of success, the method returns 1. In case of error, the method
+returns <b><tt>nil</tt></b> followed by an error message.
+</p>
+<!-- stream.close +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.close">
+master:<b>close()</b><br>
+client:<b>close()</b><br>
+server:<b>close()</b>
+</p>
+<p class="description">
+Closes a stream Unix domain object. The internal socket used by the object
+is closed. No further operations (except further calls to
+<tt>close</tt>) are allowed on a closed socket.
+</p>
+<p class="note">
+Note: Closing a socket does not remove the bound path from the file
+system. Delete the socket file yourself (e.g. <tt>os.remove(path)</tt>)
+once the server is done with it.
+</p>
+<p class="note">
+Note: Garbage-collected objects are automatically closed before
+destruction.
+</p>
+<!-- stream.connect +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.connect">
+master:<b>connect(</b>path<b>)</b><br>
+master:<b>setpeername(</b>path<b>)</b>
+</p>
+<p class="description">
+Attempts to connect a master object to <tt>path</tt>, transforming it
+into a client object. <tt>setpeername</tt> is an alias for
+<tt>connect</tt>. Client objects support
+<a href="#stream.send"><tt>send</tt></a>,
+<a href="#stream.receive"><tt>receive</tt></a>,
+<a href="#stream.getsockname"><tt>getsockname</tt></a>,
+<a href="#stream.settimeout"><tt>settimeout</tt></a>,
+<a href="#stream.shutdown"><tt>shutdown</tt></a>, and
+<a href="#stream.close"><tt>close</tt></a>.
+</p>
+<p class="parameters">
+<tt>Path</tt> is a string with the file system path of a listening server
+object.
+</p>
+<p class="return">
+In case of error, the method returns <b><tt>nil</tt></b> followed by a
+string describing the error. In case of success, the method returns 1.
+</p>
+<!-- stream.dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.dirty">
+master:<b>dirty()</b><br>
+client:<b>dirty()</b><br>
+server:<b>dirty()</b>
+</p>
+<p class="description">
+Check the read buffer status.
+</p>
+<p class="return">
+Returns <tt>true</tt> if there is any data in the read buffer,
+<tt>false</tt> otherwise.
+</p>
+<p class="note">
+Note: <b>This is an internal method, use at your own risk.</b>
+</p>
+<!-- stream.getfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.getfd">
+master:<b>getfd()</b><br>
+client:<b>getfd()</b><br>
+server:<b>getfd()</b>
+</p>
+<p class="description">
+Returns the underlying socket descriptor or handle associated to the
+object.
+</p>
+<p class="return">
+The descriptor or handle.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be portable. Use at your
+own risk.</b>
+</p>
+<!-- stream.getsockname +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.getsockname">
+master:<b>getsockname()</b><br>
+client:<b>getsockname()</b><br>
+server:<b>getsockname()</b>
+</p>
+<p class="description">
+Returns the local path the object is bound to.
+</p>
+<p class="return">
+The method returns a string with the local path. In case of error, the
+method returns <b><tt>nil</tt></b>.
+</p>
+<!-- stream.getstats +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.getstats">
+master:<b>getstats()</b><br>
+client:<b>getstats()</b><br>
+server:<b>getstats()</b>
+</p>
+<p class="description">
+Returns accounting information on the socket, useful for throttling of
+bandwidth. Works exactly like <a href="tcp.html#getstats"><tt>tcp:getstats</tt></a>.
+</p>
+<p class="return">
+The method returns the number of bytes received, the number of bytes
+sent, and the age of the socket object in seconds.
+</p>
+<!-- stream.listen ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.listen">
+master:<b>listen(</b>[backlog]<b>)</b>
+</p>
+<p class="description">
+Specifies the socket is willing to receive connections, transforming the
+object into a server object. Server objects support
+<a href="#stream.accept"><tt>accept</tt></a>,
+<a href="#stream.getsockname"><tt>getsockname</tt></a>,
+<a href="#stream.setoption"><tt>setoption</tt></a>,
+<a href="#stream.settimeout"><tt>settimeout</tt></a>, and
+<a href="#stream.close"><tt>close</tt></a>.
+</p>
+<p class="parameters">
+The optional <tt>backlog</tt> parameter specifies the number of client
+connections that can be queued waiting for service. Defaults to 32.
+</p>
+<p class="return">
+In case of success, the method returns 1. In case of error, the method
+returns <b><tt>nil</tt></b> followed by an error message.
+</p>
+<!-- stream.receive +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.receive">
+client:<b>receive(</b>[pattern [, prefix [, maxsize]]]<b>)</b>
+</p>
+<p class="description">
+Reads data from a client object. Works exactly like
+<a href="tcp.html#receive"><tt>tcp:receive</tt></a>, including the
+<tt>*a</tt>/<tt>*l</tt>/<tt>number</tt> patterns and the
+<tt>prefix</tt>/<tt>maxsize</tt> parameters.
+</p>
+<!-- stream.send +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.send">
+client:<b>send(</b>data [, i [, j]]<b>)</b>
+</p>
+<p class="description">
+Sends <tt>data</tt> through a client object. Works exactly like
+<a href="tcp.html#send"><tt>tcp:send</tt></a>, including the optional
+<tt>i</tt>/<tt>j</tt> substring selection.
+</p>
+<!-- stream.setfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.setfd">
+master:<b>setfd(</b>fd<b>)</b><br>
+client:<b>setfd(</b>fd<b>)</b><br>
+server:<b>setfd(</b>fd<b>)</b>
+</p>
+<p class="description">
+Sets the underlying socket descriptor or handle associated to the object.
+The current one is simply replaced, not closed, and no other change to
+the object state is made.
+</p>
+<p class="return">
+No return value.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be portable. Use at your
+own risk.</b>
+</p>
+<!-- stream.setoption +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.setoption">
+client:<b>setoption(</b>option [, value]<b>)</b><br>
+server:<b>setoption(</b>option [, value]<b>)</b>
+</p>
+<p class="description">
+Sets options for the stream object. Options are only needed by low-level
+or time-critical applications. You should only modify an option if you
+are sure you need it.
+</p>
+<p class="parameters">
+<tt>Option</tt> is a string with the option name, and <tt>value</tt>
+depends on the option being set:
+</p>
+<ul>
+<li> '<tt>keepalive</tt>': Setting this option to <tt>true</tt> enables
+the periodic transmission of messages on a connected socket. See
+<a href="tcp.html#setoption"><tt>tcp:setoption</tt></a> for details;</li>
+<li> '<tt>reuseaddr</tt>': Setting this option indicates that the rules
+used in validating addresses supplied in a call to
+<a href="#stream.bind"><tt>bind</tt></a> should allow reuse of local
+addresses;</li>
+<li> '<tt>linger</tt>': Controls the action taken when unsent data are
+queued on a socket and a close is performed. See
+<a href="tcp.html#setoption"><tt>tcp:setoption</tt></a> for the full
+description of the <tt>on</tt>/<tt>timeout</tt> value table.</li>
+</ul>
+<p class="return">
+The method returns 1 in case of success, or <b><tt>nil</tt></b> followed
+by an error message otherwise.
+</p>
+<!-- stream.setstats +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.setstats">
+master:<b>setstats(</b>received, sent, age<b>)</b><br>
+client:<b>setstats(</b>received, sent, age<b>)</b><br>
+server:<b>setstats(</b>received, sent, age<b>)</b>
+</p>
+<p class="description">
+Resets accounting information on the socket, useful for throttling of
+bandwidth. Works exactly like
+<a href="tcp.html#setstats"><tt>tcp:setstats</tt></a>.
+</p>
+<p class="return">
+The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
+</p>
+<!-- stream.settimeout +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.settimeout">
+master:<b>settimeout(</b>value [, mode]<b>)</b><br>
+client:<b>settimeout(</b>value [, mode]<b>)</b><br>
+server:<b>settimeout(</b>value [, mode]<b>)</b>
+</p>
+<p class="description">
+Changes the timeout values for the object. Works exactly like
+<a href="tcp.html#settimeout"><tt>tcp:settimeout</tt></a>, including the
+'<tt>b</tt>' (block) and '<tt>t</tt>' (total) modes.
+</p>
+<!-- stream.shutdown ++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="stream.shutdown">
+client:<b>shutdown(</b>[mode]<b>)</b>
+</p>
+<p class="description">
+Shuts down part of a full-duplex connection. Works exactly like
+<a href="tcp.html#shutdown"><tt>tcp:shutdown</tt></a>.
+</p>
+<p class="parameters">
+<tt>Mode</tt> can be "<tt>both</tt>" (default), "<tt>send</tt>" or
+"<tt>receive</tt>".
+</p>
+<p class="return">
+This function returns 1.
+</p>
+<!-- socket.unix.stream +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="socket.unix.stream">
+unix.<b>stream()</b>
+</p>
+<p class="description">
+Creates and returns a stream Unix domain master object. A master object
+can be transformed into a server object with
+<a href="#stream.listen"><tt>listen</tt></a> (after a call to
+<a href="#stream.bind"><tt>bind</tt></a>) or into a client object with
+<a href="#stream.connect"><tt>connect</tt></a>. The only other method
+supported by a master object is <a href="#stream.close"><tt>close</tt></a>.
+</p>
+<p class="return">
+In case of success, a new master object is returned. In case of error,
+<b><tt>nil</tt></b> is returned, followed by an error message.
+</p>
+<!-- dgram +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<h3 id="dgram">Datagram (<tt>socket.unix.dgram</tt>)</h3>
+<p>
+Datagram Unix domain sockets behave like UDP sockets (see
+<a href="udp.html">UDP</a>): a socket starts out unconnected, and can
+optionally be turned into a connected socket with
+<a href="#dgram.connect"><tt>connect</tt></a> for repeated exchanges with
+a single peer.
+</p>
+<!-- dgram.bind +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.bind">
+unconnected:<b>bind(</b>path<b>)</b><br>
+unconnected:<b>setsockname(</b>path<b>)</b>
+</p>
+<p class="description">
+Binds the datagram object to a local file system <tt>path</tt>.
+<tt>setsockname</tt> is an alias for <tt>bind</tt>. Binding is only
+required if you want other processes to be able to
+<a href="#dgram.sendto"><tt>sendto</tt></a> this object; it is not
+required to <a href="#dgram.sendto"><tt>sendto</tt></a> or
+<a href="#dgram.connect"><tt>connect</tt></a> from it.
+</p>
+<p class="return">
+In case of success, the method returns 1. In case of error, the method
+returns <b><tt>nil</tt></b> followed by an error message.
+</p>
+<!-- dgram.close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.close">
+connected:<b>close()</b><br>
+unconnected:<b>close()</b>
+</p>
+<p class="description">
+Closes a datagram Unix domain object.
+</p>
+<p class="note">
+Note: Closing a socket does not remove the bound path from the file
+system. Delete the socket file yourself (e.g. <tt>os.remove(path)</tt>)
+once you are done with it.
+</p>
+<p class="note">
+Note: Garbage-collected objects are automatically closed before
+destruction.
+</p>
+<!-- dgram.connect ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.connect">
+connected:<b>connect(</b>path<b>)</b><br>
+unconnected:<b>connect(</b>path<b>)</b><br>
+connected:<b>setpeername(</b>path<b>)</b><br>
+unconnected:<b>setpeername(</b>path<b>)</b>
+</p>
+<p class="description">
+Sets (or changes) the peer of a datagram object, turning an unconnected
+object into a connected one. <tt>setpeername</tt> is an alias for
+<tt>connect</tt>.
+</p>
+<p class="parameters">
+<tt>Path</tt> is a string with the file system path of the peer.
+</p>
+<p class="return">
+In case of error, the method returns <b><tt>nil</tt></b> followed by an
+error message. In case of success, the method returns 1.
+</p>
+<p class="note">
+Note: Unlike <a href="udp.html#setpeername"><tt>udp:setpeername</tt></a>,
+there is no '<tt>*</tt>' path to dissolve the peer association back to an
+unconnected socket.
+</p>
+<!-- dgram.dirty ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.dirty">
+connected:<b>dirty()</b><br>
+unconnected:<b>dirty()</b>
+</p>
+<p class="description">
+Check the read buffer status.
+</p>
+<p class="return">
+Always returns <tt>false</tt>. Datagram objects do not keep a read
+buffer.
+</p>
+<p class="note">
+Note: <b>This is an internal method, use at your own risk.</b>
+</p>
+<!-- dgram.getfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.getfd">
+connected:<b>getfd()</b><br>
+unconnected:<b>getfd()</b>
+</p>
+<p class="description">
+Returns the underlying socket descriptor or handle associated to the
+object.
+</p>
+<p class="return">
+The descriptor or handle.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be portable. Use at your
+own risk.</b>
+</p>
+<!-- dgram.getsockname +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.getsockname">
+connected:<b>getsockname()</b><br>
+unconnected:<b>getsockname()</b>
+</p>
+<p class="description">
+Returns the local path the object is bound to.
+</p>
+<p class="return">
+The method returns a string with the local path. In case of error, the
+method returns <b><tt>nil</tt></b>.
+</p>
+<!-- dgram.gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.gettimeout">
+connected:<b>gettimeout()</b><br>
+unconnected:<b>gettimeout()</b>
+</p>
+<p class="description">
+Returns the current timeout value.
+</p>
+<!-- dgram.receive +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.receive">
+connected:<b>receive(</b>[size]<b>)</b><br>
+unconnected:<b>receive(</b>[size]<b>)</b>
+</p>
+<p class="description">
+Receives a datagram from the object. If the object is connected, only
+datagrams coming from the peer are accepted.
+</p>
+<p class="parameters">
+The optional <tt>size</tt> parameter specifies the maximum size of the
+datagram to be retrieved (defaults to 8192 bytes).
+</p>
+<p class="return">
+In case of success, the method returns the received datagram, which may
+be the empty string (a valid zero-length datagram, not end-of-stream). In
+case of timeout, the method returns <b><tt>nil</tt></b> followed by the
+string '<tt>timeout</tt>'.
+</p>
+<!-- dgram.receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.receivefrom">
+unconnected:<b>receivefrom(</b>[size]<b>)</b>
+</p>
+<p class="description">
+Works exactly as <a href="#dgram.receive"><tt>receive</tt></a>, except it
+also returns the sender's path as a second return value.
+</p>
+<p class="return">
+In case of success, the method returns the received datagram followed by
+the sender's path (the empty string if the sender's socket was not
+bound). In case of timeout, the method returns <b><tt>nil</tt></b>
+followed by the string '<tt>timeout</tt>'.
+</p>
+<!-- dgram.send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.send">
+connected:<b>send(</b>datagram<b>)</b>
+</p>
+<p class="description">
+Sends a datagram to the peer of a connected object.
+</p>
+<p class="return">
+If successful, the method returns the number of bytes sent. In case of
+error, the method returns <b><tt>nil</tt></b> followed by an error
+message (the string '<tt>refused</tt>' if the peer's socket is not
+accepting datagrams).
+</p>
+<!-- dgram.sendto +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.sendto">
+unconnected:<b>sendto(</b>datagram, path<b>)</b>
+</p>
+<p class="description">
+Sends a datagram to the object bound to <tt>path</tt>.
+</p>
+<p class="parameters">
+<tt>Datagram</tt> is a string with the datagram contents. <tt>Path</tt>
+is the file system path of the recipient.
+</p>
+<p class="return">
+If successful, the method returns the number of bytes sent. In case of
+error, the method returns <b><tt>nil</tt></b> followed by an error
+message (the string '<tt>refused</tt>' if the recipient's socket is not
+accepting datagrams).
+</p>
+<!-- dgram.setfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.setfd">
+connected:<b>setfd(</b>fd<b>)</b><br>
+unconnected:<b>setfd(</b>fd<b>)</b>
+</p>
+<p class="description">
+Sets the underlying socket descriptor or handle associated to the object.
+</p>
+<p class="return">
+No return value.
+</p>
+<p class="note">
+Note: <b>This is an internal method. Unlikely to be portable. Use at your
+own risk.</b>
+</p>
+<!-- dgram.setoption +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.setoption">
+connected:<b>setoption(</b>option [, value]<b>)</b><br>
+unconnected:<b>setoption(</b>option [, value]<b>)</b>
+</p>
+<p class="description">
+Sets options for the datagram object.
+</p>
+<p class="parameters">
+<tt>Option</tt> is a string with the option name:
+</p>
+<ul>
+<li> '<tt>reuseaddr</tt>': Indicates that the rules used in validating
+addresses supplied in a <a href="#dgram.bind"><tt>bind</tt></a> call
+should allow reuse of local addresses. Receives a boolean value.</li>
+</ul>
+<p class="return">
+The method returns 1 in case of success, or <b><tt>nil</tt></b> followed
+by an error message otherwise.
+</p>
+<!-- dgram.settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="dgram.settimeout">
+connected:<b>settimeout(</b>value<b>)</b><br>
+unconnected:<b>settimeout(</b>value<b>)</b>
+</p>
+<p class="description">
+Changes the timeout value for the object. Works like
+<a href="udp.html#settimeout"><tt>udp:settimeout</tt></a>: since
+<a href="#dgram.send"><tt>send</tt></a> and
+<a href="#dgram.sendto"><tt>sendto</tt></a> never block, this only
+affects <a href="#dgram.receive"><tt>receive</tt></a> and
+<a href="#dgram.receivefrom"><tt>receivefrom</tt></a>.
+</p>
+<!-- socket.unix.dgram +++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<p class="name" id="socket.unix.dgram">
+unix.<b>dgram()</b>
+</p>
+<p class="description">
+Creates and returns an unconnected datagram Unix domain object.
+Unconnected objects support
+<a href="#dgram.sendto"><tt>sendto</tt></a>,
+<a href="#dgram.receive"><tt>receive</tt></a>,
+<a href="#dgram.receivefrom"><tt>receivefrom</tt></a>,
+<a href="#dgram.getsockname"><tt>getsockname</tt></a>,
+<a href="#dgram.setoption"><tt>setoption</tt></a>,
+<a href="#dgram.settimeout"><tt>settimeout</tt></a>,
+<a href="#dgram.connect"><tt>connect</tt></a>, and
+<a href="#dgram.close"><tt>close</tt></a>. Use
+<a href="#dgram.connect"><tt>connect</tt></a> to turn the object into a
+connected object.
+</p>
+<p class="return">
+In case of success, a new unconnected datagram object is returned. In
+case of error, <b><tt>nil</tt></b> is returned, followed by an error
+message.
+</p>
+<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+<div class="footer">
+<hr>
+<center>
+<p class="bar">
+<a href="index.html">home</a> &middot;
+<a href="index.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>
+</div>
+</body>
+</html>