head	1.9;
access;
symbols
	libarchive-3-8-10:1.1.1.8
	pkgsrc-2026Q3:1.8.0.22
	pkgsrc-2026Q3-base:1.8
	libarchive-3-8-9:1.1.1.7
	libarchive-3-8-8:1.1.1.7
	pkgsrc-2026Q2:1.8.0.20
	pkgsrc-2026Q2-base:1.8
	libarchive-3-8-7:1.1.1.7
	libarchive-3-8-6:1.1.1.7
	pkgsrc-2026Q1:1.8.0.18
	pkgsrc-2026Q1-base:1.8
	libarchive-3-8-5:1.1.1.7
	libarchive-3-8-4:1.1.1.7
	pkgsrc-2025Q4:1.8.0.16
	pkgsrc-2025Q4-base:1.8
	libarchive-3-8-3:1.1.1.7
	libarchive-3-8-2:1.1.1.7
	pkgsrc-2025Q3:1.8.0.14
	pkgsrc-2025Q3-base:1.8
	libarchive-3-8-1:1.1.1.7
	pkgsrc-2025Q2:1.8.0.12
	pkgsrc-2025Q2-base:1.8
	libarchive-3-8-0:1.1.1.7
	libarchive-3-7-9:1.1.1.7
	pkgsrc-2025Q1:1.8.0.10
	pkgsrc-2025Q1-base:1.8
	pkgsrc-2024Q4:1.8.0.8
	pkgsrc-2024Q4-base:1.8
	libarchive-3-7-7:1.1.1.7
	pkgsrc-2024Q3:1.8.0.6
	pkgsrc-2024Q3-base:1.8
	libarchive-3-7-5:1.1.1.7
	pkgsrc-2024Q2:1.8.0.4
	pkgsrc-2024Q2-base:1.8
	libarchive-3-7-4:1.1.1.7
	libarchive-3-7-3:1.1.1.7
	pkgsrc-2024Q1:1.8.0.2
	pkgsrc-2024Q1-base:1.8
	libarchive-3-7-2:1.1.1.7
	pkgsrc-2023Q4:1.7.0.30
	pkgsrc-2023Q4-base:1.7
	pkgsrc-2023Q3:1.7.0.28
	pkgsrc-2023Q3-base:1.7
	pkgsrc-2023Q2:1.7.0.26
	pkgsrc-2023Q2-base:1.7
	pkgsrc-2023Q1:1.7.0.24
	pkgsrc-2023Q1-base:1.7
	pkgsrc-2022Q4:1.7.0.22
	pkgsrc-2022Q4-base:1.7
	pkgsrc-2022Q3:1.7.0.20
	pkgsrc-2022Q3-base:1.7
	pkgsrc-2022Q2:1.7.0.18
	pkgsrc-2022Q2-base:1.7
	pkgsrc-2022Q1:1.7.0.16
	pkgsrc-2022Q1-base:1.7
	pkgsrc-2021Q4:1.7.0.14
	pkgsrc-2021Q4-base:1.7
	pkgsrc-2021Q3:1.7.0.12
	pkgsrc-2021Q3-base:1.7
	pkgsrc-2021Q2:1.7.0.10
	pkgsrc-2021Q2-base:1.7
	pkgsrc-2021Q1:1.7.0.8
	pkgsrc-2021Q1-base:1.7
	pkgsrc-2020Q4:1.7.0.6
	pkgsrc-2020Q4-base:1.7
	pkgsrc-2020Q3:1.7.0.4
	pkgsrc-2020Q3-base:1.7
	pkgsrc-2020Q2:1.7.0.2
	pkgsrc-2020Q2-base:1.7
	pkgsrc-2020Q1:1.6.0.4
	pkgsrc-2020Q1-base:1.6
	pkgsrc-2019Q4:1.6.0.6
	pkgsrc-2019Q4-base:1.6
	pkgsrc-2019Q3:1.6.0.2
	pkgsrc-2019Q3-base:1.6
	libarchive-3-4-0:1.1.1.6
	libarchive-3-3-3:1.1.1.5
	pkgsrc-2019Q2:1.5.0.18
	pkgsrc-2019Q2-base:1.5
	pkgsrc-2019Q1:1.5.0.16
	pkgsrc-2019Q1-base:1.5
	pkgsrc-2018Q4:1.5.0.14
	pkgsrc-2018Q4-base:1.5
	pkgsrc-2018Q3:1.5.0.12
	pkgsrc-2018Q3-base:1.5
	pkgsrc-2018Q2:1.5.0.10
	pkgsrc-2018Q2-base:1.5
	pkgsrc-2018Q1:1.5.0.8
	pkgsrc-2018Q1-base:1.5
	pkgsrc-2017Q4:1.5.0.6
	pkgsrc-2017Q4-base:1.5
	pkgsrc-2017Q3:1.5.0.4
	pkgsrc-2017Q3-base:1.5
	libarchive-3-3-2:1.1.1.5
	pkgsrc-2017Q2:1.4.0.4
	pkgsrc-2017Q2-base:1.4
	pkgsrc-2017Q1:1.4.0.2
	pkgsrc-2017Q1-base:1.4
	libarchive-3-3-1:1.1.1.4
	pkgsrc-2016Q4:1.3.0.6
	pkgsrc-2016Q4-base:1.3
	pkgsrc-2016Q3:1.3.0.4
	pkgsrc-2016Q3-base:1.3
	pkgsrc-2016Q2:1.3.0.2
	pkgsrc-2016Q2-base:1.3
	libarchive-3-2-1:1.1.1.3
	pkgsrc-2016Q1:1.2.0.10
	pkgsrc-2016Q1-base:1.2
	pkgsrc-2015Q4:1.2.0.8
	pkgsrc-2015Q4-base:1.2
	pkgsrc-2015Q3:1.2.0.6
	pkgsrc-2015Q3-base:1.2
	pkgsrc-2015Q2:1.2.0.4
	pkgsrc-2015Q2-base:1.2
	pkgsrc-2015Q1:1.2.0.2
	pkgsrc-2015Q1-base:1.2
	pkgsrc-2014Q4:1.1.1.2.0.36
	pkgsrc-2014Q4-base:1.1.1.2
	pkgsrc-2014Q3:1.1.1.2.0.34
	pkgsrc-2014Q3-base:1.1.1.2
	pkgsrc-2014Q2:1.1.1.2.0.32
	pkgsrc-2014Q2-base:1.1.1.2
	pkgsrc-2014Q1:1.1.1.2.0.30
	pkgsrc-2014Q1-base:1.1.1.2
	pkgsrc-2013Q4:1.1.1.2.0.28
	pkgsrc-2013Q4-base:1.1.1.2
	pkgsrc-2013Q3:1.1.1.2.0.26
	pkgsrc-2013Q3-base:1.1.1.2
	pkgsrc-2013Q2:1.1.1.2.0.24
	pkgsrc-2013Q2-base:1.1.1.2
	pkgsrc-2013Q1:1.1.1.2.0.22
	pkgsrc-2013Q1-base:1.1.1.2
	pkgsrc-2012Q4:1.1.1.2.0.20
	pkgsrc-2012Q4-base:1.1.1.2
	pkgsrc-2012Q3:1.1.1.2.0.18
	pkgsrc-2012Q3-base:1.1.1.2
	pkgsrc-2012Q2:1.1.1.2.0.16
	pkgsrc-2012Q2-base:1.1.1.2
	pkgsrc-2012Q1:1.1.1.2.0.14
	pkgsrc-2012Q1-base:1.1.1.2
	pkgsrc-2011Q4:1.1.1.2.0.12
	pkgsrc-2011Q4-base:1.1.1.2
	pkgsrc-2011Q3:1.1.1.2.0.10
	pkgsrc-2011Q3-base:1.1.1.2
	pkgsrc-2011Q2:1.1.1.2.0.8
	pkgsrc-2011Q2-base:1.1.1.2
	pkgsrc-2011Q1:1.1.1.2.0.6
	pkgsrc-2011Q1-base:1.1.1.2
	pkgsrc-2010Q4:1.1.1.2.0.4
	pkgsrc-2010Q4-base:1.1.1.2
	pkgsrc-2010Q3:1.1.1.2.0.2
	pkgsrc-2010Q3-base:1.1.1.2
	libarchive-2-8-4:1.1.1.2
	pkgsrc-2010Q2:1.1.1.1.0.4
	pkgsrc-2010Q2-base:1.1.1.1
	pkgsrc-2010Q1:1.1.1.1.0.2
	pkgsrc-2010Q1-base:1.1.1.1
	libarchive-2-8-3:1.1.1.1
	libarchive-2-8-2:1.1.1.1
	libarchive-2-8-0:1.1.1.1
	KIENTZLE:1.1.1;
