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