.Os
.Sh NAME
.Nm archive_read_new ,
-.Nm archive_read_open ,
-.Nm archive_read_open2 ,
-.Nm archive_read_open_fd ,
-.Nm archive_read_open_FILE ,
-.Nm archive_read_open_filename ,
-.Nm archive_read_open_memory ,
.Nm archive_read_next_header ,
.Nm archive_read_next_header2 ,
.Nm archive_read_data ,
.Ft struct archive *
.Fn archive_read_new "void"
.Ft int
-.Fo archive_read_open
-.Fa "struct archive *"
-.Fa "void *client_data"
-.Fa "archive_open_callback *"
-.Fa "archive_read_callback *"
-.Fa "archive_close_callback *"
-.Fc
-.Ft int
-.Fo archive_read_open2
-.Fa "struct archive *"
-.Fa "void *client_data"
-.Fa "archive_open_callback *"
-.Fa "archive_read_callback *"
-.Fa "archive_skip_callback *"
-.Fa "archive_close_callback *"
-.Fc
-.Ft int
-.Fn archive_read_open_FILE "struct archive *" "FILE *file"
-.Ft int
-.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
-.Ft int
-.Fo archive_read_open_filename
-.Fa "struct archive *"
-.Fa "const char *filename"
-.Fa "size_t block_size"
-.Fc
-.Ft int
-.Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
-.Ft int
.Fn archive_read_next_header "struct archive *" "struct archive_entry **"
.Ft int
.Fn archive_read_next_header2 "struct archive *" "struct archive_entry *"
object, set options, initialize the reader, iterate over the archive
headers and associated data, then close the archive and release all
resources.
-.Pp
-The following summary describes the functions in approximately the
-order they would be used, with the caveat that functions enabling filters
-and archive formats and option setting functions, which must be called
-before the archive is opened, are described in
-.Xr archive_read_filter 3
-and
-.Xr archive_read_format 3 :
.\"
+.Ss Create archive object
.Bl -tag -compact -width indent
.It Fn archive_read_new
Allocates and initializes a
.Tn struct archive
object suitable for reading from an archive.
-.It Fn archive_read_open
-The same as
-.Fn archive_read_open2 ,
-except that the skip callback is assumed to be
-.Dv NULL .
-.It Fn archive_read_open2
-Freeze the settings, open the archive, and prepare for reading entries.
-This is the most generic version of this call, which accepts
-four callback functions.
-Most clients will want to use
-.Fn archive_read_open_filename ,
-.Fn archive_read_open_FILE ,
-.Fn archive_read_open_fd ,
-or
-.Fn archive_read_open_memory
-instead.
-The library invokes the client-provided functions to obtain
-raw bytes from the archive.
-.It Fn archive_read_open_FILE
-Like
-.Fn archive_read_open ,
-except that it accepts a
-.Ft "FILE *"
-pointer.
-This function should not be used with tape drives or other devices
-that require strict I/O blocking.
-.It Fn archive_read_open_fd
-Like
-.Fn archive_read_open ,
-except that it accepts a file descriptor and block size rather than
-a set of function pointers.
-Note that the file descriptor will not be automatically closed at
-end-of-archive.
-This function is safe for use with tape drives or other blocked devices.
-.It Fn archive_read_open_file
-This is a deprecated synonym for
-.Fn archive_read_open_filename .
-.It Fn archive_read_open_filename
-Like
-.Fn archive_read_open ,
-except that it accepts a simple filename and a block size.
-A NULL filename represents standard input.
-This function is safe for use with tape drives or other blocked devices.
-.It Fn archive_read_open_memory
-Like
-.Fn archive_read_open ,
-except that it accepts a pointer and size of a block of
-memory containing the archive data.
+.El
+.Ss Enable filters and formats
+See
+.Xr archive_read_filter 3
+and
+.Xr archive_read_format 3 .
+.\"
+.Ss Set options
+See
+.Xr archive_read_set_options 3 .
+.\"
+.Ss Open archive
+See
+.Xr archive_read_open 3 .
+.\"
+.Ss Consume archive
+.Bl -tag -compact -width indent
.It Fn archive_read_next_header
Read the header for the next entry and return a pointer to
a
Generally, the data pointed to should include a reference to the archive
object and the archive_entry object so that various statistics
can be retrieved for the progress display.
+.El
+.\"
+.Ss Release resources
+.Bl -tag -compact -width indent
.It Fn archive_read_close
Complete the archive and invoke the close callback.
.It Fn archive_read_finish
.Tn struct archive_entry
objects can be found in the overview manual page for
.Xr libarchive 3 .
-.Sh CLIENT CALLBACKS
-The callback functions must match the following prototypes:
-.Bl -item -offset indent
-.It
-.Ft typedef ssize_t
-.Fo archive_read_callback
-.Fa "struct archive *"
-.Fa "void *client_data"
-.Fa "const void **buffer"
-.Fc
-.It
-.Ft typedef off_t
-.Fo archive_skip_callback
-.Fa "struct archive *"
-.Fa "void *client_data"
-.Fa "off_t request"
-.Fc
-.It
-.Ft typedef int
-.Fn archive_open_callback "struct archive *" "void *client_data"
-.It
-.Ft typedef int
-.Fn archive_close_callback "struct archive *" "void *client_data"
-.El
-.Pp
-The open callback is invoked by
-.Fn archive_open .
-It should return
-.Cm ARCHIVE_OK
-if the underlying file or data source is successfully
-opened.
-If the open fails, it should call
-.Fn archive_set_error
-to register an error code and message and return
-.Cm ARCHIVE_FATAL .
-.Pp
-The read callback is invoked whenever the library
-requires raw bytes from the archive.
-The read callback should read data into a buffer,
-set the
-.Li const void **buffer
-argument to point to the available data, and
-return a count of the number of bytes available.
-The library will invoke the read callback again
-only after it has consumed this data.
-The library imposes no constraints on the size
-of the data blocks returned.
-On end-of-file, the read callback should
-return zero.
-On error, the read callback should invoke
-.Fn archive_set_error
-to register an error code and message and
-return -1.
-.Pp
-The skip callback is invoked when the
-library wants to ignore a block of data.
-The return value is the number of bytes actually
-skipped, which may differ from the request.
-If the callback cannot skip data, it should return
-zero.
-If the skip callback is not provided (the
-function pointer is
-.Dv NULL ),
-the library will invoke the read function
-instead and simply discard the result.
-A skip callback can provide significant
-performance gains when reading uncompressed
-archives from slow disk drives or other media
-that can skip quickly.
-.Pp
-The close callback is invoked by archive_close when
-the archive processing is complete.
-The callback should return
-.Cm ARCHIVE_OK
-on success.
-On failure, the callback should invoke
-.Fn archive_set_error
-to register an error code and message and
-return
-.Cm ARCHIVE_FATAL.
.Sh EXAMPLE
The following illustrates basic usage of the library.
In this example,
--- /dev/null
+.\" Copyright (c) 2003-2011 Tim Kientzle
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD: head/lib/libarchive/archive_read.3 191595 2009-04-27 20:13:13Z kientzle $
+.\"
+.Dd March 19, 2011
+.Dt archive_read_open 3
+.Os
+.Sh NAME
+.Nm archive_read_open ,
+.Nm archive_read_open2 ,
+.Nm archive_read_open_fd ,
+.Nm archive_read_open_FILE ,
+.Nm archive_read_open_filename ,
+.Nm archive_read_open_memory ,
+.Nd functions for reading streaming archives
+.Sh SYNOPSIS
+.In archive.h
+.Ft int
+.Fo archive_read_open
+.Fa "struct archive *"
+.Fa "void *client_data"
+.Fa "archive_open_callback *"
+.Fa "archive_read_callback *"
+.Fa "archive_close_callback *"
+.Fc
+.Ft int
+.Fo archive_read_open2
+.Fa "struct archive *"
+.Fa "void *client_data"
+.Fa "archive_open_callback *"
+.Fa "archive_read_callback *"
+.Fa "archive_skip_callback *"
+.Fa "archive_close_callback *"
+.Fc
+.Ft int
+.Fn archive_read_open_FILE "struct archive *" "FILE *file"
+.Ft int
+.Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
+.Ft int
+.Fo archive_read_open_filename
+.Fa "struct archive *"
+.Fa "const char *filename"
+.Fa "size_t block_size"
+.Fc
+.Ft int
+.Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
+.Sh DESCRIPTION
+.Bl -tag -compact -width indent
+.It Fn archive_read_open
+The same as
+.Fn archive_read_open2 ,
+except that the skip callback is assumed to be
+.Dv NULL .
+.It Fn archive_read_open2
+Freeze the settings, open the archive, and prepare for reading entries.
+This is the most generic version of this call, which accepts
+four callback functions.
+Most clients will want to use
+.Fn archive_read_open_filename ,
+.Fn archive_read_open_FILE ,
+.Fn archive_read_open_fd ,
+or
+.Fn archive_read_open_memory
+instead.
+The library invokes the client-provided functions to obtain
+raw bytes from the archive.
+.It Fn archive_read_open_FILE
+Like
+.Fn archive_read_open ,
+except that it accepts a
+.Ft "FILE *"
+pointer.
+This function should not be used with tape drives or other devices
+that require strict I/O blocking.
+.It Fn archive_read_open_fd
+Like
+.Fn archive_read_open ,
+except that it accepts a file descriptor and block size rather than
+a set of function pointers.
+Note that the file descriptor will not be automatically closed at
+end-of-archive.
+This function is safe for use with tape drives or other blocked devices.
+.It Fn archive_read_open_file
+This is a deprecated synonym for
+.Fn archive_read_open_filename .
+.It Fn archive_read_open_filename
+Like
+.Fn archive_read_open ,
+except that it accepts a simple filename and a block size.
+A NULL filename represents standard input.
+This function is safe for use with tape drives or other blocked devices.
+.It Fn archive_read_open_memory
+Like
+.Fn archive_read_open ,
+except that it accepts a pointer and size of a block of
+memory containing the archive data.
+.El
+.Pp
+A complete description of the
+.Tn struct archive
+and
+.Tn struct archive_entry
+objects can be found in the overview manual page for
+.Xr libarchive 3 .
+.Sh CLIENT CALLBACKS
+The callback functions must match the following prototypes:
+.Bl -item -offset indent
+.It
+.Ft typedef ssize_t
+.Fo archive_read_callback
+.Fa "struct archive *"
+.Fa "void *client_data"
+.Fa "const void **buffer"
+.Fc
+.It
+.Ft typedef off_t
+.Fo archive_skip_callback
+.Fa "struct archive *"
+.Fa "void *client_data"
+.Fa "off_t request"
+.Fc
+.It
+.Ft typedef int
+.Fn archive_open_callback "struct archive *" "void *client_data"
+.It
+.Ft typedef int
+.Fn archive_close_callback "struct archive *" "void *client_data"
+.El
+.Pp
+The open callback is invoked by
+.Fn archive_open .
+It should return
+.Cm ARCHIVE_OK
+if the underlying file or data source is successfully
+opened.
+If the open fails, it should call
+.Fn archive_set_error
+to register an error code and message and return
+.Cm ARCHIVE_FATAL .
+.Pp
+The read callback is invoked whenever the library
+requires raw bytes from the archive.
+The read callback should read data into a buffer,
+set the
+.Li const void **buffer
+argument to point to the available data, and
+return a count of the number of bytes available.
+The library will invoke the read callback again
+only after it has consumed this data.
+The library imposes no constraints on the size
+of the data blocks returned.
+On end-of-file, the read callback should
+return zero.
+On error, the read callback should invoke
+.Fn archive_set_error
+to register an error code and message and
+return -1.
+.Pp
+The skip callback is invoked when the
+library wants to ignore a block of data.
+The return value is the number of bytes actually
+skipped, which may differ from the request.
+If the callback cannot skip data, it should return
+zero.
+If the skip callback is not provided (the
+function pointer is
+.Dv NULL ),
+the library will invoke the read function
+instead and simply discard the result.
+A skip callback can provide significant
+performance gains when reading uncompressed
+archives from slow disk drives or other media
+that can skip quickly.
+.Pp
+The close callback is invoked by archive_close when
+the archive processing is complete.
+The callback should return
+.Cm ARCHIVE_OK
+on success.
+On failure, the callback should invoke
+.Fn archive_set_error
+to register an error code and message and
+return
+.Cm ARCHIVE_FATAL.
+.\" .Sh EXAMPLE
+.\"
+.Sh RETURN VALUES
+These functions return
+.Cm ARCHIVE_OK
+on success, or
+.Cm ARCHIVE_FATAL .
+.Pp
+Detailed error codes and textual descriptions are available from the
+.Fn archive_errno
+and
+.Fn archive_error_string
+functions.
+.Pp
+The library expects the client callbacks to behave similarly.
+If there is an error, you can use
+.Fn archive_set_error
+to set an appropriate error code and description,
+then return one of the non-zero values above.
+(Note that the value eventually returned to the client may
+not be the same; many errors that are not critical at the level
+of basic I/O can prevent the archive from being properly read,
+thus most I/O errors eventually cause
+.Cm ARCHIVE_FATAL
+to be returned.)
+.\" .Sh ERRORS
+.Sh SEE ALSO
+.Xr tar 1 ,
+.Xr libarchive 3 ,
+.Xr archive_read 3 ,
+.Xr archive_read_filter 3 ,
+.Xr archive_read_format 3 ,
+.Xr archive_read_set_options 3 ,
+.Xr archive_util 3 ,
+.Xr tar 5
projects / thirdparty / libarchive.git / commitdiff