locks; strict;
comment	@# @;


1.9
date	2026.10.19.12.05.17;	author adam;	state Exp;
branches;
next	1.8;
commitid	R3KJfVxz3NuPb50H;

1.8
date	2024.01.18.18.00.16;	author adam;	state Exp;
branches;
next	1.7;
commitid	hNXpsHx3SuHqsXUE;

1.7
date	2020.05.26.09.16.41;	author nia;	state Exp;
branches;
next	1.6;
commitid	nNhsdZACz3PjmJ9C;

1.6
date	2019.09.22.09.55.08;	author joerg;	state Exp;
branches;
next	1.5;
commitid	FdPvRjF4OzwBwZDB;

1.5
date	2017.08.01.22.26.23;	author joerg;	state Exp;
branches;
next	1.4;
commitid	32clTfkmVE8bPy1A;

1.4
date	2017.02.25.21.11.19;	author joerg;	state Exp;
branches;
next	1.3;
commitid	rW8QfCWrsCO1snHz;

1.3
date	2016.06.20.17.24.57;	author joerg;	state Exp;
branches;
next	1.2;
commitid	ArUvympBjfBseebz;

1.2
date	2015.01.17.12.44.49;	author adam;	state Exp;
branches;
next	1.1;
commitid	yy7e1hLrfmA2pn6y;

1.1
date	2010.02.20.03.49.47;	author joerg;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	2010.02.20.03.49.47;	author joerg;	state Exp;
branches;
next	1.1.1.2;

1.1.1.2
date	2010.07.09.11.53.30;	author joerg;	state Exp;
branches;
next	1.1.1.3;

1.1.1.3
date	2016.06.20.17.12.04;	author joerg;	state Exp;
branches;
next	1.1.1.4;
commitid	rRgm3BqbmbI8aebz;

1.1.1.4
date	2017.02.25.20.54.22;	author joerg;	state Exp;
branches;
next	1.1.1.5;
commitid	ReqPI0ibLYjdmnHz;

1.1.1.5
date	2017.08.01.22.21.12;	author joerg;	state Exp;
branches;
next	1.1.1.6;
commitid	XQwPAFJku336Ny1A;

1.1.1.6
date	2019.09.22.09.51.33;	author joerg;	state Exp;
branches;
next	1.1.1.7;
commitid	5kDbfPbiV3INvZDB;

1.1.1.7
date	2024.01.18.17.37.45;	author adam;	state Exp;
branches;
next	1.1.1.8;
commitid	zDULEPUODGjTkXUE;

1.1.1.8
date	2026.10.19.11.50.39;	author adam;	state Exp;
branches;
next	;
commitid	eS0MvMrTxXQX650H;


desc
@@


1.9
log
@libarchive: updated to 3.8.10

3.8.10

New features:

7z: add Delta, RISCV, ARMTHUMB and IA64 filters for non-lzma archives
libarchive: support digest with nettle 4 and mbedtls 3
tar: add --mode option

Security and Bug Fixes

see ChangeLog
@
text
@ARCHIVE_READ(3) manual page 
== NAME == 
'''archive_read''' 
- functions for reading streaming archives 
== LIBRARY == 
Streaming Archive Library (libarchive, -larchive) 
== SYNOPSIS == 
'''<nowiki>#include <archive.h></nowiki>''' 
== DESCRIPTION == 
These functions provide a complete API for reading streaming archives. 
The general process is to first create the 
'''struct archive''' 
object, set options, initialize the reader, iterate over the archive 
headers and associated data, then close the archive and release all 
resources. 
=== Create archive object=== 
See 
[[ManPageArchiveReadNew3]]. 

To read an archive, you must first obtain an initialized 
'''struct archive''' 
object from 
'''archive_read_new'''(). 
=== Enable filters and formats=== 
See 
[[ManPageArchiveReadFilter3]] 
and 
[[ManPageArchiveReadFormat3]]. 

You can then modify this object for the desired operations with the 
various 
'''archive_read_set_XXX'''() 
and 
'''archive_read_support_XXX'''() 
functions. 
In particular, you will need to invoke appropriate 
'''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 
'''archive_read_support_filter_all'''() 
and 
'''archive_read_support_format_all'''() 
to enable auto-detect for all formats and compression types 
currently supported by the library. 
=== Set options=== 
See 
[[ManPageArchiveReadSetOptions3]]. 
=== Open archive=== 
See 
[[ManPageArchiveReadOpen3]]. 

Once you have prepared the 
'''struct archive''' 
object, you call 
'''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, 
''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. 
=== Consume archive=== 
See 
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadData3]] 
and 
[[ManPageArchiveReadExtract3]]. 

