libarchive/archive_read.3 - third_party/libarchive - Git at Google

 .\" Copyright (c) 2003-2007 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$
 .\"
 .Dd February 2, 2012
 .Dt ARCHIVE_READ 3
 .Os
 .Sh NAME
 .Nm archive_read
 .Nd functions for reading streaming archives
 .Sh LIBRARY
 Streaming Archive Library (libarchive, -larchive)
 .Sh SYNOPSIS
 .In archive.h
 .Sh DESCRIPTION
 These functions provide a complete API for reading streaming archives.
 The general process is to first create the
 .Tn struct archive
 object, set options, initialize the reader, iterate over the archive
 headers and associated data, then close the archive and release all
 resources.
 .\"
 .Ss Create archive object
 See
 .Xr archive_read_new 3 .
 .Pp
 To read an archive, you must first obtain an initialized
 .Tn struct archive
 object from
 .Fn archive_read_new .
 .\"
 .Ss Enable filters and formats
 See
 .Xr archive_read_filter 3
 and
 .Xr archive_read_format 3 .
 .Pp
 You can then modify this object for the desired operations with the
 various
 .Fn archive_read_set_XXX
 and
 .Fn archive_read_support_XXX
 functions.
 In particular, you will need to invoke appropriate
 .Fn archive_read_support_XXX
 functions to enable the corresponding compression and format
 support.
 Note that these latter functions perform two distinct operations:
 they cause the corresponding support code to be linked into your
 program, and they enable the corresponding auto-detect code.
 Unless you have specific constraints, you will generally want
 to invoke
 .Fn archive_read_support_filter_all
 and
 .Fn archive_read_support_format_all
 to enable auto-detect for all formats and compression types
 currently supported by the library.
 .\"
 .Ss Set options
 See
 .Xr archive_read_set_options 3 .
 .\"
 .Ss Open archive
 See
 .Xr archive_read_open 3 .
 .Pp
 Once you have prepared the
 .Tn struct archive
 object, you call
 .Fn archive_read_open
 to actually open the archive and prepare it for reading.
 There are several variants of this function;
 the most basic expects you to provide pointers to several
 functions that can provide blocks of bytes from the archive.
 There are convenience forms that allow you to
 specify a filename, file descriptor,
 .Ft "FILE *"
 object, or a block of memory from which to read the archive data.
 Note that the core library makes no assumptions about the
 size of the blocks read;
 callback functions are free to read whatever block size is
 most appropriate for the medium.
 .\"
 .Ss Consume archive
 See
 .Xr archive_read_header 3 ,
 .Xr archive_read_data 3
 and
 .Xr archive_read_extract 3 .
 .Pp
 Each archive entry consists of a header followed by a certain
 amount of data.
 You can obtain the next header with
 .Fn archive_read_next_header ,
 which returns a pointer to an
 .Tn struct archive_entry
 structure with information about the current archive element.
 If the entry is a regular file, then the header will be followed
 by the file data.
 You can use
 .Fn archive_read_data
 (which works much like the
 .Xr read 2
 system call)
 to read this data from the archive, or
 .Fn archive_read_data_block
 which provides a slightly more efficient interface.
 You may prefer to use the higher-level
 .Fn archive_read_data_skip ,
 which reads and discards the data for this entry,
 .Fn archive_read_data_to_file ,
 which copies the data to the provided file descriptor, or
 .Fn archive_read_extract ,
 which recreates the specified entry on disk and copies data
 from the archive.
 In particular, note that
 .Fn archive_read_extract
 uses the
 .Tn struct archive_entry
 structure that you provide it, which may differ from the
 entry just read from the archive.
 In particular, many applications will want to override the
 pathname, file permissions, or ownership.
 .\"
 .Ss Release resources
 See
 .Xr archive_read_free 3 .
 .Pp
 Once you have finished reading data from the archive, you
 should call
 .Fn archive_read_close
 to close the archive, then call
 .Fn archive_read_free
 to release all resources, including all memory allocated by the library.
 .\"
 .Sh EXAMPLE
 The following illustrates basic usage of the library.
 In this example,
 the callback functions are simply wrappers around the standard
 .Xr open 2 ,
 .Xr read 2 ,
 and
 .Xr close 2
 system calls.
 .Bd -literal -offset indent
 void
 list_archive(const char *name)
 {
   struct mydata *mydata;
   struct archive *a;
   struct archive_entry *entry;

   mydata = malloc(sizeof(struct mydata));
   a = archive_read_new();
   mydata->name = name;
   archive_read_support_filter_all(a);
   archive_read_support_format_all(a);
   archive_read_open(a, mydata, myopen, myread, myclose);
   while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
     printf("%s\en",archive_entry_pathname(entry));
     archive_read_data_skip(a);
   }
   archive_read_free(a);
   free(mydata);
 }

 ssize_t
 myread(struct archive *a, void *client_data, const void **buff)
 {
   struct mydata *mydata = client_data;

   *buff = mydata->buff;
   return (read(mydata->fd, mydata->buff, 10240));
 }

 int
 myopen(struct archive *a, void *client_data)
 {
   struct mydata *mydata = client_data;

   mydata->fd = open(mydata->name, O_RDONLY);
   return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
 }

 int
 myclose(struct archive *a, void *client_data)
 {
   struct mydata *mydata = client_data;

   if (mydata->fd > 0)
     close(mydata->fd);
   return (ARCHIVE_OK);
 }
 .Ed
 .\" .Sh ERRORS
 .Sh SEE ALSO
 .Xr tar 1 ,
 .Xr libarchive 3 ,
 .Xr archive_read_new 3 ,
 .Xr archive_read_data 3 ,
 .Xr archive_read_extract 3 ,
 .Xr archive_read_filter 3 ,
 .Xr archive_read_format 3 ,
 .Xr archive_read_header 3 ,
 .Xr archive_read_open 3 ,
 .Xr archive_read_set_options 3 ,
 .Xr archive_util 3 ,
 .Xr tar 5
 .Sh HISTORY
 The
 .Nm libarchive
 library first appeared in
 .Fx 5.3 .
 .Sh AUTHORS
 .An -nosplit
 The
 .Nm libarchive
 library was written by
 .An Tim Kientzle Aq kientzle@acm.org .
 .Sh BUGS
 Many traditional archiver programs treat
 empty files as valid empty archives.
 For example, many implementations of
 .Xr tar 1
 allow you to append entries to an empty file.
 Of course, it is impossible to determine the format of an empty file
 by inspecting the contents, so this library treats empty files as
 having a special
 .Dq empty
 format.
	.\" Copyright (c) 2003-2007 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$
	.\"
	.Dd February 2, 2012
	.Dt ARCHIVE_READ 3
	.Os
	.Sh NAME
	.Nm archive_read
	.Nd functions for reading streaming archives
	.Sh LIBRARY
	Streaming Archive Library (libarchive, -larchive)
	.Sh SYNOPSIS
	.In archive.h
	.Sh DESCRIPTION
	These functions provide a complete API for reading streaming archives.
	The general process is to first create the
	.Tn struct archive
	object, set options, initialize the reader, iterate over the archive
	headers and associated data, then close the archive and release all
	resources.
	.\"
	.Ss Create archive object
	See
	.Xr archive_read_new 3 .
	.Pp
	To read an archive, you must first obtain an initialized
	.Tn struct archive
	object from
	.Fn archive_read_new .
	.\"
	.Ss Enable filters and formats
	See
	.Xr archive_read_filter 3
	and
	.Xr archive_read_format 3 .
	.Pp
	You can then modify this object for the desired operations with the
	various
	.Fn archive_read_set_XXX
	and
	.Fn archive_read_support_XXX
	functions.
	In particular, you will need to invoke appropriate
	.Fn archive_read_support_XXX
	functions to enable the corresponding compression and format
	support.
	Note that these latter functions perform two distinct operations:
	they cause the corresponding support code to be linked into your
	program, and they enable the corresponding auto-detect code.
	Unless you have specific constraints, you will generally want
	to invoke
	.Fn archive_read_support_filter_all
	and
	.Fn archive_read_support_format_all
	to enable auto-detect for all formats and compression types
	currently supported by the library.
	.\"
	.Ss Set options
	See
	.Xr archive_read_set_options 3 .
	.\"
	.Ss Open archive
	See
	.Xr archive_read_open 3 .
	.Pp
	Once you have prepared the
	.Tn struct archive
	object, you call
	.Fn archive_read_open
	to actually open the archive and prepare it for reading.
	There are several variants of this function;
	the most basic expects you to provide pointers to several
	functions that can provide blocks of bytes from the archive.
	There are convenience forms that allow you to
	specify a filename, file descriptor,
	.Ft "FILE *"
	object, or a block of memory from which to read the archive data.
	Note that the core library makes no assumptions about the
	size of the blocks read;
	callback functions are free to read whatever block size is
	most appropriate for the medium.
	.\"
	.Ss Consume archive
	See
	.Xr archive_read_header 3 ,
	.Xr archive_read_data 3
	and
	.Xr archive_read_extract 3 .
	.Pp
	Each archive entry consists of a header followed by a certain
	amount of data.
	You can obtain the next header with
	.Fn archive_read_next_header ,
	which returns a pointer to an
	.Tn struct archive_entry
	structure with information about the current archive element.
	If the entry is a regular file, then the header will be followed
	by the file data.
	You can use
	.Fn archive_read_data
	(which works much like the
	.Xr read 2
	system call)
	to read this data from the archive, or
	.Fn archive_read_data_block
	which provides a slightly more efficient interface.
	You may prefer to use the higher-level
	.Fn archive_read_data_skip ,
	which reads and discards the data for this entry,
	.Fn archive_read_data_to_file ,
	which copies the data to the provided file descriptor, or
	.Fn archive_read_extract ,
	which recreates the specified entry on disk and copies data
	from the archive.
	In particular, note that
	.Fn archive_read_extract
	uses the
	.Tn struct archive_entry
	structure that you provide it, which may differ from the
	entry just read from the archive.
	In particular, many applications will want to override the
	pathname, file permissions, or ownership.
	.\"
	.Ss Release resources
	See
	.Xr archive_read_free 3 .
	.Pp
	Once you have finished reading data from the archive, you
	should call
	.Fn archive_read_close
	to close the archive, then call
	.Fn archive_read_free
	to release all resources, including all memory allocated by the library.
	.\"
	.Sh EXAMPLE
	The following illustrates basic usage of the library.
	In this example,
	the callback functions are simply wrappers around the standard
	.Xr open 2 ,
	.Xr read 2 ,
	and
	.Xr close 2
	system calls.
	.Bd -literal -offset indent
	void
	list_archive(const char *name)
	{
	struct mydata *mydata;
	struct archive *a;
	struct archive_entry *entry;

	mydata = malloc(sizeof(struct mydata));
	a = archive_read_new();
	mydata->name = name;
	archive_read_support_filter_all(a);
	archive_read_support_format_all(a);
	archive_read_open(a, mydata, myopen, myread, myclose);
	while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
	printf("%s\en",archive_entry_pathname(entry));
	archive_read_data_skip(a);
	}
	archive_read_free(a);
	free(mydata);
	}

	ssize_t
	myread(struct archive a, void client_data, const void **buff)
	{
	struct mydata *mydata = client_data;

	*buff = mydata->buff;
	return (read(mydata->fd, mydata->buff, 10240));
	}

	int
	myopen(struct archive a, void client_data)
	{
	struct mydata *mydata = client_data;

	mydata->fd = open(mydata->name, O_RDONLY);
	return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
	}

	int
	myclose(struct archive a, void client_data)
	{
	struct mydata *mydata = client_data;

	if (mydata->fd > 0)
	close(mydata->fd);
	return (ARCHIVE_OK);
	}
	.Ed
	.\" .Sh ERRORS
	.Sh SEE ALSO
	.Xr tar 1 ,
	.Xr libarchive 3 ,
	.Xr archive_read_new 3 ,
	.Xr archive_read_data 3 ,
	.Xr archive_read_extract 3 ,
	.Xr archive_read_filter 3 ,
	.Xr archive_read_format 3 ,
	.Xr archive_read_header 3 ,
	.Xr archive_read_open 3 ,
	.Xr archive_read_set_options 3 ,
	.Xr archive_util 3 ,
	.Xr tar 5
	.Sh HISTORY
	The
	.Nm libarchive
	library first appeared in
	.Fx 5.3 .
	.Sh AUTHORS
	.An -nosplit
	The
	.Nm libarchive
	library was written by
	.An Tim Kientzle Aq kientzle@acm.org .
	.Sh BUGS
	Many traditional archiver programs treat
	empty files as valid empty archives.
	For example, many implementations of
	.Xr tar 1
	allow you to append entries to an empty file.
	Of course, it is impossible to determine the format of an empty file
	by inspecting the contents, so this library treats empty files as
	having a special
	.Dq empty
	format.