1.1 --- a/reference.txt	Fri May 01 13:56:52 2015 +0200
     1.2 +++ b/reference.txt	Sat May 02 01:48:29 2015 +0200
     1.3 @@ -70,8 +70,8 @@
     1.4  ### socket:drain(maxlen, terminator)
     1.5  
     1.6  Same as socket:read(maxlen, terminator), but discards the input and returns the
     1.7 -number of discarded bytes. If no bytes could be read but EOF was encountered,
     1.8 -then true is returned.
     1.9 +number of discarded bytes (as first return value) and the status code ("term",
    1.10 +"maxlen", "eof" as second return value).
    1.11  
    1.12  In case of an I/O error, nil (as first return value) plus an error message (as
    1.13  second return value) are returned.
    1.14 @@ -79,9 +79,9 @@
    1.15  
    1.16  ### socket:drain_nb(maxlen, terminator)
    1.17  
    1.18 -Same as socket:read_nb(maxlen, terminator), but discards the input and returns
    1.19 -the number of discarded bytes. If no bytes could be read but EOF was
    1.20 -encountered, then true is returned. 
    1.21 +Same as socket:drain(maxlen, terminator), but non-blocking. The status code
    1.22 +(which is returned as second return value) may therefore be "term", "maxlen",
    1.23 +"eof", or "block".
    1.24  
    1.25  In case of an I/O error, nil (as first return value) plus an error message (as
    1.26  second return value) are returned.
    1.27 @@ -144,16 +144,24 @@
    1.28  
    1.29  ### socket:read(maxlen, terminator)
    1.30  
    1.31 -Read up to maxlen bytes or until an optional termination character is
    1.32 +Reads up to maxlen bytes or until an optional termination character is
    1.33  encountered (which is included in the result). The maxlen value may be nil, in
    1.34  which case there is no limit on the number of bytes read.
    1.35  
    1.36 -If EOF is encountered before any data could be read, then false (as first
    1.37 -return value) plus a notice string (as second return value) are returned.
    1.38 -
    1.39  In case of an I/O error, nil (as first return value) plus an error message (as
    1.40  second return value) are returned.
    1.41  
    1.42 +In all other cases (including EOF), the following two values are returned:
    1.43 +
    1.44 +- a string containing the bytes read (first return value, may be empty string)
    1.45 +- a status code equal to "term", "maxlen", or "eof" (second return value)
    1.46 +
    1.47 +If an EOF is encountered before all data could be read, then "eof" is returned
    1.48 +as second return value. If maxlen bytes have been read and no termination
    1.49 +character has been read, then "maxlen" is returned as second return value. If
    1.50 +the termination character is the last character of the read string, the second
    1.51 +return value will be "term".
    1.52 +
    1.53  
    1.54  ### socket:read_call(waitfunc, maxlen, terminator)
    1.55  
    1.56 @@ -163,20 +171,20 @@
    1.57  
    1.58  ### socket:read_nb(maxlen, terminator)
    1.59  
    1.60 -Read up to maxlen bytes, until an optional termination character is encountered
    1.61 -(which is included in the result), or until no more data is available for
    1.62 -reading. The maxlen value may be nil, in which case there is no limit on the
    1.63 -number of bytes read.
    1.64 -
    1.65 -If EOF is encountered before any data could be read, then false (as first
    1.66 -return value) plus a notice string (as second return value) are returned.
    1.67 -
    1.68 -If no data was available for reading, but no EOF was encountered, then an empty
    1.69 -string is returned.
    1.70 +Same as socket:read(maxlen, terminator), but does not block.
    1.71  
    1.72  In case of an I/O error, nil (as first return value) plus an error message (as
    1.73  second return value) are returned.
    1.74  
    1.75 +In all other cases (including EOF), the following two values are returned:
    1.76 +
    1.77 +- a string containing the bytes read (first return value, may be empty string)
    1.78 +- a status code equal to "term", "maxlen", "eof", "block" (second return value)
    1.79 +
    1.80 +The status code "block" as second return value is used if the function returned
    1.81 +prematurely because it would block otherwise. In this case, the first return
    1.82 +value is a string that contains the bytes that could be read without blocking.
    1.83 +
    1.84  
    1.85  ### socket:read_yield(maxlen, terminator)
    1.86