1 .\" Copyright (c) 2003-2004 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: src/lib/libarchive/archive_read.3,v 1.11 2004/08/07 19:22:50 kientzle Exp $
31 .Nm archive_read_new ,
32 .Nm archive_read_set_bytes_per_block ,
33 .Nm archive_read_support_compression_all ,
34 .Nm archive_read_support_compression_bzip2 ,
35 .Nm archive_read_support_compression_compress ,
36 .Nm archive_read_support_compression_gzip ,
37 .Nm archive_read_support_compression_none ,
38 .Nm archive_read_support_format_tar ,
39 .Nm archive_read_support_format_cpio ,
40 .Nm archive_read_support_format_all ,
41 .Nm archive_read_open ,
42 .Nm archive_read_open_fd ,
43 .Nm archive_read_open_file ,
44 .Nm archive_read_next_header ,
45 .Nm archive_read_data ,
46 .Nm archive_read_data_block ,
47 .Nm archive_read_data_skip ,
48 .Nm archive_read_data_into_buffer ,
49 .Nm archive_read_data_into_fd ,
50 .Nm archive_read_extract ,
51 .Nm archive_read_extract_set_progress_callback ,
52 .Nm archive_read_close
53 .Nm archive_read_finish
54 .Nd functions for reading tar archives
58 .Fn archive_read_new "void"
60 .Fn archive_read_set_bytes_per_block "struct archive *" "int"
62 .Fn archive_read_support_compression_all "struct archive *"
64 .Fn archive_read_support_compression_bzip2 "struct archive *"
66 .Fn archive_read_support_compression_compress "struct archive *"
68 .Fn archive_read_support_compression_gzip "struct archive *"
70 .Fn archive_read_support_compression_none "struct archive *"
72 .Fn archive_read_support_format_tar "struct archive *"
74 .Fn archive_read_support_format_cpio "struct archive *"
76 .Fn archive_read_support_format_all "struct archive *"
78 .Fn archive_read_open "struct archive *" "void *client_data" "archive_read_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
80 .Fn archive_read_open_fd "struct archive *" "int fd"
82 .Fn archive_read_open_file "struct archive *" "const char *filename"
84 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
86 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
88 .Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"
90 .Fn archive_read_data_skip "struct archive *"
92 .Fn archive_read_data_into_buffer "struct archive *" "void *"
94 .Fn archive_read_data_into_fd "struct archive *" "int fd"
96 .Fn archive_read_extract "struct archive *" "int flags"
98 .Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"
100 .Fn archive_read_close "struct archive *"
102 .Fn archive_read_finish "struct archive *"
104 These functions provide a complete API for reading streaming archives.
105 The general process is to first create the
107 object, set options, initialize the reader, iterate over the archive
108 headers and associated data, then close the archive and release all
110 The following summary describes the functions in approximately the
111 order they would be used:
112 .Bl -tag -compact -width indent
113 .It Fn archive_read_new
114 Allocates and initializes a
116 object suitable for reading from an archive.
117 .It Fn archive_read_set_bytes_per_block
118 Sets the block size used for reading the archive data.
119 This controls the size that will be used when invoking the read
121 The default is 20 records or 10240 bytes for tar formats.
122 .It Fn archive_read_support_compression_XXX
123 Enables auto-detection code and decompression support for the
124 specified compression.
127 is always enabled by default.
129 .Fn archive_read_support_compression_all
130 enables all available decompression code.
131 .It Fn archive_read_support_format_XXX
132 Enables support---including auto-detection code---for the
133 specified archive format.
135 .Fn archive_read_support_format_tar
136 enables support for a variety of standard tar formats, old-style tar,
137 ustar, pax interchange format, and many common variants.
139 .Fn archive_read_support_format_all
140 enables support for all available formats.
141 Note that there is no default.
142 .It Fn archive_read_open
143 Freeze the settings, open the archive, and prepare for reading entries.
144 This is the most generic version of this call, which accepts
145 three callback functions.
146 The library invokes these client-provided functions to obtain
147 raw bytes from the archive.
148 Note: The API permits a decompression method to fork and invoke the
149 callbacks from another process.
150 Although none of the current decompression methods use this technique,
151 future decompression methods may utilize this technique.
152 If the decompressor forks, it will ensure that the open and close
153 callbacks are invoked within the same process as the read callback.
154 In particular, clients should not attempt to use shared variables to
155 communicate between the open/read/close callbacks and the mainline code.
156 .It Fn archive_read_open_fd
158 .Fn archive_read_open ,
159 except that it accepts a file descriptor rather than
160 a trio of function pointers.
161 Note that the file descriptor will not be automatically closed at
163 .It Fn archive_read_open_file
165 .Fn archive_read_open ,
166 except that it accepts a simple filename.
167 A NULL filename represents standard input.
168 .It Fn archive_read_next_header
169 Read the header for the next entry and return a pointer to
171 .Tn struct archive_entry .
172 .It Fn archive_read_data
173 Read data associated with the header just read.
174 Internally, this is a convenience function that calls
175 .Fn archive_read_data_block
176 and fills any gaps with nulls so that callers see a single
177 continuous stream of data.
178 .It Fn archive_read_data_block
179 Return the next available block of data for this entry.
181 .Fn archive_read_data ,
183 .Fn archive_read_data_block
184 function avoids copying data and allows you to correctly handle
185 sparse files, as supported by some archive formats.
186 The library gaurantees that offsets will increase and that blocks
188 .It Fn archive_read_data_skip
189 A convenience function that repeatedly calls
190 .Fn archive_read_data_block
191 to skip all of the data for this archive entry.
192 .It Fn archive_read_data_into_buffer
193 A convenience function that repeatedly calls
194 .Fn archive_read_data_block
195 to copy the entire entry into the client-supplied buffer.
196 Note that the client is responsible for sizing the buffer appropriately.
197 .It Fn archive_read_data_into_fd
198 A convenience function that repeatedly calls
199 .Fn archive_read_data_block
200 to copy the entire entry to the provided file descriptor.
201 .It Fn archive_read_extract
202 A convenience function that recreates the specified object on
203 disk and reads the entry data into that object.
206 argument modifies how the object is recreated.
207 It consists of a bitwise OR of one or more of the following values:
208 .Bl -tag -compact -width "indent"
209 .It Cm ARCHIVE_EXTRACT_OWNER
210 The user and group IDs should be set on the restored file.
211 By default, the user and group IDs are not restored.
212 .It Cm ARCHIVE_EXTRACT_PERM
213 The permissions (mode bits) should be restored for all objects.
214 By default, permissions are only restored for regular files.
215 .It Cm ARCHIVE_EXTRACT_TIME
216 The timestamps (mtime, ctime, and atime) should be restored.
217 By default, they are ignored.
218 Note that restoring of atime is not currently supported.
219 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
220 Existing files on disk will not be overwritten.
221 By default, existing files are unlinked before the new entry is written.
222 .It Cm ARCHIVE_EXTRACT_UNLINK
223 Existing files on disk will be unlinked and recreated from scratch.
224 By default, existing files are truncated and rewritten, but
225 the file is not recreated.
226 In particular, the default behavior does not break existing hard links.
228 .It Fn archive_read_extract_set_progress_callback
229 Sets a pointer to a user-defined callback that can be used
230 for updating progress displays during extraction.
231 The progress function will be invoked during the extraction of large
233 The progress function will be invoked with the pointer provided to this call.
234 Generally, the data pointed to should include a reference to the archive
235 object and the archive_entry object so that various statistics
236 can be retrieved for the progress display.
237 .It Fn archive_read_close
238 Complete the archive and invoke the close callback.
239 .It Fn archive_read_finish
241 .Fn archive_read_close
242 if it wasn't invoked maually, then release all resources.
245 Note that the library determines most of the relevant information about
246 the archive by inspection.
247 In particular, it automatically detects
251 compression and transparently performs the appropriate decompression.
252 It also automatically detects the archive format.
254 The callback functions must match the following prototypes:
255 .Bl -item -offset indent
258 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
261 .Fn archive_open_callback "struct archive *" "void *client_data"
264 .Fn archive_close_callback "struct archive *" "void *client_data"
266 These callback functions are called whenever the library requires
267 raw bytes from the archive.
268 Note that it is the client's responsibility to correctly
271 A complete description of the
274 .Tn struct archive_entry
275 objects can be found in the overview manual page for
278 The following illustrates basic usage of the library.
280 the callback functions are simply wrappers around the standard
286 .Bd -literal -offset indent
288 list_archive(const char *name)
290 struct mydata *mydata;
292 struct archive_entry *entry;
294 mydata = malloc(sizeof(struct mydata));
295 a = archive_read_new();
297 archive_read_support_compression_all(a);
298 archive_read_support_format_all(a);
299 archive_read_open(a, mydata, myopen, myread, myclose);
300 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
301 printf("%s\\n",archive_entry_pathname(entry));
302 archive_read_data_skip(a);
304 archive_read_finish(a);
309 myread(struct archive *a, void *client_data, const void **buff)
311 struct mydata *mydata = client_data;
313 *buff = mydata->buff;
314 return (read(mydata->fd, mydata->buff, 10240));
318 myopen(struct archive *a, void *client_data)
320 struct mydata *mydata = client_data;
322 mydata->fd = open(mydata->name, O_RDONLY);
323 return (mydata->fd >= 0);
327 myclose(struct archive *a, void *client_data)
329 struct mydata *mydata = client_data;
337 Most functions return zero on success, non-zero on error.
338 The possible return codes include:
340 (the operation succeeded)
342 (the operation succeeded but a non-critical error was encountered)
344 (end-of-archive was encountered),
346 (the operation failed but can be retried),
349 (there was a fatal error; the archive should be closed immediately).
350 Detailed error codes and textual descriptions are available from the
353 .Fn archive_error_string
357 returns a pointer to a freshly allocated
364 .Fn archive_read_data
365 returns a count of bytes actually read or zero at the end of the entry.
371 is returned and an error code and textual description can be retrieved from the
374 .Fn archive_error_string
377 The library expects the client callbacks to behave similarly.
378 If there is an error, you can use
379 .Fn archive_set_error
380 to set an appropriate error code and description,
381 then return one of the non-zero values above.
382 (Note that the value eventually returned to the client may
383 not be the same; many errors that are not critical at the level
384 of basic I/O can prevent the archive from being properly read,
385 thus most I/O errors eventually cause
396 library first appeared in
402 library was written by
403 .An Tim Kientzle Aq kientzle@acm.org .