Each archive entry consists of a header followed by a certain 
amount of data. 
You can obtain the next header with 
'''archive_read_next_header'''(), 
which returns a pointer to an 
'''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 
'''archive_read_data'''() 
(which works much like the 
[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]] 
system call) 
to read this data from the archive, or 
'''archive_read_data_block'''() 
which provides a slightly more efficient interface. 
You may prefer to use the higher-level 
'''archive_read_data_skip'''(), 
which reads and discards the data for this entry, 
'''archive_read_data_into_fd'''(), 
which copies the data to the provided file descriptor, or 
'''archive_read_extract'''(), 
which recreates the specified entry on disk and copies data 
from the archive. 
In particular, note that 
'''archive_read_extract'''() 
uses the 
'''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. 
=== Release resources=== 
See 
[[ManPageArchiveReadFree3]]. 

Once you have finished reading data from the archive, you 
should call 
'''archive_read_close'''() 
to close the archive, then call 
'''archive_read_free'''() 
to release all resources, including all memory allocated by the library. 
== EXAMPLES == 
The following illustrates basic usage of the library. 
In this example, 
the callback functions are simply wrappers around the standard 
[[open(2)|http://www.freebsd.org/cgi/man.cgi?query=open&sektion=2]], 
[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]], 
and 
[[close(2)|http://www.freebsd.org/cgi/man.cgi?query=close&sektion=2]] 
system calls. 
```text
void
list_archive(const char *name)
{
  struct mydata *mydata;
  struct archive *a;
  struct archive_entry *entry;
  mydata = malloc(sizeof(*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);
}
la_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);
}
```
== SEE ALSO == 
[[ManPageBsdtar1]], 
[[ManPageArchiveReadData3]], 
[[ManPageArchiveReadExtract3]], 
[[ManPageArchiveReadFilter3]], 
[[ManPageArchiveReadFormat3]], 
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadNew3]], 
[[ManPageArchiveReadOpen3]], 
[[ManPageArchiveReadSetOptions3]], 
[[ManPageArchiveUtil3]], 
[[ManPageLibarchive3]], 
[[ManPageTar5]] 
== HISTORY == 
The 
'''libarchive''' 
library first appeared in 
FreeBSD 5.3. 
== AUTHORS == 
The 
'''libarchive''' 
library was written by 
Tim Kientzle  &lt;kientzle@@acm.org.&gt; 
== BUGS == 
Many traditional archiver programs treat 
empty files as valid empty archives. 
For example, many implementations of 
[[ManPageBsdtar1]] 
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 
"empty" 
format. 
@


1.8
log
@libarchive: updated to 3.7.2

Libarchive 3.7.2 is a security, bugfix and feature release.

Security fixes:

Multiple vulnerabilities have been fixed in the PAX writer (1b4e0d0)
Important bugfixes:

bsdunzip(1) now correctly handles arguments following an -x after the zipfile
New features:

bsdunzip(1) now supports the "--version" flag
7-zip reader now translates Windows permissions into UNIX permissions
uudecode filter in raw mode now supports file name and file mode
zstd filter now supports the "long" write option


Libarchive 3.7.1 is a security, feature and bugfix release.

Security fixes:

SEGV and stack buffer overflow in verbose mode of cpio
Feature updates:

bsdunzip updated to match latest upstream code
Important bugfixes:

miscellaneous functional bugfixes
build fixes on multiple platforms


Libarchive 3.7.0 is a feature and bugfix release.

New features:

bsdunzip: new tool ported from FreeBSD
drop-in replacement for Info-ZIP unzip, not yet ported for Windows
7zip reader: support for Zstandard compression
7zip reader: support for ARM64 filter
zstd filter: support for multi-frame zstd archives
Other notable bugfixes and improvements:

pax: fix year 2038 problem on platforms with 64-bit time_t
Windows: Universal Windows Platform (UWP) fixes and improvements
Windows: bcrypt usage fixes and improvements
Windows: time function usage fixes and improvements
@
text
@d139 1
a139 1
  mydata = malloc(sizeof(struct mydata));
@


1.7
log
@libarchive: Update to 3.4.3

Libarchive 3.4.3 is a feature and bugfix release.

New features:

    support for pzstd compressed files (#1357)
    support for RHT.security.selinux tar extended attribute (#1348)

Important bugfixes:

    various zstd fixes and improvements (#1342 #1352 #1359)
    child process handling fixes (#1372)

Libarchive 3.4.2 is a feature and security release.

New features:

    support for atomic file extraction (bsdtar -x --safe-writes) (#1289)
    support for mbed TLS (PolarSSL) (#1301)

Important bugfixes:

    security fixes in RAR5 reader (#1280 #1326)
    compression buffer fix in XAR writer (#1317)
    fix uname and gname longer than 32 characters in PAX writer (#1319)
    fix segfault when archiving hard links in ISO9660 and XAR writers (#1325)
    fix support for extracting 7z archive entries with Delta filter (#987)

Libarchive 3.4.1 is a feature and security release.

New features:

    Unicode filename support for reading lha/lzh archives
    New pax write option "xattrhdr"

Important bugfixes:

    security fixes in wide string processing (#1276 #1298)
    security fixes in RAR5 reader (#1212 #1217 #1296)
    security fixes and optimizations to write filter logic (#351)
    security fix related to use of readlink(2) (1dae5a5)
    sparse file handling fixes (#1218 #1260)

Thanks to all contributors and bug reporters.
Special thanks to Christos Zoulas (@@zoulasc) from NetBSD for the atomic file extraction feature.
@
text
@d18 1
a18 1
[[ManPagerchiveeadew3]]. 
d26 1
a26 1
[[ManPagerchiveeadilter3]] 
d28 1
a28 1
[[ManPagerchiveeadormat3]]. 
d52 1
a52 1
[[ManPagerchiveeadetptions3]]. 
d55 1
a55 1
[[ManPagerchiveeadpen3]]. 
d75 2
a76 2
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadata3]] 
d78 1
a78 1
[[ManPagerchiveeadxtract3]]. 
d115 1
a115 1
[[ManPagerchiveeadree3]]. 
d177 10
a186 10
[[ManPagerchiveeadata3]], 
[[ManPagerchiveeadxtract3]], 
[[ManPagerchiveeadilter3]], 
[[ManPagerchiveeadormat3]], 
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadew3]], 
[[ManPagerchiveeadpen3]], 
[[ManPagerchiveeadetptions3]], 
[[ManPagerchivetil3]], 
[[ManPageibarchive3]], 
@


1.6
log
@Update for libarchive-3.4.0:
- improvements for Android APK and JAR archives
- better support for non-recursive list and extract
- tar --exclude-vcs support
- fixes for file attributes and flags handling
- zipx support
- rar 5.0 reader
@
text
@d18 1
a18 1
[[ManPageArchiveReadNew3]]. 
d26 1
a26 1
[[ManPageArchiveReadFilter3]] 
d28 1
a28 1
[[ManPageArchiveReadFormat3]]. 
d52 1
a52 1
[[ManPageArchiveReadSetOptions3]]. 
d55 1
a55 1
[[ManPageArchiveReadOpen3]]. 
d75 2
a76 2
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadData3]] 
d78 1
a78 1
[[ManPageArchiveReadExtract3]]. 
d115 1
a115 1
[[ManPageArchiveReadFree3]]. 
d123 1
a123 1
== EXAMPLE == 
d177 10
a186 10
[[ManPageLibarchive3]], 
[[ManPageArchiveReadNew3]], 
[[ManPageArchiveReadData3]], 
[[ManPageArchiveReadExtract3]], 
[[ManPageArchiveReadFilter3]], 
[[ManPageArchiveReadFormat3]], 
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadOpen3]], 
[[ManPageArchiveReadSetOptions3]], 
[[ManPageArchiveUtil3]], 
@


1.5
log
@Merge for libarchive-3.3.2.
@
text
@d18 1
a18 1
[[ManPagerchiveeadew3]]. 
d26 1
a26 1
[[ManPagerchiveeadilter3]] 
d28 1
a28 1
[[ManPagerchiveeadormat3]]. 
d52 1
a52 1
[[ManPagerchiveeadetptions3]]. 
d55 1
a55 1
[[ManPagerchiveeadpen3]]. 
d75 2
a76 2
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadata3]] 
d78 1
a78 1
[[ManPagerchiveeadxtract3]]. 
d115 1
a115 1
[[ManPagerchiveeadree3]]. 
d177 10
a186 10
[[ManPageibarchive3]], 
[[ManPagerchiveeadew3]], 
[[ManPagerchiveeadata3]], 
[[ManPagerchiveeadxtract3]], 
[[ManPagerchiveeadilter3]], 
[[ManPagerchiveeadormat3]], 
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadpen3]], 
[[ManPagerchiveeadetptions3]], 
[[ManPagerchivetil3]], 
@


1.4
log
@Merge libarchive-3.3.1.
@
text
@d18 1
a18 1
[[ManPageArchiveReadNew3]]. 
d26 1
a26 1
[[ManPageArchiveReadFilter3]] 
d28 1
a28 1
[[ManPageArchiveReadFormat3]]. 
d52 1
a52 1
[[ManPageArchiveReadSetOptions3]]. 
d55 1
a55 1
[[ManPageArchiveReadOpen3]]. 
d75 2
a76 2
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadData3]] 
d78 1
a78 1
[[ManPageArchiveReadExtract3]]. 
d115 1
a115 1
[[ManPageArchiveReadFree3]]. 
d177 10
a186 10
[[ManPageLibarchive3]], 
[[ManPageArchiveReadNew3]], 
[[ManPageArchiveReadData3]], 
[[ManPageArchiveReadExtract3]], 
[[ManPageArchiveReadFilter3]], 
[[ManPageArchiveReadFormat3]], 
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadOpen3]], 
[[ManPageArchiveReadSetOptions3]], 
[[ManPageArchiveUtil3]], 
@


