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