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
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
39 Streaming Archive Library (libarchive, -larchive)
44 .Fa "struct archive *"
45 .Fa "void *client_data"
46 .Fa "archive_open_callback *"
47 .Fa "archive_read_callback *"
48 .Fa "archive_close_callback *"
51 .Fo archive_read_open2
52 .Fa "struct archive *"
53 .Fa "void *client_data"
54 .Fa "archive_open_callback *"
55 .Fa "archive_read_callback *"
56 .Fa "archive_skip_callback *"
57 .Fa "archive_close_callback *"
60 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
62 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
64 .Fo archive_read_open_filename
65 .Fa "struct archive *"
66 .Fa "const char *filename"
67 .Fa "size_t block_size"
70 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
72 .Bl -tag -compact -width indent
73 .It Fn archive_read_open
75 .Fn archive_read_open2 ,
76 except that the skip callback is assumed to be
78 .It Fn archive_read_open2
79 Freeze the settings, open the archive, and prepare for reading entries.
80 This is the most generic version of this call, which accepts
81 four callback functions.
82 Most clients will want to use
83 .Fn archive_read_open_filename ,
84 .Fn archive_read_open_FILE ,
85 .Fn archive_read_open_fd ,
87 .Fn archive_read_open_memory
89 The library invokes the client-provided functions to obtain
90 raw bytes from the archive.
91 .It Fn archive_read_open_FILE
93 .Fn archive_read_open ,
94 except that it accepts a
97 This function should not be used with tape drives or other devices
98 that require strict I/O blocking.
99 .It Fn archive_read_open_fd
101 .Fn archive_read_open ,
102 except that it accepts a file descriptor and block size rather than
103 a set of function pointers.
104 Note that the file descriptor will not be automatically closed at
106 This function is safe for use with tape drives or other blocked devices.
107 .It Fn archive_read_open_file
108 This is a deprecated synonym for
109 .Fn archive_read_open_filename .
110 .It Fn archive_read_open_filename
112 .Fn archive_read_open ,
113 except that it accepts a simple filename and a block size.
114 A NULL filename represents standard input.
115 This function is safe for use with tape drives or other blocked devices.
116 .It Fn archive_read_open_memory
118 .Fn archive_read_open ,
119 except that it accepts a pointer and size of a block of
120 memory containing the archive data.
123 A complete description of the
126 .Tn struct archive_entry
127 objects can be found in the overview manual page for
130 The callback functions must match the following prototypes:
131 .Bl -item -offset indent
134 .Fo archive_read_callback
135 .Fa "struct archive *"
136 .Fa "void *client_data"
137 .Fa "const void **buffer"
141 .Fo archive_skip_callback
142 .Fa "struct archive *"
143 .Fa "void *client_data"
148 .Fn archive_open_callback "struct archive *" "void *client_data"
151 .Fn archive_close_callback "struct archive *" "void *client_data"
154 The open callback is invoked by
158 if the underlying file or data source is successfully
160 If the open fails, it should call
161 .Fn archive_set_error
162 to register an error code and message and return
165 The read callback is invoked whenever the library
166 requires raw bytes from the archive.
167 The read callback should read data into a buffer,
169 .Li const void **buffer
170 argument to point to the available data, and
171 return a count of the number of bytes available.
172 The library will invoke the read callback again
173 only after it has consumed this data.
174 The library imposes no constraints on the size
175 of the data blocks returned.
176 On end-of-file, the read callback should
178 On error, the read callback should invoke
179 .Fn archive_set_error
180 to register an error code and message and
183 The skip callback is invoked when the
184 library wants to ignore a block of data.
185 The return value is the number of bytes actually
186 skipped, which may differ from the request.
187 If the callback cannot skip data, it should return
189 If the skip callback is not provided (the
192 the library will invoke the read function
193 instead and simply discard the result.
194 A skip callback can provide significant
195 performance gains when reading uncompressed
196 archives from slow disk drives or other media
197 that can skip quickly.
199 The close callback is invoked by archive_close when
200 the archive processing is complete.
201 The callback should return
204 On failure, the callback should invoke
205 .Fn archive_set_error
206 to register an error code and message and
212 These functions return
218 Detailed error codes and textual descriptions are available from the
221 .Fn archive_error_string
228 .Xr archive_read_data 3 ,
229 .Xr archive_read_filter 3 ,
230 .Xr archive_read_format 3 ,
231 .Xr archive_read_set_options 3 ,