1.3
log
@Update for libarchive 3.2.1.
@
text
@d18 1
a18 1
[[ManPagerchiveeadew3]]. 
d26 1
a26 1
[[ManPagerchiveeadilter3]] 
d28 1
a28 1
[[ManPagerchiveeadormat3]]. 
d52 1
a52 1
[[ManPagerchiveeadetptions3]]. 
d55 1
a55 1
[[ManPagerchiveeadpen3]]. 
d75 2
a76 2
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadata3]] 
d78 1
a78 1
[[ManPagerchiveeadxtract3]]. 
d115 1
a115 1
[[ManPagerchiveeadree3]]. 
d177 10
a186 10
[[ManPageibarchive3]], 
[[ManPagerchiveeadew3]], 
[[ManPagerchiveeadata3]], 
[[ManPagerchiveeadxtract3]], 
[[ManPagerchiveeadilter3]], 
[[ManPagerchiveeadormat3]], 
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadpen3]], 
[[ManPagerchiveeadetptions3]], 
[[ManPagerchivetil3]], 
@


1.2
log
@Changes 3.1.2:
This is a maintenance update to fix issues with the new RAR seeking
feature. This new release also contains fixes for build failures when
building libarchive using Visual Studio 2012 and MinGW.
@
text
@d18 1
a18 1
'''archive_read_new'''(3). 
d26 1
a26 1
'''archive_read_filter'''(3) 
d28 1
a28 1
'''archive_read_format'''(3). 
d52 1
a52 1
'''archive_read_set_options'''(3). 
d55 1
a55 1
'''archive_read_open'''(3). 
d67 1
a67 1
'''FILE *''' 
d75 2
a76 2
'''archive_read_header'''(3), 
'''archive_read_data'''(3) 
d78 1
a78 1
'''archive_read_extract'''(3). 
d92 1
a92 1
'''read'''(2) 
d100 1
a100 1
'''archive_read_data_to_file'''(), 
d115 1
a115 1
'''archive_read_free'''(3). 
d127 2
a128 2
'''open'''(2), 
'''read'''(2), 
d130 1
a130 1
'''close'''(2) 
d152 1
a152 1
ssize_t
d176 12
a187 12
'''tar'''(1), 
'''libarchive'''(3), 
'''archive_read_new'''(3), 
'''archive_read_data'''(3), 
'''archive_read_extract'''(3), 
'''archive_read_filter'''(3), 
'''archive_read_format'''(3), 
'''archive_read_header'''(3), 
'''archive_read_open'''(3), 
'''archive_read_set_options'''(3), 
'''archive_util'''(3), 
'''tar'''(5) 
d202 1
a202 1
'''tar'''(1) 
@


