1.1 --- a/reference.txt	Tue Apr 07 02:52:41 2015 +0200
     1.2 +++ b/reference.txt	Tue Apr 07 03:50:28 2015 +0200
     1.3 @@ -52,42 +52,65 @@
     1.4  a single socket object as argument, which is described below:
     1.5  
     1.6  
     1.7 -### socket:cancel()
     1.8 -
     1.9 -Closes the socket connection by sending a TCP RST package if possible to
    1.10 -indicate error condition. Returns true on success, or nil plus error message in
    1.11 -case of an I/O error. Using this method on sockets that have already been
    1.12 -closed (or canceled) will throw an error.
    1.13 -
    1.14 -Warning: Previously sent (and flushed) data may be lost during transmission.
    1.15 -
    1.16 -
    1.17  ### socket:close(timeout)
    1.18  
    1.19  Closes the socket connection (input and output stream) by flushing all data and
    1.20 -sending a TCP FIN package. Returns true on success, or nil plus error message
    1.21 -in case of an I/O error. Using this method on sockets that have already been
    1.22 -closed (or canceled) will throw an error.
    1.23 +sending a TCP FIN packet. If the timeout value is non-nil but zero, a TCP RST
    1.24 +is sent instead. If a positive timeout value is given and if the remote peer
    1.25 +doesn't respond with a TCP FIN within the given time, a TCP RST is sent in
    1.26 +addition to the previously sent TCP FIN packet. If the timeout value is nil or
    1.27 +negative, the call returns immediately and the operating system will wait for
    1.28 +the peer's TCP FIN packet.
    1.29 +
    1.30 +Returns true on success, or nil plus error message in case of an I/O error.
    1.31 +Using this method on sockets that have already been closed (or reset) will
    1.32 +throw an error.
    1.33  
    1.34  Warning: Pending data on the input stream may cause connection aborts (TCP RST)
    1.35  depending on the particular operating system used. All pending input data
    1.36 -should have been read before calling socket:close().
    1.37 +should have been read (or drained) before calling socket:close().
    1.38 +
    1.39 +
    1.40 +### socket:drain(maxlen, terminator)
    1.41  
    1.42 -The optional timeout parameter may be used to wait until all data has been sent
    1.43 -out, or until the timeout elapses (in which case a TCP RST is sent) whichever
    1.44 -happens first. A timeout value of 0 or nil causes immediate return and sending
    1.45 -of pending data in background (recommended).
    1.46 +Same as socket:read(maxlen, terminator), but discards the input and returns the
    1.47 +number of discarded bytes. If no bytes could be read but EOF was encountered,
    1.48 +then true is returned.
    1.49 +
    1.50 +In case of an I/O error, nil (as first return value) plus an error message (as
    1.51 +second result value) are returned.
    1.52  
    1.53  
    1.54 -### socket:flush()
    1.55 +### socket:drain_nb(maxlen, terminator)
    1.56  
    1.57 -Alias for socket.output:flush()
    1.58 +Same as socket:read_nb(maxlen, terminator), but discards the input and returns
    1.59 +the number of discarded bytes. If no bytes could be read but EOF was
    1.60 +encountered, then true is returned. 
    1.61 +
    1.62 +In case of an I/O error, nil (as first return value) plus an error message (as
    1.63 +second result value) are returned.
    1.64 +
    1.65  
    1.66  
    1.67 -### socket.input
    1.68 +### socket:flush(...)
    1.69 +
    1.70 +Same as socket:write(...) but additionally flushes the socket (i.e. all pending
    1.71 +data is passed to the operating system).
    1.72 +
    1.73 +In case of an I/O error, nil (as first return value) plus an error message (as
    1.74 +second result value) are returned. On success, the socket userdata object is
    1.75 +returned.
    1.76 +
    1.77  
    1.78 -Lua file handle representing the input stream of the socket connection.
    1.79 -Supports the same methods as io.open()'s return values.
    1.80 +### socket:flush_nb(...)
    1.81 +
    1.82 +Same as socket:write_nb(...) but additionally flushes the socket (i.e. all
    1.83 +pending data is passed to the operating system). The total number of bytes that
    1.84 +could not be passed yet to the operating system is returned. Zero is returned
    1.85 +if all data could be flushed out.
    1.86 +
    1.87 +In case of an I/O error, nil (as first return value) plus an error message (as
    1.88 +second result value) are returned.
    1.89  
    1.90  
    1.91  ### socket.interval
    1.92 @@ -96,11 +119,6 @@
    1.93  an elapsed interval timer. Otherwise nil.
    1.94  
    1.95  
    1.96 -### socket:lines()
    1.97 -
    1.98 -Alias for socket.input:lines()
    1.99 -
   1.100 -
   1.101  ### socket.local_ip4
   1.102  
   1.103  Local IPv4 address used for the connection. Encoded as 4 raw bytes in form of a
   1.104 @@ -118,27 +136,34 @@
   1.105  Local TCP port used for the connection.
   1.106  
   1.107  
   1.108 -### socket.output
   1.109 +### socket:read(maxlen, terminator)
   1.110  
   1.111 -Lua file handle representing the output stream of the socket connection.
   1.112 -Supports the same methods as io.open()'s return values.
   1.113 +Read up to maxlen bytes or until an optional termination character is
   1.114 +encountered (which is included in the result). The maxlen value may be nil, in
   1.115 +which case there is no limit on the number of bytes read.
   1.116  
   1.117 +If EOF is encountered before any data could be read, then false (as first
   1.118 +return value) plus a notice string (as second return value) are returned.
   1.119  
   1.120 -### socket:read(...)
   1.121 -
   1.122 -Alias for socket.input:read()
   1.123 +In case of an I/O error, nil (as first return value) plus an error message (as
   1.124 +second result value) are returned.
   1.125  
   1.126  
   1.127 -### socket:readuntil(terminator, maxlen)
   1.128 +### socket:read_nb(maxlen, terminator)
   1.129 +
   1.130 +Read up to maxlen bytes, until an optional termination character is encountered
   1.131 +(which is included in the result), or until no more data is available for
   1.132 +reading. The maxlen value may be nil, in which case there is no limit on the
   1.133 +number of bytes read.
   1.134  
   1.135 -Reads as many bytes until a byte equal to the terminator value occurs. An
   1.136 -optional maximum length may be specified. The terminating byte is included in
   1.137 -the return value (unless the maximum length would be exceeded). On EOF, nil is
   1.138 -returned. In case of an I/O error, nil (as first result value) plus an error
   1.139 -message (as second result value) is returned.
   1.140 +If EOF is encountered before any data could be read, then false (as first
   1.141 +return value) plus a notice string (as second return value) are returned.
   1.142  
   1.143 -This method is also available as :readuntil(...) for any other Lua file handle
   1.144 -(including socket.input).
   1.145 +If no data was available for reading, but no EOF was encountered, then an empty
   1.146 +string is returned.
   1.147 +
   1.148 +In case of an I/O error, nil (as first return value) plus an error message (as
   1.149 +second result value) are returned.
   1.150  
   1.151  
   1.152  ### socket.remote_ip4
   1.153 @@ -158,9 +183,43 @@
   1.154  Remote TCP port used for the connection.
   1.155  
   1.156  
   1.157 +### socket:reset()
   1.158 +
   1.159 +Alias for socket:close(0). Closes the socket connection by sending a TCP RST
   1.160 +packet if possible to indicate error condition.
   1.161 +
   1.162 +Returns true on success, or nil (as first result value) plus error message (as
   1.163 +second result value) in case of an I/O error. Using this method on sockets that
   1.164 +have already been closed (or reset) will throw an error.
   1.165 +
   1.166 +Warning: Previously sent (and flushed) data may be lost during transmission.
   1.167 +
   1.168 +
   1.169  ### socket:write(...)
   1.170  
   1.171 -Alias for socket.output:write(...)
   1.172 +Takes a variable number of strings and sends them to the peer. The operation is
   1.173 +buffered, so to actually send out the data, it is necessary to eventually call
   1.174 +socket:flush(), socket:finish(), or socket:close().
   1.175 +
   1.176 +In case of an I/O error, nil (as first return value) plus an error message (as
   1.177 +second result value) are returned. On success, the socket userdata object is
   1.178 +returned.
   1.179 +
   1.180 +
   1.181 +### socket:write_nb(...)
   1.182 +
   1.183 +Takes a variable number of strings and sends them to the peer. The operation is
   1.184 +buffered, so to actually send out the data, it is necessary to eventually call
   1.185 +socket:flush_nb(), socket:flush(), socket:finish(), or socket:close().
   1.186 +
   1.187 +This function always returns immediately (i.e. it does not block). If all data
   1.188 +(but a small buffered portion) could be sent out, then zero is returned.
   1.189 +Otherwise, all arguments that could not be sent are stored in a buffer of
   1.190 +unlimited size (up to memory capabilities) and an integer is returned that
   1.191 +indicates the number of bytes currently in the buffer.
   1.192 +
   1.193 +In case of an I/O error, nil (as first return value) plus an error message (as
   1.194 +second result value) are returned.
   1.195  
   1.196  
   1.197