diff options
| -rw-r--r-- | Makefile | 1 | ||||
| -rw-r--r-- | gzopen.3 | 151 |
2 files changed, 152 insertions, 0 deletions
diff --git a/Makefile b/Makefile index 83e5321..8975efd 100644 --- a/Makefile +++ b/Makefile @@ -18,6 +18,7 @@ MAN += deflateReset.3 MAN += deflateSetDictionary.3 MAN += deflateSetHeader.3 MAN += deflateTune.3 +MAN += gzopen.3 MAN += inflate.3 MAN += inflateBack.3 MAN += inflateBackEnd.3 diff --git a/gzopen.3 b/gzopen.3 new file mode 100644 index 0000000..37ed629 --- /dev/null +++ b/gzopen.3 @@ -0,0 +1,151 @@ +.Dd November 12, 2018 +.Dt GZOPEN 3 +.Os +. +.Sh NAME +.Nm gzopen +.Nd open gzip file +. +.Sh LIBRARY +.Lb libz +. +.Sh SYNOPSIS +.In zlib.h +.Ft gzFile +.Fn gzopen "const char *path" "const char *mode" +. +.Sh DESCRIPTION +Opens a gzip (.gz) file +for reading or writing. +The +.Fa mode +parameter is as in +.Xr fopen 3 +.Po +.Dq rb +or +.Dq wb +.Pc +but can also include a compression level +.Pq Dq wb9 +or a strategy: +.Sq f +for filtered data as in +.Dq wb6f , +.Sq h +for Huffman-only compression as in +.Dq wb1h , +.Sq R +for run-length encoding as in +.Dq wb1R , +or +.Sq F +for fixed code compression as in +.Dq wb9F . +.Po +See the description of +.Xr deflateInit2 3 +for more information about the +.Fa strategy +parameter. +.Pc +.Sq T +will request transparent writing or appending +with no compression +and not using the gzip format. +. +.Pp +.Dq a +can be used instead of +.Dq w +to request that the gzip stream +that will be written +be appended to the file. +.Dq + +will result in an error, +since reading and writing +to the same gzip file +is not supported. +The addition of +.Dq x +when writing will create the file exclusively, +which fails if the file already exists. +On systems that support it, +the addition of +.Dq e +when reading or writing +will set the flag to close the file on an +.Xr execve 2 +call. +. +.Pp +These functions, +as well as +.Xr gzip 1 , +will read and decode +a sequence of gzip streams in a file. +The append function of +.Fn gzopen +can be used to create such a file. +.Po +Also see +.Xr gzflush 3 +for another way to do this. +.Pc +When appending, +.Fn gzopen +does not test whether the file begins with a gzip stream, +nor does it look for the end of the gzip streams +to begin appending. +.Fn gzopen +will simply append a gzip stream +to the existing file. +. +.Pp +.Fn gzopen +can be used to read a file which is not in gzip format; +in this case +.Xr gzread 3 +will directly read from the file without decompression. +When reading, +this will be detected automatically +by looking for the magic two-byte gzip header. +. +.Sh RETURN VALUES +.Fn gzopen +returns +.Dv NULL +if the file could not be opened, +if there was insufficient memory +to allocate the +.Vt gzFile +state, +or if an invalid +.Fa mode +was specified +.Po +an +.Sq r , +.Sq w , +or +.Sq a +was not provided, +or +.Sq + +was provided +.Pc . +.Va errno +can be checked +to determine if the reason +.Fn gzopen +failed was that the file +could not be opened. +. +.Sh ERRORS +The +.Fn gzopen +function may fail and set +.Va errno +for any of the errors specified +for the routine +.Xr fopen 3 . |