Document gzread() capability to read concurrently written files.

Also since gzread() will no longer return an error for an incomplete
gzip file, have gzclose() return an error if the last gzread() ended
in the middle of a gzip stream.

1 files changed, 14 insertions, 1 deletions

diff --git a/zlib.h b/zlib.h
index 1ee04e9..7068d50 100644
--- a/zlib.h
+++ b/zlib.h
@@ -1297,6 +1297,18 @@ ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len));
    If something other than a gzip stream is encountered after a gzip stream,
    that remaining trailing garbage is ignored (and no error is returned).
 
+     gzread can be used to read a gzip file that is being concurrently written.
+   Upon reaching the end of the input, gzread will return with the available
+   data.  If the error code returned by gzerror is Z_OK or Z_BUF_ERROR, then
+   gzclearerr can be used to clear the end of file indicator in order to permit
+   gzread to be tried again.  Z_OK indicates that a gzip stream was completed
+   on the last gzread.  Z_BUF_ERROR indicates that the input file ended in the
+   middle of a gzip stream.  Note that gzread does not return -1 in the event
+   of an incomplete gzip stream.  This error is deferred until gzclose(), which
+   will return Z_BUF_ERROR if the last gzread ended in the middle of a gzip
+   stream.  Alternatively, gzerror can be used before gzclose to detect this
+   case.
+
      gzread returns the number of uncompressed bytes actually read, less than
    len for end of file, or -1 for error.
 */
@@ -1480,7 +1492,8 @@ ZEXTERN int ZEXPORT    gzclose OF((gzFile file));
    must not be called more than once on the same allocation.
 
      gzclose will return Z_STREAM_ERROR if file is not valid, Z_ERRNO on a
-   file operation error, Z_MEM_ERROR if out of memory, or Z_OK on success.
+   file operation error, Z_MEM_ERROR if out of memory, Z_BUF_ERROR if the
+   last read ended in the middle of a gzip stream, or Z_OK on success.
 */
 
 ZEXTERN int ZEXPORT gzclose_r OF((gzFile file));