1.1
log
@Initial revision
@
text
@d1 132
a132 574
#summary archive_read 3 manual page
== NAME ==
*archive_read_new*,
*archive_read_set_filter_options*,
*archive_read_set_format_options*,
*archive_read_set_options*,
*archive_read_support_compression_all*,
*archive_read_support_compression_bzip2*,
*archive_read_support_compression_compress*,
*archive_read_support_compression_gzip*,
*archive_read_support_compression_lzma*,
*archive_read_support_compression_none*,
*archive_read_support_compression_xz*,
*archive_read_support_compression_program*,
*archive_read_support_compression_program_signature*,
*archive_read_support_format_all*,
*archive_read_support_format_ar*,
*archive_read_support_format_cpio*,
*archive_read_support_format_empty*,
*archive_read_support_format_iso9660*,
*archive_read_support_format_mtree,*
*archive_read_support_format_raw,*
*archive_read_support_format_tar*,
*archive_read_support_format_zip*,
*archive_read_open*,
*archive_read_open2*,
*archive_read_open_fd*,
*archive_read_open_FILE*,
*archive_read_open_filename*,
*archive_read_open_memory*,
*archive_read_next_header*,
*archive_read_next_header2*,
*archive_read_data*,
*archive_read_data_block*,
*archive_read_data_skip*,
*archive_read_data_into_buffer*,
*archive_read_data_into_fd*,
*archive_read_extract*,
*archive_read_extract2*,
*archive_read_extract_set_progress_callback*,
*archive_read_close*,
*archive_read_finish*
- functions for reading streaming archives
== SYNOPSIS ==
*#include <archive.h>*
<br>
*struct archive `*`*
<br>
*archive_read_new*(_void_);
<br>
*int*
<br>
*archive_read_support_compression_all*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_bzip2*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_compress*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_gzip*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_lzma*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_none*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_xz*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_compression_program*(_struct archive `*`_, _const char `*`cmd_);
<br>
*int*
<br>
*archive_read_support_compression_program_signature*(_struct archive `*`_, _const char `*`cmd_, _const void `*`signature_, _size_t signature_length_);
<br>
*int*
<br>
*archive_read_support_format_all*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_ar*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_cpio*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_empty*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_iso9660*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_mtree*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_raw*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_tar*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_support_format_zip*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_set_filter_options*(_struct archive `*`_, _const char `*`_);
<br>
*int*
<br>
*archive_read_set_format_options*(_struct archive `*`_, _const char `*`_);
<br>
*int*
<br>
*archive_read_set_options*(_struct archive `*`_, _const char `*`_);
<br>
*int*
<br>
*archive_read_open*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_read_callback `*`_, _archive_close_callback `*`_);
<br>
*int*
<br>
*archive_read_open2*(_struct archive `*`_, _void `*`client_data_, _archive_open_callback `*`_, _archive_read_callback `*`_, _archive_skip_callback `*`_, _archive_close_callback `*`_);
<br>
*int*
<br>
*archive_read_open_FILE*(_struct archive `*`_, _FILE `*`file_);
<br>
*int*
<br>
*archive_read_open_fd*(_struct archive `*`_, _int fd_, _size_t block_size_);
<br>
*int*
<br>
*archive_read_open_filename*(_struct archive `*`_, _const char `*`filename_, _size_t block_size_);
<br>
*int*
<br>
*archive_read_open_memory*(_struct archive `*`_, _void `*`buff_, _size_t size_);
<br>
*int*
<br>
*archive_read_next_header*(_struct archive `*`_, _struct archive_entry `*``*`_);
<br>
*int*
<br>
*archive_read_next_header2*(_struct archive `*`_, _struct archive_entry `*`_);
<br>
*ssize_t*
<br>
*archive_read_data*(_struct archive `*`_, _void `*`buff_, _size_t len_);
<br>
*int*
<br>
*archive_read_data_block*(_struct archive `*`_, _const void `*``*`buff_, _size_t `*`len_, _off_t `*`offset_);
<br>
*int*
<br>
*archive_read_data_skip*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_data_into_buffer*(_struct archive `*`_, _void `*`_, _ssize_t len_);
<br>
*int*
<br>
*archive_read_data_into_fd*(_struct archive `*`_, _int fd_);
<br>
*int*
<br>
*archive_read_extract*(_struct archive `*`_, _struct archive_entry `*`_, _int flags_);
<br>
*int*
<br>
*archive_read_extract2*(_struct archive `*`src_, _struct archive_entry `*`_, _struct archive `*`dest_);
<br>
*void*
<br>
*archive_read_extract_set_progress_callback*(_struct archive `*`_, _void (`*`func)(void `*`)_, _void `*`user_data_);
<br>
*int*
<br>
*archive_read_close*(_struct archive `*`_);
<br>
*int*
<br>
*archive_read_finish*(_struct archive `*`_);
== DESCRIPTION ==
These functions provide a complete API for reading streaming archives.
The general process is to first create the
*struct archive*
object, set options, initialize the reader, iterate over the archive
headers and associated data, then close the archive and release all
resources.
The following summary describes the functions in approximately the
order they would be used:
<dl>
<dt>*archive_read_new*()</dt><dd>
Allocates and initializes a
*struct archive*
object suitable for reading from an archive.
</dd><dt>
*archive_read_support_compression_bzip2*(),
*archive_read_support_compression_compress*(),
*archive_read_support_compression_gzip*(),
*archive_read_support_compression_lzma*(),
*archive_read_support_compression_none*(),
*archive_read_support_compression_xz*()
</dt> <dd>
Enables auto-detection code and decompression support for the
specified compression.
Returns
*ARCHIVE_OK*
if the compression is fully supported, or
*ARCHIVE_WARN*
if the compression is supported only through an external program.
Note that decompression using an external program is usually slower than
decompression through built-in libraries.
Note that
"none"
is always enabled by default.
</dd><dt>*archive_read_support_compression_all*()</dt><dd>
Enables all available decompression filters.
</dd><dt>*archive_read_support_compression_program*()</dt><dd>
Data is fed through the specified external program before being dearchived.
Note that this disables automatic detection of the compression format,
so it makes no sense to specify this in conjunction with any other
decompression option.
</dd><dt>*archive_read_support_compression_program_signature*()</dt><dd>
This feeds data through the specified external program
but only if the initial bytes of the data match the specified
signature value.
</dd><dt>
*archive_read_support_format_all*(),
*archive_read_support_format_ar*(),
*archive_read_support_format_cpio*(),
*archive_read_support_format_empty*(),
*archive_read_support_format_iso9660*(),
*archive_read_support_format_mtree*(),
*archive_read_support_format_tar*(),
*archive_read_support_format_zip*()
</dt> <dd>
Enables support---including auto-detection code---for the
specified archive format.
For example,
*archive_read_support_format_tar*()
enables support for a variety of standard tar formats, old-style tar,
ustar, pax interchange format, and many common variants.
For convenience,
*archive_read_support_format_all*()
enables support for all available formats.
Only empty archives are supported by default.
</dd><dt>*archive_read_support_format_raw*()</dt><dd>
The
"raw"
format handler allows libarchive to be used to read arbitrary data.
It treats any data stream as an archive with a single entry.
The pathname of this entry is
"data ;"
all other entry fields are unset.
This is not enabled by
*archive_read_support_format_all*()
in order to avoid erroneous handling of damaged archives.
</dd><dt>
*archive_read_set_filter_options*(),
*archive_read_set_format_options*(),
*archive_read_set_options*()
</dt> <dd>
Specifies options that will be passed to currently-registered
filters (including decompression filters) and/or format readers.
The argument is a comma-separated list of individual options.
Individual options have one of the following forms:
<dl>
<dt>_option=value_</dt><dd>
The option/value pair will be provided to every module.
Modules that do not accept an option with this name will ignore it.
</dd><dt>_option_</dt><dd>
The option will be provided to every module with a value of
"1".
</dd><dt>_!option_</dt><dd>
The option will be provided to every module with a NULL value.
</dd><dt>_module:option=value_, _module:option_, _module:!option_</dt><dd>
As above, but the corresponding option and value will be provided
only to modules whose name matches
_module_.
</dd></dl>
The return value will be
*ARCHIVE_OK*
if any module accepts the option, or
*ARCHIVE_WARN*
if no module accepted the option, or
*ARCHIVE_FATAL*
if there was a fatal error while attempting to process the option.

