1 .\" Copyright (c) 2003-2007 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 $
32 .Nd functions for reading streaming archives
36 These functions provide a complete API for reading streaming archives.
37 The general process is to first create the
39 object, set options, initialize the reader, iterate over the archive
40 headers and associated data, then close the archive and release all
43 .Ss Create archive object
45 .Xr archive_read_new 3 .
47 To read an archive, you must first obtain an initialized
50 .Fn archive_read_new .
52 .Ss Enable filters and formats
54 .Xr archive_read_filter 3
56 .Xr archive_read_format 3 .
58 You can then modify this object for the desired operations with the
60 .Fn archive_read_set_XXX
62 .Fn archive_read_support_XXX
64 In particular, you will need to invoke appropriate
65 .Fn archive_read_support_XXX
66 functions to enable the corresponding compression and format
68 Note that these latter functions perform two distinct operations:
69 they cause the corresponding support code to be linked into your
70 program, and they enable the corresponding auto-detect code.
71 Unless you have specific constraints, you will generally want
73 .Fn archive_read_support_filter_all
75 .Fn archive_read_support_format_all
76 to enable auto-detect for all formats and compression types
77 currently supported by the library.
81 .Xr archive_read_set_options 3 .
85 .Xr archive_read_open 3 .
87 Once you have prepared the
91 to actually open the archive and prepare it for reading.
92 There are several variants of this function;
93 the most basic expects you to provide pointers to several
94 functions that can provide blocks of bytes from the archive.
95 There are convenience forms that allow you to
96 specify a filename, file descriptor,
98 object, or a block of memory from which to read the archive data.
99 Note that the core library makes no assumptions about the
100 size of the blocks read;
101 callback functions are free to read whatever block size is
102 most appropriate for the medium.
106 .Xr archive_read_header 3 ,
107 .Xr archive_read_data 3
109 .Xr archive_read_extract 3 .
111 Each archive entry consists of a header followed by a certain
113 You can obtain the next header with
114 .Fn archive_read_next_header ,
115 which returns a pointer to an
116 .Tn struct archive_entry
117 structure with information about the current archive element.
118 If the entry is a regular file, then the header will be followed
121 .Fn archive_read_data
122 (which works much like the
125 to read this data from the archive, or
126 .Fn archive_read_data_block
127 which provides a slightly more efficient interface.
128 You may prefer to use the higher-level
129 .Fn archive_read_data_skip ,
130 which reads and discards the data for this entry,
131 .Fn archive_read_data_to_file ,
132 which copies the data to the provided file descriptor, or
133 .Fn archive_read_extract ,
134 which recreates the specified entry on disk and copies data
136 In particular, note that
137 .Fn archive_read_extract
139 .Tn struct archive_entry
140 structure that you provide it, which may differ from the
141 entry just read from the archive.
142 In particular, many applications will want to override the
143 pathname, file permissions, or ownership.
145 .Ss Release resources
147 .Xr archive_read_free 3 .
149 Once you have finished reading data from the archive, you
151 .Fn archive_read_close
152 to close the archive, then call
153 .Fn archive_read_free
154 to release all resources, including all memory allocated by the library.
157 The following illustrates basic usage of the library.
159 the callback functions are simply wrappers around the standard
165 .Bd -literal -offset indent
167 list_archive(const char *name)
169 struct mydata *mydata;
171 struct archive_entry *entry;
173 mydata = malloc(sizeof(struct mydata));
174 a = archive_read_new();
176 archive_read_support_filter_all(a);
177 archive_read_support_format_all(a);
178 archive_read_open(a, mydata, myopen, myread, myclose);
179 while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
180 printf("%s\en",archive_entry_pathname(entry));
181 archive_read_data_skip(a);
183 archive_read_free(a);
188 myread(struct archive *a, void *client_data, const void **buff)
190 struct mydata *mydata = client_data;
192 *buff = mydata->buff;
193 return (read(mydata->fd, mydata->buff, 10240));
197 myopen(struct archive *a, void *client_data)
199 struct mydata *mydata = client_data;
201 mydata->fd = open(mydata->name, O_RDONLY);
202 return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
206 myclose(struct archive *a, void *client_data)
208 struct mydata *mydata = client_data;
219 .Xr archive_read_new 3 ,
220 .Xr archive_read_data 3 ,
221 .Xr archive_read_extract 3 ,
222 .Xr archive_read_filter 3 ,
223 .Xr archive_read_format 3 ,
224 .Xr archive_read_header 3 ,
225 .Xr archive_read_open 3 ,
226 .Xr archive_read_set_options 3 ,
232 library first appeared in
238 library was written by
239 .An Tim Kientzle Aq kientzle@acm.org .
241 Many traditional archiver programs treat
242 empty files as valid empty archives.
243 For example, many implementations of
245 allow you to append entries to an empty file.
246 Of course, it is impossible to determine the format of an empty file
247 by inspecting the contents, so this library treats empty files as