1 .\" Copyright (c) 2003-2011 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $FreeBSD: head/lib/libarchive/archive_read.3 191595 2009-04-27 20:13:13Z kientzle $
28 .Dt ARCHIVE_READ_OPEN 3
31 .Nm archive_read_open ,
32 .Nm archive_read_open2 ,
33 .Nm archive_read_open_fd ,
34 .Nm archive_read_open_FILE ,
35 .Nm archive_read_open_filename ,
36 .Nm archive_read_open_memory ,
37 .Nd functions for reading streaming archives
42 .Fa "struct archive *"
43 .Fa "void *client_data"
44 .Fa "archive_open_callback *"
45 .Fa "archive_read_callback *"
46 .Fa "archive_close_callback *"
49 .Fo archive_read_open2
50 .Fa "struct archive *"
51 .Fa "void *client_data"
52 .Fa "archive_open_callback *"
53 .Fa "archive_read_callback *"
54 .Fa "archive_skip_callback *"
55 .Fa "archive_close_callback *"
58 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
60 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
62 .Fo archive_read_open_filename
63 .Fa "struct archive *"
64 .Fa "const char *filename"
65 .Fa "size_t block_size"
68 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
70 .Bl -tag -compact -width indent
71 .It Fn archive_read_open
73 .Fn archive_read_open2 ,
74 except that the skip callback is assumed to be
76 .It Fn archive_read_open2
77 Freeze the settings, open the archive, and prepare for reading entries.
78 This is the most generic version of this call, which accepts
79 four callback functions.
80 Most clients will want to use
81 .Fn archive_read_open_filename ,
82 .Fn archive_read_open_FILE ,
83 .Fn archive_read_open_fd ,
85 .Fn archive_read_open_memory
87 The library invokes the client-provided functions to obtain
88 raw bytes from the archive.
89 .It Fn archive_read_open_FILE
91 .Fn archive_read_open ,
92 except that it accepts a
95 This function should not be used with tape drives or other devices
96 that require strict I/O blocking.
97 .It Fn archive_read_open_fd
99 .Fn archive_read_open ,
100 except that it accepts a file descriptor and block size rather than
101 a set of function pointers.
102 Note that the file descriptor will not be automatically closed at
104 This function is safe for use with tape drives or other blocked devices.
105 .It Fn archive_read_open_file
106 This is a deprecated synonym for
107 .Fn archive_read_open_filename .
108 .It Fn archive_read_open_filename
110 .Fn archive_read_open ,
111 except that it accepts a simple filename and a block size.
112 A NULL filename represents standard input.
113 This function is safe for use with tape drives or other blocked devices.
114 .It Fn archive_read_open_memory
116 .Fn archive_read_open ,
117 except that it accepts a pointer and size of a block of
118 memory containing the archive data.
121 A complete description of the
124 .Tn struct archive_entry
125 objects can be found in the overview manual page for
128 The callback functions must match the following prototypes:
129 .Bl -item -offset indent
132 .Fo archive_read_callback
133 .Fa "struct archive *"
134 .Fa "void *client_data"
135 .Fa "const void **buffer"
139 .Fo archive_skip_callback
140 .Fa "struct archive *"
141 .Fa "void *client_data"
146 .Fn archive_open_callback "struct archive *" "void *client_data"
149 .Fn archive_close_callback "struct archive *" "void *client_data"
152 The open callback is invoked by
156 if the underlying file or data source is successfully
158 If the open fails, it should call
159 .Fn archive_set_error
160 to register an error code and message and return
163 The read callback is invoked whenever the library
164 requires raw bytes from the archive.
165 The read callback should read data into a buffer,
167 .Li const void **buffer
168 argument to point to the available data, and
169 return a count of the number of bytes available.
170 The library will invoke the read callback again
171 only after it has consumed this data.
172 The library imposes no constraints on the size
173 of the data blocks returned.
174 On end-of-file, the read callback should
176 On error, the read callback should invoke
177 .Fn archive_set_error
178 to register an error code and message and
181 The skip callback is invoked when the
182 library wants to ignore a block of data.
183 The return value is the number of bytes actually
184 skipped, which may differ from the request.
185 If the callback cannot skip data, it should return
187 If the skip callback is not provided (the
190 the library will invoke the read function
191 instead and simply discard the result.
192 A skip callback can provide significant
193 performance gains when reading uncompressed
194 archives from slow disk drives or other media
195 that can skip quickly.
197 The close callback is invoked by archive_close when
198 the archive processing is complete.
199 The callback should return
202 On failure, the callback should invoke
203 .Fn archive_set_error
204 to register an error code and message and
210 These functions return
216 Detailed error codes and textual descriptions are available from the
219 .Fn archive_error_string
226 .Xr archive_read_data 3 ,
227 .Xr archive_read_filter 3 ,
228 .Xr archive_read_format 3 ,
229 .Xr archive_read_set_options 3 ,