The currently supported options are:
<dl>
<dt>Format iso9660</dt><dd>
<dl>
<dt>*joliet*</dt><dd>
Support Joliet extensions.
Defaults to enabled, use
*!joliet*
to disable.
</dd></dl>
</dd></dl>
</dd><dt>*archive_read_open*()</dt><dd>
The same as
*archive_read_open2*(),
except that the skip callback is assumed to be
NULL.
</dd><dt>*archive_read_open2*()</dt><dd>
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
*archive_read_open_filename*(),
*archive_read_open_FILE*(),
*archive_read_open_fd*(),
or
*archive_read_open_memory*()
instead.
The library invokes the client-provided functions to obtain
raw bytes from the archive.
</dd><dt>*archive_read_open_FILE*()</dt><dd>
Like
*archive_read_open*(),
except that it accepts a
*FILE `*`*
pointer.
This function should not be used with tape drives or other devices
that require strict I/O blocking.
</dd><dt>*archive_read_open_fd*()</dt><dd>
Like
*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.
</dd><dt>*archive_read_open_file*()</dt><dd>
This is a deprecated synonym for
*archive_read_open_filename*().
</dd><dt>*archive_read_open_filename*()</dt><dd>
Like
*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.
</dd><dt>*archive_read_open_memory*()</dt><dd>
Like
*archive_read_open*(),
except that it accepts a pointer and size of a block of
memory containing the archive data.
</dd><dt>*archive_read_next_header*()</dt><dd>
Read the header for the next entry and return a pointer to
a
*struct archive_entry .*
This is a convenience wrapper around
*archive_read_next_header2*()
that reuses an internal
*struct archive_entry*
object for each request.
</dd><dt>*archive_read_next_header2*()</dt><dd>
Read the header for the next entry and populate the provided
*struct archive_entry .*
</dd><dt>*archive_read_data*()</dt><dd>
Read data associated with the header just read.
Internally, this is a convenience function that calls
*archive_read_data_block*()
and fills any gaps with nulls so that callers see a single
continuous stream of data.
</dd><dt>*archive_read_data_block*()</dt><dd>
Return the next available block of data for this entry.
Unlike
*archive_read_data*(),
the
*archive_read_data_block*()
function avoids copying data and allows you to correctly handle
sparse files, as supported by some archive formats.
The library guarantees that offsets will increase and that blocks
will not overlap.
Note that the blocks returned from this function can be much larger
than the block size read from disk, due to compression
and internal buffer optimizations.
</dd><dt>*archive_read_data_skip*()</dt><dd>
A convenience function that repeatedly calls
*archive_read_data_block*()
to skip all of the data for this archive entry.
</dd><dt>*archive_read_data_into_buffer*()</dt><dd>
This function is deprecated and will be removed.
Use
*archive_read_data*()
instead.
</dd><dt>*archive_read_data_into_fd*()</dt><dd>
A convenience function that repeatedly calls
*archive_read_data_block*()
to copy the entire entry to the provided file descriptor.
</dd><dt>*archive_read_extract*(), *archive_read_extract_set_skip_file*()</dt><dd>
A convenience function that wraps the corresponding
*archive_write_disk*(3)
interfaces.
The first call to
*archive_read_extract*()
creates a restore object using
*archive_write_disk_new*(3)
and
*archive_write_disk_set_standard_lookup*(3),
then transparently invokes
*archive_write_disk_set_options*(3),
*archive_write_header*(3),
*archive_write_data*(3),
and
*archive_write_finish_entry*(3)
to create the entry on disk and copy data into it.
The
_flags_
argument is passed unmodified to
*archive_write_disk_set_options*(3).
</dd><dt>*archive_read_extract2*()</dt><dd>
This is another version of
*archive_read_extract*()
that allows you to provide your own restore object.
In particular, this allows you to override the standard lookup functions
using
*archive_write_disk_set_group_lookup*(3),
and
*archive_write_disk_set_user_lookup*(3).
Note that
*archive_read_extract2*()
does not accept a
_flags_
argument; you should use
*archive_write_disk_set_options*()
to set the restore options yourself.
</dd><dt>*archive_read_extract_set_progress_callback*()</dt><dd>
Sets a pointer to a user-defined callback that can be used
for updating progress displays during extraction.
The progress function will be invoked during the extraction of large
regular files.
The progress function will be invoked with the pointer provided to this call.
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.
</dd><dt>*archive_read_close*()</dt><dd>
Complete the archive and invoke the close callback.
</dd><dt>*archive_read_finish*()</dt><dd>
Invokes
*archive_read_close*()
if it was not invoked manually, then release all resources.
Note: In libarchive 1.x, this function was declared to return
*void ,*
which made it impossible to detect certain errors when
*archive_read_close*()
was invoked implicitly from this function.
The declaration is corrected beginning with libarchive 2.0.
</dd></dl>

