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_DATA 3
29.Os
30.Sh NAME
31.Nm archive_read_data ,
32.Nm archive_read_data_block ,
33.Nm archive_read_data_skip ,
34.Nm archive_read_data_into_fd
35.Nd functions for reading streaming archives
36.Sh LIBRARY
37Streaming Archive Library (libarchive, -larchive)
38.Sh SYNOPSIS
39.In archive.h
40.Ft la_ssize_t
41.Fn archive_read_data "struct archive *" "void *buff" "size_t len"
42.Ft int
43.Fo archive_read_data_block
44.Fa "struct archive *"
45.Fa "const void **buff"
46.Fa "size_t *len"
47.Fa "off_t *offset"
48.Fc
49.Ft int
50.Fn archive_read_data_skip "struct archive *"
51.Ft int
52.Fn archive_read_data_into_fd "struct archive *" "int fd"
53.\"
54.Sh DESCRIPTION
55.Bl -tag -compact -width indent
56.It Fn archive_read_data
57Read data associated with the header just read.
58Internally, this is a convenience function that calls
59.Fn archive_read_data_block
60and fills any gaps with nulls so that callers see a single
61continuous stream of data.
62.It Fn archive_read_data_block
63Return the next available block of data for this entry.
64Unlike
65.Fn archive_read_data ,
66the
67.Fn archive_read_data_block
68function avoids copying data and allows you to correctly handle
69sparse files, as supported by some archive formats.
70The library guarantees that offsets will increase and that blocks
71will not overlap.
72Note that the blocks returned from this function can be much larger
73than the block size read from disk, due to compression
74and internal buffer optimizations.
75.It Fn archive_read_data_skip
76A convenience function that repeatedly calls
77.Fn archive_read_data_block
78to skip all of the data for this archive entry.
79Note that this function is invoked automatically by
80.Fn archive_read_next_header2
81if the previous entry was not completely consumed.
82.It Fn archive_read_data_into_fd
83A convenience function that repeatedly calls
84.Fn archive_read_data_block
85to copy the entire entry to the provided file descriptor.
86.El
87.\"
88.Sh RETURN VALUES
89Most functions return zero on success, non-zero on error.
90The possible return codes include:
91.Cm ARCHIVE_OK
92(the operation succeeded),
93.Cm ARCHIVE_WARN
94(the operation succeeded but a non-critical error was encountered),
95.Cm ARCHIVE_EOF
96(end-of-archive was encountered),
97.Cm ARCHIVE_RETRY
98(the operation failed but can be retried),
99and
100.Cm ARCHIVE_FATAL
101(there was a fatal error; the archive should be closed immediately).
102.Pp
103.Fn archive_read_data
104returns a count of bytes actually read or zero at the end of the entry.
105On error, a value of
106.Cm ARCHIVE_FATAL ,
107.Cm ARCHIVE_WARN ,
108or
109.Cm ARCHIVE_RETRY
110is returned.
111.\"
112.Sh ERRORS
113Detailed error codes and textual descriptions are available from the
114.Fn archive_errno
115and
116.Fn archive_error_string
117functions.
118.\"
119.Sh SEE ALSO
120.Xr tar 1 ,
121.Xr archive_read 3 ,
122.Xr archive_read_extract 3 ,
123.Xr archive_read_filter 3 ,
124.Xr archive_read_format 3 ,
125.Xr archive_read_header 3 ,
126.Xr archive_read_open 3 ,
127.Xr archive_read_set_options 3 ,
128.Xr archive_util 3 ,
129.Xr libarchive 3 ,
130.Xr tar 5
131