Annotation of src/usr.bin/compress/zopen.3, Revision 1.7
1.7 ! jmc 1: .\" $OpenBSD: zopen.3,v 1.6 2003/06/03 02:56:07 millert Exp $
1.1 deraadt 2: .\" $NetBSD: zopen.3,v 1.3 1995/03/26 09:44:49 glass Exp $
3: .\"
4: .\" Copyright (c) 1992, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.6 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
31: .\" @(#)zopen.3 8.1 (Berkeley) 6/9/93
32: .\"
33: .Dd June 9, 1993
34: .Dt ZOPEN 3
35: .Os
36: .Sh NAME
37: .Nm zopen
38: .Nd compressed stream open function
39: .Sh SYNOPSIS
40: .Fd #include <stdio.h>
41: .Ft FILE *
42: .Fn zopen "const char *path" "const char *mode" "int bits"
1.3 tholo 43: .Ft FILE *
44: .Fn zdopen "int fd" "const char *mode" "int bits"
1.1 deraadt 45: .Sh DESCRIPTION
46: The
47: .Fn zopen
48: function
49: opens the compressed file whose name is the string pointed to by
50: .Fa path
51: and associates a stream with it.
52: .Pp
1.3 tholo 53: The
54: .Fn zdopen
55: function
56: opens the compressed file whose file descriptor is given in
57: .Fa fd
58: and associates a stream with it.
59: .Pp
1.1 deraadt 60: The argument
61: .Fa mode
62: points to one of the following one-character strings:
63: .Bl -tag -width indent
64: .It Dq Li r
65: Open compressed file for reading.
66: The stream is positioned at the beginning of the file.
67: .It Dq Li w
68: Truncate file to zero length or create compressed file for writing.
69: The stream is positioned at the beginning of the file.
70: .El
71: .Pp
72: Any created files will have mode
73: .Pf \\*q Dv S_IRUSR
74: \&|
75: .Dv S_IWUSR
76: \&|
77: .Dv S_IRGRP
78: \&|
79: .Dv S_IWGRP
80: \&|
81: .Dv S_IROTH
82: \&|
83: .Dv S_IWOTH Ns \\*q
84: .Pq Li 0666 ,
85: as modified by the process'
86: umask value (see
87: .Xr umask 2 ) .
88: .Pp
89: Files may only be read or written.
90: Seek operations are not allowed.
91: .Pp
92: The
93: .Fa bits
94: argument, if non-zero, is set to the bits code limit.
95: If zero, the default is 16.
96: See
97: .Fn compress 1
98: for more information.
99: .Sh RETURN VALUES
100: Upon successful completion
101: .Fn zopen
102: returns a
1.5 aaron 103: .Dv FILE
1.1 deraadt 104: pointer.
105: Otherwise,
106: .Dv NULL
107: is returned and the global variable
108: .Va errno
109: is set to indicate the error.
110: .Sh ERRORS
111: .Bl -tag -width [EINVAL]
112: .It Bq Er EINVAL
113: The
114: .Fa mode
115: or
116: .Fa bits
117: arguments specified to
118: .Fn zopen
119: were invalid.
120: .It Bq Er EFTYPE
121: The compressed file starts with an invalid header, or the compressed
122: file is compressed with more bits than can be handled.
123: .El
124: .Pp
125: The
126: .Fn zopen
127: function may also fail and set
128: .Va errno
129: for any of the errors specified for the routines
130: .Xr fopen 3
131: or
132: .Xr funopen 3 .
133: .Sh SEE ALSO
134: .Xr compress 1 ,
1.7 ! jmc 135: .Xr gzip 1 ,
1.1 deraadt 136: .Xr fopen 3 ,
137: .Xr funopen 3
138: .Sh HISTORY
139: The
140: .Nm zopen
141: function
1.4 millert 142: first appeared in
143: .Bx 4.4 .
1.1 deraadt 144: .Sh BUGS
145: The
146: .Fn zopen
1.3 tholo 147: and
148: .Fn zdopen
149: functions
1.1 deraadt 150: may not be portable to systems other than
151: .Bx .