Note that the library determines most of the relevant information about
the archive by inspection.
In particular, it automatically detects
*gzip*(1)
or
*bzip2*(1)
compression and transparently performs the appropriate decompression.
It also automatically detects the archive format.

A complete description of the
*struct archive*
and
*struct archive_entry*
objects can be found in the overview manual page for
*libarchive*(3).
== CLIENT CALLBACKS ==
The callback functions must match the following prototypes:
<ul>
<li>
*typedef ssize_t*
*archive_read_callback*(_struct archive `*`_, _void `*`client_data_, _const void `*``*`buffer_)
</li><li>
*typedef int*
*archive_skip_callback*(_struct archive `*`_, _void `*`client_data_, _size_t request_)
</li><li>
*typedef int*
*archive_open_callback*(_struct archive `*`_, _void `*`client_data_)
</li><li>
*typedef int*
*archive_close_callback*(_struct archive `*`_, _void `*`client_data_)
</li></ul>

The open callback is invoked by
*archive_open*().
It should return
*ARCHIVE_OK*
if the underlying file or data source is successfully
opened.
If the open fails, it should call
*archive_set_error*()
to register an error code and message and return
*ARCHIVE_FATAL*.

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
{{{
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
*archive_set_error*()
to register an error code and message and
return -1.

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
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.

The close callback is invoked by archive_close when
the archive processing is complete.
The callback should return
*ARCHIVE_OK*
on success.
On failure, the callback should invoke
*archive_set_error*()
to register an error code and message and
return
*ARCHIVE_FATAL.*
== EXAMPLE ==
The following illustrates basic usage of the library.
In this example,
the callback functions are simply wrappers around the standard
*open*(2),
*read*(2),
and
*close*(2)
system calls.
{{{
d142 1
a142 1
  archive_read_support_compression_all(a);
d146 1
a146 1
    printf("%s\\n",archive_entry_pathname(entry));
d149 1
a149 1
  archive_read_finish(a);
d174 35
a208 79
}}}
== RETURN VALUES ==
Most functions return zero on success, non-zero on error.
The possible return codes include:
*ARCHIVE_OK*
(the operation succeeded),
*ARCHIVE_WARN*
(the operation succeeded but a non-critical error was encountered),
*ARCHIVE_EOF*
(end-of-archive was encountered),
*ARCHIVE_RETRY*
(the operation failed but can be retried),
and
*ARCHIVE_FATAL*
(there was a fatal error; the archive should be closed immediately).
Detailed error codes and textual descriptions are available from the
*archive_errno*()
and
*archive_error_string*()
functions.

*archive_read_new*()
returns a pointer to a freshly allocated
*struct archive*
object.
It returns
NULL
on error.

*archive_read_data*()
returns a count of bytes actually read or zero at the end of the entry.
On error, a value of
*ARCHIVE_FATAL*,
*ARCHIVE_WARN*,
or
*ARCHIVE_RETRY*
is returned and an error code and textual description can be retrieved from the
*archive_errno*()
and
*archive_error_string*()
functions.

The library expects the client callbacks to behave similarly.
If there is an error, you can use
*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
*ARCHIVE_FATAL*
to be returned.)
== SEE ALSO ==
*tar*(1),
*archive*(3),
*archive_util*(3),
*tar*(5)
== HISTORY ==
The
*libarchive*
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The
*libarchive*
library was written by
Tim Kientzle  <kientzle@@acm.org.>
== BUGS ==
Many traditional archiver programs treat
empty files as valid empty archives.
For example, many implementations of
*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
"empty"
format.
@


1.1.1.1
log
@Import libarchive 2.8.0:
- Infrastructure:
  - Allow command line tools as fallback for missing compression
    libraries. If compiled without gzip for example, gunzip will
    be used automatically.
  - Improved support for a number of platforms like high-resolution
    timestamps and Extended Attributes on various Unix systems
  - New convience interface for creating archives based on disk content,
    complement of the archive_write_disk interface.
- Frontends:
  - bsdcpio ready for public consumption
  - hand-written date parser replaces the yacc code
- Filter system:
  - Simplified read filter chains
  - Option support for filters
  - LZMA, XZ, uudecode handled
- Format support:
  - Write support for mtree files based on file system or archive
    content
  - Basic read support for Joliet
  - Write support for zip files
  - Write support for shar archives, both text-only and binary-safe
@
text
@@


1.1.1.2
log
@Import libarchive-2.8.4:
- Improved reliability of hash function detection
- Fix issues on ancient FreeBSD, QNX, ancient NetBSD and Minix
@
text
@d588 1
a588 1
    printf("%s\en",archive_entry_pathname(entry));
@


1.1.1.3
log
@Import libarchive-3.2.1:
- security fixes and other bugfixes
- support for multhreading in xz 5.2+
@
text
@d1 574
a574 132
ARCHIVE_READ(3) manual page 
== NAME == 
'''archive_read''' 
- functions for reading streaming archives 
== LIBRARY == 
Streaming Archive Library (libarchive, -larchive) 
== SYNOPSIS == 
'''<nowiki>#include <archive.h></nowiki>''' 
== DESCRIPTION == 
These functions provide a complete API for reading streaming archives. 
The general process is to first create the 
'''struct archive''' 
object, set options, initialize the reader, iterate over the archive 
headers and associated data, then close the archive and release all 
resources. 
=== Create archive object=== 
See 
[[ManPagerchiveeadew3]]. 

To read an archive, you must first obtain an initialized 
'''struct archive''' 
object from 
'''archive_read_new'''(). 
=== Enable filters and formats=== 
See 
[[ManPagerchiveeadilter3]] 
and 
[[ManPagerchiveeadormat3]]. 

You can then modify this object for the desired operations with the 
various 
'''archive_read_set_XXX'''() 
and 
'''archive_read_support_XXX'''() 
functions. 
In particular, you will need to invoke appropriate 
'''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 
'''archive_read_support_filter_all'''() 
and 
'''archive_read_support_format_all'''() 
to enable auto-detect for all formats and compression types 
currently supported by the library. 
=== Set options=== 
See 
[[ManPagerchiveeadetptions3]]. 
=== Open archive=== 
See 
[[ManPagerchiveeadpen3]]. 

Once you have prepared the 
'''struct archive''' 
object, you call 
'''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, 
''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. 
=== Consume archive=== 
See 
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadata3]] 
and 
[[ManPagerchiveeadxtract3]]. 

