summary refs log tree commit diff
path: root/doc/zlib/gzread.3
blob: 4118eca774c53ef6ef091f3589693ba58e6fb377 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
.Dd January 15, 2017
.Dt GZREAD 3
.Os
.
.Sh NAME
.Nm gzread
.Nd read from compressed file
.
.Sh LIBRARY
.Lb libz
.
.Sh SYNOPSIS
.In zlib.h
.Ft int
.Fn gzread "gzFile file" "voidp buf" "unsigned len"
.
.Sh DESCRIPTION
Reads the given number of uncompressed bytes
from the compressed file.
If the input file
is not in gzip format,
.Fn gzread
copies the given number of bytes
into the buffer directly from the file.
.
.Pp
After reaching the end of a gzip stream
in the input,
.Fn gzread
will continue to read,
looking for another gzip stream.
Any number of gzip streams
may be concatenated in the input file,
and will all be decompressed by
.Fn gzread .
If something other than a gzip stream
is encountered after a gzip stream,
that remaining trailing garbage is ignored
(and no error is returned).
.
.Pp
.Fn gzread
can be used to read a gzip file
that is being concurrently written.
Upon reaching the end of the input,
.Fn gzread
will return with the available data.
If the error code returned by
.Xr gzerror 3
is
.Dv Z_OK
or
.Dv Z_BUF_ERROR ,
then
.Xr gzclearerr 3
can be used
to clear the end of file indicator
in order to permit
.Fn gzread
to be tried again.
.Dv Z_OK
indicates that a gzip stream was completed
on the last
.Fn gzread .
.Dv Z_BUF_ERROR
indicates that the input file
ended in the middle of a gzip stream.
Note that
.Fn gzread
does not return -1
in the event of an incomplete gzip stream.
This error is deferred until
.Xr gzclose 3 ,
which will return
.Dv Z_BUF_ERROR
if the last
.Fn gzread
ended in the middle of a gzip stream.
Alternatively,
.Xr gzerror 3
can be used before
.Xr gzclose 3
to detect this case.
.
.Sh RETURN VALUES
.Fn gzread
returns the number of uncompressed bytes actually read,
less than
.Fa len
for end of file,
or -1 for error.
If
.Fa len
is too large to fit in an
.Vt int ,
then nothing is read,
-1 is returned,
and the error state is set to
.Dv Z_STREAM_ERROR .
.
.Sh SEE ALSO
.Xr gzeof 3 ,
.Xr gzerror 3 ,
.Xr gzfread 3 ,
.Xr gzopen 3
.
.Sh HISTORY
This manual page was converted from
.In zlib.h
to mdoc format by
.An June McEnroe Aq Mt june@causal.agency .
.
.Sh AUTHORS
.An Jean-loup Gailly Aq Mt jloup@gzip.org
.An Mark Adler Aq Mt madler@alumni.caltech.edu
21 -0500'>2019-12-19Ignore about-filterJune McEnroe 2019-12-19Fix matching make tags with no sourcesJune McEnroe 2019-12-19Avoid matching := assignments as tagsJune McEnroe 2019-12-18Hide line numbers when rendering mdocJune McEnroe Hack: output an extra <td> after rendering mdoc so that line numbers can be hidden based on there being three. This required splitting source-filter and about-filter since on about pages there is no table. 2019-12-18Customize cgit CSSJune McEnroe 2019-12-18Use :target rather than :focus pseudo-classJune McEnroe :target persists after you click on something else. 2019-12-18Copy cgit auxiliary binaries properlyJune McEnroe 2019-12-18Add git.causal.agency cgit configJune McEnroe 2019-12-18Bail from hi if input is binaryJune McEnroe NULs in the input cause an infinite loop in htmlEscape, not to mention regexes obviously not working, etc. 2019-12-16Post "cgit setup"June McEnroe