1.\" Copyright (c) 2003-2011 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_OPEN 3
29.Os
30.Sh NAME
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
38.Sh LIBRARY
39Streaming Archive Library (libarchive, -larchive)
40.Sh SYNOPSIS
41.In archive.h
42.Ft int
43.Fo archive_read_open
44.Fa "struct archive *"
45.Fa "void *client_data"
46.Fa "archive_open_callback *"
47.Fa "archive_read_callback *"
48.Fa "archive_close_callback *"
49.Fc
50.Ft int
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 *"
58.Fc
59.Ft int
60.Fn archive_read_open_FILE "struct archive *" "FILE *file"
61.Ft int
62.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
63.Ft int
64.Fo archive_read_open_filename
65.Fa "struct archive *"
66.Fa "const char *filename"
67.Fa "size_t block_size"
68.Fc
69.Ft int
70.Fn archive_read_open_memory "struct archive *" "const void *buff" "size_t size"
71.Sh DESCRIPTION
72.Bl -tag -compact -width indent
73.It Fn archive_read_open
74The same as
75.Fn archive_read_open2 ,
76except that the skip callback is assumed to be
77.Dv NULL .
78.It Fn archive_read_open2
79Freeze the settings, open the archive, and prepare for reading entries.
80This is the most generic version of this call, which accepts
81four callback functions.
82Most clients will want to use
83.Fn archive_read_open_filename ,
84.Fn archive_read_open_FILE ,
85.Fn archive_read_open_fd ,
86or
87.Fn archive_read_open_memory
88instead.
89The library invokes the client-provided functions to obtain
90raw bytes from the archive.
91.It Fn archive_read_open_FILE
92Like
93.Fn archive_read_open ,
94except that it accepts a
95.Ft "FILE *"
96pointer.
97This function should not be used with tape drives or other devices
98that require strict I/O blocking.
99.It Fn archive_read_open_fd
100Like
101.Fn archive_read_open ,
102except that it accepts a file descriptor and block size rather than
103a set of function pointers.
104Note that the file descriptor will not be automatically closed at
105end-of-archive.
106This function is safe for use with tape drives or other blocked devices.
107.It Fn archive_read_open_file
108This is a deprecated synonym for
109.Fn archive_read_open_filename .
110.It Fn archive_read_open_filename
111Like
112.Fn archive_read_open ,
113except that it accepts a simple filename and a block size.
114A NULL filename represents standard input.
115This function is safe for use with tape drives or other blocked devices.
116.It Fn archive_read_open_memory
117Like
118.Fn archive_read_open ,
119except that it accepts a pointer and size of a block of
120memory containing the archive data.
121.El
122.Pp
123A complete description of the
124.Tn struct archive
125and
126.Tn struct archive_entry
127objects can be found in the overview manual page for
128.Xr libarchive 3 .
129.Sh CLIENT CALLBACKS
130The callback functions must match the following prototypes:
131.Bl -item -offset indent
132.It
133.Ft typedef la_ssize_t
134.Fo archive_read_callback
135.Fa "struct archive *"
136.Fa "void *client_data"
137.Fa "const void **buffer"
138.Fc
139.It
140.Ft typedef la_int64_t
141.Fo archive_skip_callback
142.Fa "struct archive *"
143.Fa "void *client_data"
144.Fa "off_t request"
145.Fc
146.It
147.Ft typedef int
148.Fn archive_open_callback "struct archive *" "void *client_data"
149.It
150.Ft typedef int
151.Fn archive_close_callback "struct archive *" "void *client_data"
152.El
153.Pp
154The open callback is invoked by
155.Fn archive_open .
156It should return
157.Cm ARCHIVE_OK
158if the underlying file or data source is successfully
159opened.
160If the open fails, it should call
161.Fn archive_set_error
162to register an error code and message and return
163.Cm ARCHIVE_FATAL .
164.Pp
165The read callback is invoked whenever the library
166requires raw bytes from the archive.
167The read callback should read data into a buffer,
168set the
169.Li const void **buffer
170argument to point to the available data, and
171return a count of the number of bytes available.
172The library will invoke the read callback again
173only after it has consumed this data.
174The library imposes no constraints on the size
175of the data blocks returned.
176On end-of-file, the read callback should
177return zero.
178On error, the read callback should invoke
179.Fn archive_set_error
180to register an error code and message and
181return -1.
182.Pp
183The skip callback is invoked when the
184library wants to ignore a block of data.
185The return value is the number of bytes actually
186skipped, which may differ from the request.
187If the callback cannot skip data, it should return
188zero.
189If the skip callback is not provided (the
190function pointer is
191.Dv NULL ),
192the library will invoke the read function
193instead and simply discard the result.
194A skip callback can provide significant
195performance gains when reading uncompressed
196archives from slow disk drives or other media
197that can skip quickly.
198.Pp
199The close callback is invoked by archive_close when
200the archive processing is complete.
201The callback should return
202.Cm ARCHIVE_OK
203on success.
204On failure, the callback should invoke
205.Fn archive_set_error
206to register an error code and message and
207return
208.Cm ARCHIVE_FATAL .
209.\" .Sh EXAMPLE
210.\"
211.Sh RETURN VALUES
212These functions return
213.Cm ARCHIVE_OK
214on success, or
215.Cm ARCHIVE_FATAL .
216.\"
217.Sh ERRORS
218Detailed error codes and textual descriptions are available from the
219.Fn archive_errno
220and
221.Fn archive_error_string
222functions.
223.\"
224.Sh SEE ALSO
225.Xr tar 1 ,
226.Xr archive_read 3 ,
227.Xr archive_read_data 3 ,
228.Xr archive_read_filter 3 ,
229.Xr archive_read_format 3 ,
230.Xr archive_read_set_options 3 ,
231.Xr archive_util 3 ,
232.Xr libarchive 3 ,
233.Xr tar 5
234