Each archive entry consists of a header followed by a certain 
amount of data. 
You can obtain the next header with 
'''archive_read_next_header'''(), 
which returns a pointer to an 
'''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 
'''archive_read_data'''() 
(which works much like the 
[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]] 
system call) 
to read this data from the archive, or 
'''archive_read_data_block'''() 
which provides a slightly more efficient interface. 
You may prefer to use the higher-level 
'''archive_read_data_skip'''(), 
which reads and discards the data for this entry, 
'''archive_read_data_into_fd'''(), 
which copies the data to the provided file descriptor, or 
'''archive_read_extract'''(), 
which recreates the specified entry on disk and copies data 
from the archive. 
In particular, note that 
'''archive_read_extract'''() 
uses the 
'''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. 
=== Release resources=== 
See 
[[ManPagerchiveeadree3]]. 

Once you have finished reading data from the archive, you 
should call 
'''archive_read_close'''() 
to close the archive, then call 
'''archive_read_free'''() 
to release all resources, including all memory allocated by the library. 
== EXAMPLE == 
The following illustrates basic usage of the library. 
In this example, 
the callback functions are simply wrappers around the standard 
[[open(2)|http://www.freebsd.org/cgi/man.cgi?query=open&sektion=2]], 
[[read(2)|http://www.freebsd.org/cgi/man.cgi?query=read&sektion=2]], 
and 
[[close(2)|http://www.freebsd.org/cgi/man.cgi?query=close&sektion=2]] 
system calls. 
```text
d584 1
a584 1
  archive_read_support_filter_all(a);
d591 1
a591 1
  archive_read_free(a);
d594 1
a594 1
la_ssize_t
d616 79
a694 35
```
== SEE ALSO == 
[[ManPageBsdtar1]], 
[[ManPageibarchive3]], 
[[ManPagerchiveeadew3]], 
[[ManPagerchiveeadata3]], 
[[ManPagerchiveeadxtract3]], 
[[ManPagerchiveeadilter3]], 
[[ManPagerchiveeadormat3]], 
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadpen3]], 
[[ManPagerchiveeadetptions3]], 
[[ManPagerchivetil3]], 
[[ManPageTar5]] 
== HISTORY == 
The 
'''libarchive''' 
library first appeared in 
FreeBSD 5.3. 
== AUTHORS == 
The 
'''libarchive''' 
library was written by 
Tim Kientzle  &lt;kientzle@@acm.org.&gt; 
== BUGS == 
Many traditional archiver programs treat 
empty files as valid empty archives. 
For example, many implementations of 
[[ManPageBsdtar1]] 
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 
"empty" 
format. 
@


1.1.1.4
log
@Import libarchive-3.3.1.
@
text
@d18 1
a18 1
[[ManPageArchiveReadNew3]]. 
d26 1
a26 1
[[ManPageArchiveReadFilter3]] 
d28 1
a28 1
[[ManPageArchiveReadFormat3]]. 
d52 1
a52 1
[[ManPageArchiveReadSetOptions3]]. 
d55 1
a55 1
[[ManPageArchiveReadOpen3]]. 
d75 2
a76 2
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadData3]] 
d78 1
a78 1
[[ManPageArchiveReadExtract3]]. 
d115 1
a115 1
[[ManPageArchiveReadFree3]]. 
d177 10
a186 10
[[ManPageLibarchive3]], 
[[ManPageArchiveReadNew3]], 
[[ManPageArchiveReadData3]], 
[[ManPageArchiveReadExtract3]], 
[[ManPageArchiveReadFilter3]], 
[[ManPageArchiveReadFormat3]], 
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadOpen3]], 
[[ManPageArchiveReadSetOptions3]], 
[[ManPageArchiveUtil3]], 
@


1.1.1.5
log
@Import libarchive-3.3.2 + 9de5f3 + f9dacbf:
- Support NFS4 ACLs on Linux
- Bugfixes
@
text
@d18 1
a18 1
[[ManPagerchiveeadew3]]. 
d26 1
a26 1
[[ManPagerchiveeadilter3]] 
d28 1
a28 1
[[ManPagerchiveeadormat3]]. 
d52 1
a52 1
[[ManPagerchiveeadetptions3]]. 
d55 1
a55 1
[[ManPagerchiveeadpen3]]. 
d75 2
a76 2
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadata3]] 
d78 1
a78 1
[[ManPagerchiveeadxtract3]]. 
d115 1
a115 1
[[ManPagerchiveeadree3]]. 
d177 10
a186 10
[[ManPageibarchive3]], 
[[ManPagerchiveeadew3]], 
[[ManPagerchiveeadata3]], 
[[ManPagerchiveeadxtract3]], 
[[ManPagerchiveeadilter3]], 
[[ManPagerchiveeadormat3]], 
[[ManPagerchiveeadeader3]], 
[[ManPagerchiveeadpen3]], 
[[ManPagerchiveeadetptions3]], 
[[ManPagerchivetil3]], 
@


1.1.1.6
log
@Import libarchive 3.4.0
@
text
@d18 1
a18 1
[[ManPageArchiveReadNew3]]. 
d26 1
a26 1
[[ManPageArchiveReadFilter3]] 
d28 1
a28 1
[[ManPageArchiveReadFormat3]]. 
d52 1
a52 1
[[ManPageArchiveReadSetOptions3]]. 
d55 1
a55 1
[[ManPageArchiveReadOpen3]]. 
d75 2
a76 2
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadData3]] 
d78 1
a78 1
[[ManPageArchiveReadExtract3]]. 
d115 1
a115 1
[[ManPageArchiveReadFree3]]. 
d177 10
a186 10
[[ManPageLibarchive3]], 
[[ManPageArchiveReadNew3]], 
[[ManPageArchiveReadData3]], 
[[ManPageArchiveReadExtract3]], 
[[ManPageArchiveReadFilter3]], 
[[ManPageArchiveReadFormat3]], 
[[ManPageArchiveReadHeader3]], 
[[ManPageArchiveReadOpen3]], 
[[ManPageArchiveReadSetOptions3]], 
[[ManPageArchiveUtil3]], 
@


1.1.1.7
log
@Import libarchive 3.7.2
@
text
@d123 1
a123 1
== EXAMPLES == 
d177 2
a183 1
[[ManPageArchiveReadNew3]], 
a186 1
[[ManPageLibarchive3]], 
@


1.1.1.8
log
@libarchive: import version 3.8.10
@
text
@d139 1
a139 1
  mydata = malloc(sizeof(*mydata));
@