1.\" $MirOS: src/lib/libz/gzfopen.3,v 1.2 2006/01/24 19:41:51 tg Exp $
2.\"-
3.\" Copyright (c) 2006
4.\"	Thorsten Glaser <tg@mirbsd.de>
5.\" Copyright (c) 1990, 1991, 1993
6.\"	The Regents of the University of California.  All rights reserved.
7.\"
8.\" This code is derived from software contributed to Berkeley by
9.\" Chris Torek and the American National Standards Committee X3,
10.\" on Information Processing Systems.
11.\"
12.\" Licensee is hereby permitted to deal in this work without restric-
13.\" tion, including unlimited rights to use, publicly perform, modify,
14.\" merge, distribute, sell, give away or sublicence, provided all co-
15.\" pyright notices above, these terms and the disclaimer are retained
16.\" in all redistributions or reproduced in accompanying documentation
17.\" or other materials provided with binary redistributions.
18.\"
19.\" All advertising materials mentioning features or use of this soft-
20.\" ware must display the following acknowledgement:
21.\"	This product includes material provided by Thorsten Glaser.
22.\"
23.\" Licensor offers the work "AS IS" and WITHOUT WARRANTY of any kind,
24.\" express, or implied, to the maximum extent permitted by applicable
25.\" law, without malicious intent or gross negligence; in no event may
26.\" licensor, an author or contributor be held liable for any indirect
27.\" or other damage, or direct damage except proven a consequence of a
28.\" direct error of said person and intended use of this work, loss or
29.\" other issues arising in any way out of its use, even if advised of
30.\" the possibility of such damage or existence of a nontrivial bug.
31.\"-
32.Dd January 24, 2006
33.Dt GZFOPEN 3
34.Os
35.Sh NAME
36.Nm gzfopen ,
37.Nm gzfdopen
38.Nd deflated stream open functions
39.Sh SYNOPSIS
40.Fd #include <zlib.h>
41.Ft FILE *
42.Fn gzfopen "const char *path" "const char *mode"
43.Ft FILE *
44.Fn gzfdopen "int filedes" "const char *mode"
45.Sh DESCRIPTION
46The
47.Fn gzfopen
48function opens the file whose name is the string pointed to by
49.Fa path
50and associates a zlib stream with it.
51.Pp
52The
53.Fn gzfdopen
54function associates a zlib stream with the existing file descriptor
55.Fa filedes .
56The
57.Fa mode
58of the stream must be compatible with the mode of the file descriptor.
59The stream is positioned at the file offset of the file descriptor,
60which must point to the first byte of the deflate magic in read mode.
61If
62.Fn gzfdopen
63fails, the file descriptor
64.Fa filedes
65is not affected in any way.
66If
67.Fn gzfdopen
68succeeds, any subsequential
69.Fn fclose
70will also close and invalidate
71.Fa filedes .
72.Pp
73The argument
74.Fa mode
75points to a string beginning with one of the following
76characters (additional characters may follow):
77.Bl -tag -width indent
78.It Dq Li r
79Open file for reading.
80.It Dq Li w
81Truncate file to zero length or create text file for writing.
82.It Dq Li a
83Open for writing.
84The file is created if it does not exist.
85.El
86.Pp
87The characters which can follow are the same as for the
88.Fn gzopen
89function:
90.Bl -tag -width indent
91.It Dq Li b
92Binary mode (meaningless under
93.Ux ) .
94.It Dq Li f
95Set the zlib stream strategy to filtered.
96.It Dq Li h
97Set the zlib stream strategy to huffman-only.
98.It Dq Li R
99Set the zlib stream to use RLE compression instead of deflate.
100.It Dq Li 0..9
101Set the compression level of the zlib stream used for writing.
102.El
103.Sh RETURN VALUES
104Upon successful completion,
105.Fn gzfopen
106and
107.Fn gzfdopen
108return a
109.Vt FILE
110pointer.
111Otherwise,
112.Dv NULL
113is returned and the global variable
114.Va errno
115is set to indicate the error.
116.Sh ERRORS
117For both the
118.Fn gzfopen
119and
120.Fn gzfdopen
121functions, as well as stream operations (read,
122write, seek, close), the code tries to meaningful
123map the zlib error codes to errno values.
124An unknown error is mapped to
125.Er ENOCOFFEE .
126.Pp
127.Fn gzfopen
128and
129.Fn gzfdopen
130can return any error code which the underlying
131.Fn funopen
132function returns, and fail for additional reasons.
133.Sh SEE ALSO
134.Xr close 2 ,
135.Xr funopen 3 ,
136.Xr gzclose 3 ,
137.Xr gzdopen 3 ,
138.Xr gzopen 3 ,
139.Xr gzread 3 ,
140.Xr gzseek 3 ,
141.Xr gzwrite 3 ,
142.Xr lseek 2 ,
143.Xr open 2 ,
144.Xr read 2 ,
145.Xr write 2
146.Pp
147The description of
148.Fn deflateInit2
149inside
150.Xr compress 3 .
151.Sh HISTORY
152.Nm gzfopen
153and
154.Nm gzfdopen
155first appeared in
156.Mx 9 .
157.Sh AUTHORS
158The code and manual page have been written by
159.An Thorsten Glaser Aq tg@mirbsd.de .
160.Sh CAVEATS
161Attempt to
162.Fn lseek
163on the stream is subject to the same limitations as
164.Fn gzseek
165is, and discouraged.
166