1.\" Copyright (c) 2003-2007 Tim Kientzle
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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.
12.\"
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
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD: head/lib/libarchive/archive_read.3 191595 2009-04-27 20:13:13Z kientzle $
26.\"
27.Dd March 23, 2011
28.Dt ARCHIVE_READ 3
29.Os
30.Sh NAME
31.Nm archive_read
32.Nd functions for reading streaming archives
33.Sh SYNOPSIS
34.In archive.h
35.Sh DESCRIPTION
36These functions provide a complete API for reading streaming archives.
37The general process is to first create the
38.Tn struct archive
39object, set options, initialize the reader, iterate over the archive
40headers and associated data, then close the archive and release all
41resources.
42.\"
43.Ss Create archive object
44See
45.Xr archive_read_new 3 .
46.Pp
47To read an archive, you must first obtain an initialized
48.Tn struct archive
49object from
50.Fn archive_read_new .
51.\"
52.Ss Enable filters and formats
53See
54.Xr archive_read_filter 3
55and
56.Xr archive_read_format 3 .
57.Pp
58You can then modify this object for the desired operations with the
59various
60.Fn archive_read_set_XXX
61and
62.Fn archive_read_support_XXX
63functions.
64In particular, you will need to invoke appropriate
65.Fn archive_read_support_XXX
66functions to enable the corresponding compression and format
67support.
68Note that these latter functions perform two distinct operations:
69they cause the corresponding support code to be linked into your
70program, and they enable the corresponding auto-detect code.
71Unless you have specific constraints, you will generally want
72to invoke
73.Fn archive_read_support_filter_all
74and
75.Fn archive_read_support_format_all
76to enable auto-detect for all formats and compression types
77currently supported by the library.
78.\"
79.Ss Set options
80See
81.Xr archive_read_set_options 3 .
82.\"
83.Ss Open archive
84See
85.Xr archive_read_open 3 .
86.Pp
87Once you have prepared the
88.Tn struct archive
89object, you call
90.Fn archive_read_open
91to actually open the archive and prepare it for reading.
92There are several variants of this function;
93the most basic expects you to provide pointers to several
94functions that can provide blocks of bytes from the archive.
95There are convenience forms that allow you to
96specify a filename, file descriptor,
97.Ft "FILE *"
98object, or a block of memory from which to read the archive data.
99Note that the core library makes no assumptions about the
100size of the blocks read;
101callback functions are free to read whatever block size is
102most appropriate for the medium.
103.\"
104.Ss Consume archive
105See
106.Xr archive_read_header 3 ,
107.Xr archive_read_data 3
108and
109.Xr archive_read_extract 3 .
110.Pp
111Each archive entry consists of a header followed by a certain
112amount of data.
113You can obtain the next header with
114.Fn archive_read_next_header ,
115which returns a pointer to an
116.Tn struct archive_entry
117structure with information about the current archive element.
118If the entry is a regular file, then the header will be followed
119by the file data.
120You can use
121.Fn archive_read_data
122(which works much like the
123.Xr read 2
124system call)
125to read this data from the archive, or
126.Fn archive_read_data_block
127which provides a slightly more efficient interface.
128You may prefer to use the higher-level
129.Fn archive_read_data_skip ,
130which reads and discards the data for this entry,
131.Fn archive_read_data_to_file ,
132which copies the data to the provided file descriptor, or
133.Fn archive_read_extract ,
134which recreates the specified entry on disk and copies data
135from the archive.
136In particular, note that
137.Fn archive_read_extract
138uses the
139.Tn struct archive_entry
140structure that you provide it, which may differ from the
141entry just read from the archive.
142In particular, many applications will want to override the
143pathname, file permissions, or ownership.
144.\"
145.Ss Release resources
146See
147.Xr archive_read_free 3 .
148.Pp
149Once you have finished reading data from the archive, you
150should call
151.Fn archive_read_close
152to close the archive, then call
153.Fn archive_read_free
154to release all resources, including all memory allocated by the library.
155.\"
156.Sh EXAMPLE
157The following illustrates basic usage of the library.
158In this example,
159the callback functions are simply wrappers around the standard
160.Xr open 2 ,
161.Xr read 2 ,
162and
163.Xr close 2
164system calls.
165.Bd -literal -offset indent
166void
167list_archive(const char *name)
168{
169  struct mydata *mydata;
170  struct archive *a;
171  struct archive_entry *entry;
172
173  mydata = malloc(sizeof(struct mydata));
174  a = archive_read_new();
175  mydata->name = name;
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);
182  }
183  archive_read_free(a);
184  free(mydata);
185}
186
187ssize_t
188myread(struct archive *a, void *client_data, const void **buff)
189{
190  struct mydata *mydata = client_data;
191
192  *buff = mydata->buff;
193  return (read(mydata->fd, mydata->buff, 10240));
194}
195
196int
197myopen(struct archive *a, void *client_data)
198{
199  struct mydata *mydata = client_data;
200
201  mydata->fd = open(mydata->name, O_RDONLY);
202  return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
203}
204
205int
206myclose(struct archive *a, void *client_data)
207{
208  struct mydata *mydata = client_data;
209
210  if (mydata->fd > 0)
211    close(mydata->fd);
212  return (ARCHIVE_OK);
213}
214.Ed
215.\" .Sh ERRORS
216.Sh SEE ALSO
217.Xr tar 1 ,
218.Xr libarchive 3 ,
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 ,
227.Xr archive_util 3 ,
228.Xr tar 5
229.Sh HISTORY
230The
231.Nm libarchive
232library first appeared in
233.Fx 5.3 .
234.Sh AUTHORS
235.An -nosplit
236The
237.Nm libarchive
238library was written by
239.An Tim Kientzle Aq kientzle@acm.org .
240.Sh BUGS
241Many traditional archiver programs treat
242empty files as valid empty archives.
243For example, many implementations of
244.Xr tar 1
245allow you to append entries to an empty file.
246Of course, it is impossible to determine the format of an empty file
247by inspecting the contents, so this library treats empty files as
248having a special
249.Dq empty
250format.
251