# HG changeset patch
# User jbe
# Date 1428602563 -7200
# Node ID 0eba766e9be2cf308cadfbb52967557c2bc60c8a
# Parent  113185a57b06fe06e4a1a2adac52625df25f8109
Updated reference to include listeners and local sockets

diff -r 113185a57b06 -r 0eba766e9be2 reference.txt
--- a/reference.txt	Thu Apr 09 19:02:43 2015 +0200
+++ b/reference.txt	Thu Apr 09 20:02:43 2015 +0200
@@ -74,7 +74,7 @@
 then true is returned.
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned.
+second return value) are returned.
 
 
 ### socket:drain_nb(maxlen, terminator)
@@ -84,7 +84,7 @@
 encountered, then true is returned. 
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned.
+second return value) are returned.
 
 
 ### socket:finish()
@@ -104,7 +104,7 @@
 data is passed to the operating system).
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned. On success, the socket userdata object is
+second return value) are returned. On success, the socket userdata object is
 returned.
 
 
@@ -116,7 +116,7 @@
 if all data could be flushed out.
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned.
+second return value) are returned.
 
 
 ### socket.interval
@@ -152,7 +152,7 @@
 return value) plus a notice string (as second return value) are returned.
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned.
+second return value) are returned.
 
 
 ### socket:read_nb(maxlen, terminator)
@@ -169,7 +169,7 @@
 string is returned.
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned.
+second return value) are returned.
 
 
 ### socket.remote_ip4
@@ -194,8 +194,8 @@
 Alias for socket:close(0). Closes the socket connection by sending a TCP RST
 packet if possible to indicate error condition.
 
-Returns true on success, or nil (as first result value) plus error message (as
-second result value) in case of an I/O error. Using this method on sockets that
+Returns true on success, or nil (as first return value) plus error message (as
+second return value) in case of an I/O error. Using this method on sockets that
 have already been closed (or reset) will throw an error.
 
 Warning: Previously sent (and flushed) data may be lost during transmission.
@@ -208,7 +208,7 @@
 socket:flush(), socket:finish(), or socket:close().
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned. On success, the socket userdata object is
+second return value) are returned. On success, the socket userdata object is
 returned.
 
 
@@ -225,7 +225,7 @@
 indicates the number of bytes currently in the buffer.
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) are returned.
+second return value) are returned.
 
 
 
@@ -235,6 +235,60 @@
 The Moonbridge Network Server for Lua Applications comes with its own I/O
 library to support blocking as well as nonblocking I/O operations.
 
+All methods on an I/O handle (e.g. socket) are described in the previous
+section regarding the "socket" object. All other functions of the library are
+listed below.
+
+
+### moonbridge_io.localconnect(path)
+
+Tries to connect to a local socket (also known as Unix Domain Socket). Returns
+a socket object on success, or nil (as first return value) plus an error
+message (as second return value) in case of error.
+
+
+### moonbridge_io.localconnect_nb(path)
+
+Tries to connect to a local socket (also known as Unix Domain Socket). Returns
+a socket object on success, or nil (as first return value) plus an error
+message (as second return value) in case of error.
+
+Same as moonbridge_io.localconnect(path), except that this function does not
+block and immediately returns a socket object.  
+
+In case of an I/O error, nil (as first return value) plus an error message (as
+second return value) may be returned. However, connection errors may also be
+reported on first read or write on the socket.
+
+
+### moonbridge_io.locallisten(path)
+
+Attempts to create a local socket (also known as Unix Domain Socket) to accept
+incoming connections.
+
+Note: The caller is responsible for unlinking the socket in the filesystem
+before opening or after closing the listening socket. If a file (or socket)
+already exists at the given path, this function returns with an I/O error.
+
+In case of an I/O error, nil (as first return value) plus an error message (as
+second return value) may be returned.On success, a listener object is returned
+which supports the methods :accept(), :accept_nb(), and :close(). 
+
+The method :accept() blocks until a new incoming connection is available in
+which case a socket object is returned.
+
+The method :accept_nb() works like :accept(), except that the call is
+nonblocking and returns false (plus a notice as second return value) in case no
+incoming connection is available. It is possible to wait for an incoming
+connection by including the listener object in the input_set of the
+moonbridge_io.poll(...) call.
+
+The method :close() will close the listening socket. In case of local sockets
+(Unix Domain Sockets), the socket will not be unlinked in the file system.
+
+I/O errors by the methods of the listener object are also reported by returning
+nil (as first return value) plus an error message (as second return value).
+
 
 ### moonbridge_io.poll(input_set, output_set, timeout)
 
@@ -252,8 +306,8 @@
 ### moonbridge_io.tcpconnect(hostname, port)
 
 Tries to open a TCP connection with the given host and TCP port number. Returns
-a socket object on success (methods see above), or nil (as first return value)
-plus an error message (as second return value) in case of error.
+a socket object on success, or nil (as first return value) plus an error
+message (as second return value) in case of error.
 
 
 ### moonbridge_io.tcpconnect_nb(hostname, port)
@@ -265,10 +319,23 @@
 numeric IP address as hostname to be truly nonblocking.
 
 In case of an I/O error, nil (as first return value) plus an error message (as
-second result value) may be returned. However, connection errors may also be
+second return value) may be returned. However, connection errors may also be
 reported on first read or write on the socket.
 
 
+### moonbridge_io.tcplisten(hostname, port)
+
+Attempts to open a TCP port for listening. To listen on the loopback interface,
+use "::1" as hostname if IPv6 shall be used, or use "127.0.0.1" as hostname if
+IPv4 shall be used. To listen on all available interfaces, use "::" (IPv6) or
+"0.0.0.0" (IPv4) respectively.
+
+In case of an I/O error, nil (as first return value) plus an error message (as
+second return value) may be returned. On success, a listener object is returned
+which supports the methods :accept(), :accept_nb(), and :close(). See reference
+for moonbridge.io_locallisten(...).
+
+
 
 HTTP module
 -----------