Add gzdopen to gzopen.3

1 files changed, 82 insertions, 2 deletions

diff --git a/gzopen.3 b/gzopen.3
index 37ed629..daebe5a 100644
--- a/gzopen.3
+++ b/gzopen.3
@@ -3,7 +3,8 @@
 .Os
 .
 .Sh NAME
-.Nm gzopen
+.Nm gzopen ,
+.Nm gzdopen
 .Nd open gzip file
 .
 .Sh LIBRARY
@@ -13,6 +14,8 @@
 .In zlib.h
 .Ft gzFile
 .Fn gzopen "const char *path" "const char *mode"
+.Ft gzFile
+.Fn gzdopen "int fd" "const char *mode"
 .
 .Sh DESCRIPTION
 Opens a gzip (.gz) file
@@ -111,9 +114,70 @@ When reading,
 this will be detected automatically
 by looking for the magic two-byte gzip header.
 .
+.Pp
+.Fn gzdopen
+associates at
+.Vt gzFile
+with the file descriptor
+.Fa fd .
+File descriptors
+are obtained from calls like
+.Xr open 2 ,
+.Xr dup 2 ,
+.Xr creat 2 ,
+.Xr pipe 2
+or
+.Xr fileno 3
+.Po
+if the file has been previously opened with
+.Xr fopen 3
+.Pc .
+The
+.Fa mode
+parameter is as in
+.Fn gzopen .
+.
+.Pp
+The next call of
+.Xr gzclose 3
+on the returned
+.Vt gzFile
+will also close the file descriptor
+.Fa fd ,
+just like
+.Xr fclose 3 .
+If you want to keep
+.Fa fd
+open,
+use
+.Li "fd = dup(fd_keep); gz = gzdopen(fd, mode);" .
+The duplicated descriptor should be saved
+to avoid a leak,
+since
+.Fn gzdopen
+does not close
+.Fa fd
+if it fails.
+If you are using
+.Xr fileno 3
+to get the file descriptor from a
+.Vt FILE * ,
+then you will have to use
+.Xr dup 2
+to avoid double-closing
+the file descriptor.
+Both
+.Xr gzclose 3
+and
+.Xr flcose 3
+will close the associated file descriptor,
+so they need to have different file descriptors.
+.
 .Sh RETURN VALUES
 .Fn gzopen
-returns
+and
+.Fn gzdopen
+return
 .Dv NULL
 if the file could not be opened,
 if there was insufficient memory
@@ -133,6 +197,22 @@ was not provided,
 or
 .Sq +
 was provided
+.Pc ,
+or if
+.Fa fd
+is -1.
+The file descriptor
+is not used until the next
+gz* read, write, seek, or close operation,
+so
+.Fn gzdopen
+will not detect if
+.Fa fd
+is invalid
+.Po
+unless
+.Fa fd
+is -1
 .Pc .
 .Va errno
 can be checked