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