1.1 --- a/reference.txt	Sat Apr 04 03:22:06 2015 +0200
     1.2 +++ b/reference.txt	Sat Apr 04 05:10:05 2015 +0200
     1.3 @@ -45,6 +45,26 @@
     1.4  
     1.5  
     1.6  
     1.7 +Function io.poll(read_fds, write_fds, timeout)
     1.8 +----------------------------------------------
     1.9 +
    1.10 +This function allows to wait for file descriptors to become ready for reading
    1.11 +or writing. It accepts the following arguments:
    1.12 +
    1.13 +1. Table of file descriptors to wait for reading (optional, may be nil)
    1.14 +2. Table of file descriptors to wait for writing (optional, may be nil)
    1.15 +3. Timeout in seconds (optional, may be nil or zero to disable timeout)
    1.16 +
    1.17 +Alternatively to file descriptors, the tables may contain file handles (in
    1.18 +which case the file descriptor is automatically extracted).
    1.19 +
    1.20 +Please note that support for non-blocking I/O operations is limited if you use
    1.21 +ordinary file handles (as Moonbridge does). It is possible, however, to wait
    1.22 +until the first byte to read is available at a file handle. For more
    1.23 +information, see socket.input:pending().
    1.24 +
    1.25 +
    1.26 +
    1.27  Socket object passed to "connect" handler
    1.28  -----------------------------------------
    1.29  
    1.30 @@ -90,6 +110,38 @@
    1.31  Supports the same methods as io.open()'s return values.
    1.32  
    1.33  
    1.34 +### socket.input:pending()
    1.35 +
    1.36 +Returns true if there is at least one byte to read. In case of I/O errors, true
    1.37 +is returned as well (to avoid lockup and cause error on subsequent read).
    1.38 +
    1.39 +Note: Subsequent calls of socket.input:read(...) or socket.input:readuntil(...)
    1.40 +may still block when attempting to read more than one byte. To avoid hanging
    1.41 +processes, the timeout(...) function may be used as a watchdog that will
    1.42 +terminate the process in case of unexpected delay. Because file handles are
    1.43 +buffered, data may be still pending even if the underlaying file descriptor
    1.44 +does not have any more data to read. Thus, all file handles passed to
    1.45 +io.poll(...) to wait for reading should be tested for pending data first.
    1.46 +
    1.47 +This method is also available as :pending() for any other Lua file handle.
    1.48 +
    1.49 +
    1.50 +### socket.input:readuntil(terminator, maxlen)
    1.51 +
    1.52 +Reads as many bytes until a byte equal to the terminator value occurs. An
    1.53 +optional maximum length may be specified. The terminating byte is included in
    1.54 +the return value (unless the maximum length would be exceeded). On EOF, nil is
    1.55 +returned. In case of an I/O error, nil (as first result value) plus an error
    1.56 +message (as second result value) is returned.
    1.57 +
    1.58 +Note: This function may provide a significant speedup compared to byte-wise
    1.59 +reading using socket.input:read(1) in a loop. However, this function will block
    1.60 +when no data is available. The timeout(...) function may be used as a watchdog
    1.61 +that will terminate the process in case of unexpected delay.
    1.62 +
    1.63 +This method is also available as :readuntil(...) for any other Lua file handle.
    1.64 +
    1.65 +
    1.66  ### socket.interval
    1.67  
    1.68  Set to the name of an interval timer if the "connect" handler was called due to
    1.69 @@ -124,6 +176,17 @@
    1.70  Supports the same methods as io.open()'s return values.
    1.71  
    1.72  
    1.73 +### socket.output:close()
    1.74 +
    1.75 +Performs a half-close (i.e. sends a TCP FIN package in case of a TCP socket).
    1.76 +
    1.77 +Note: In order to shut down a TCP connection properly, it may be necessary to
    1.78 +read any pending data from socket.input before closing the socket completely
    1.79 +(e.g. with socket:close() or by returning from the connect handler). If there
    1.80 +is still incoming data, a TCP RST packet might be sent which can cause loss of
    1.81 +transmitted data.
    1.82 +
    1.83 +
    1.84  ### socket:read(...)
    1.85  
    1.86  Alias for socket.input:read()
    1.87 @@ -131,14 +194,7 @@
    1.88  
    1.89  ### socket:readuntil(terminator, maxlen)
    1.90  
    1.91 -Reads as many bytes until a byte equal to the terminator value occurs. An
    1.92 -optional maximum length may be specified. The terminating byte is included in
    1.93 -the return value (unless the maximum length would be exceeded). On EOF, nil is
    1.94 -returned. In case of an I/O error, nil (as first result value) plus an error
    1.95 -message (as second result value) is returned.
    1.96 -
    1.97 -This method is also available as :readuntil(...) for any other Lua file handle
    1.98 -(including socket.input).
    1.99 +Alias for socket.input:readuntil(terminator, maxlen)
   1.100  
   1.101  
   1.102  ### socket.remote_ip4