The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Archive-Libarchive-0.01
River stage two • 5 direct dependents • 13 total dependents
/ Archive::Libarchive::ArchiveRead

NAME

Archive::Libarchive::ArchiveRead - Libarchive read archive class

VERSION

version 0.01

SYNOPSIS

 use 5.020;
 use Archive::Libarchive qw( :const );
 
 my $r = Archive::Libarchive::ArchiveRead->new;
 $r->support_filter_all;
 $r->support_format_all;
 $r->open_filename("archive.tar", 10240) == ARCHIVE_OK
   or die $r->error_string;
 
 my $e = Archive::Libarchive::Entry->new;
 say $e->pathname while $r->next_header($e) == ARCHIVE_OK;

DESCRIPTION

This class represents an archive instance for reading from archives.

CONSTRUCTOR

new

 # archive_read_new
 my $r = Archive::Libarchive::ArchiveRead->new;

Create a new archive read object.

METHODS

This is a subset of total list of methods available to all archive classes. For the full list see "Archive::Libarchive::ArchiveRead" in Archive::Libarchive::API.

open

 # archive_read_open1
 # archive_read_set_callback_data
 # archive_read_set_close_callback
 # archive_read_set_open_callback
 # archive_read_set_read_callback
 # archive_read_set_seek_callback
 # archive_read_set_skip_callback
 $r->open(%callbacks);

This is a basic open method, which relies on callbacks for its implementation. The only callback that is required is the read callback. The open and close callbacks are made available mostly for the benefit of the caller. The skip and seek callbacks are used if available for some formats like zip to improve performance. All callbacks should return a normal status code, which is ARCHIVE_OK on success.

Unlike the libarchive C-API, this interface doesn't provide a facility for passing in "client" data. In Perl this is implemented using a closure, which should allow you to pass in arbitrary variables via proper scoping.

open
 $r->open(open => sub ($r) {
   ...
 });

Called immediately when the archive is "opened";

read
 $r->open(read => sub ($r, $ref) {
   $$ref = ...;
   ...
   return $size.
 });

Called when new data is required. What is passed in is a scalar reference. You should set this scalar to the next block of data. On success you should return the size of the data in bytes, and on failure return a normal status code.

seek
 $r->open(seek => sub ($r, $offset, $whence) {
   ...
 });

Called to seek to the new location. The $offset and $whence arguments work exactly like the libc fseek function.

skip
 $r->open(skip => sub ($r, $request) {
   ...
 });

Called to skip the next $request bytes. Should return the actual number of bytes skipped on success (which can be less than or equal to $request), and on failure return a normal status code.

close
 $r->open(close => sub ($r) {
   ...
 });

This is called when the archive instance is closed.

next_header

 # archive_read_next_header
 my $code = $r->next_header($e);

Returns the next Archive::Libarchive::Entry object.

open_memory

 # archive_write_open_memory
 my $code = $r->open_memory(\$buffer);

Open's the in-memory archive.

open_FILE

 $r->open_FILE($file_pointer);

This takes either a FFI::C::File, or an opaque pointer to a libc file pointer.

open_perlfile

 $r->open_perlfile(*FILE);

This takes a perl file handle and reads the archive from there.

read_data

 # archive_read_data
 my $size_or_code = $r->read_data(\$buffer, $size);
 my $size_or_code = $r->read_data(\$buffer);

Read in data from the content section of the archive entry. The output is written into $buffer. Up to $size bytes will be read. This will return the number of bytes read on success, zero (0) on EOF and a normal status code on error.

append_filter

 # archive_read_append_filter
 my $int = $r->append_filter($code);

Append filter to manually specify the order in which filters will be applied. This will accept either a string representation of the filter code, or the constant. The constant prefix is ARCHIVE_FILTER_. So for a gzipped file this would be either 'gzip' or ARCHIVE_FILTER_GZIP. For the full list see "CONSTANTS" in Archive::Libarchive::API.

set_format

 # archive_read_set_format
 my $int = $r->set_format($code);

Set the format manually. This will accept either a string representation of the format, or the constant. The constant prefix is ARCHIVE_FORMAT_. So for a tar file this would be either 'tar' or ARCHIVE_FORMAT_TAR.

SEE ALSO

Archive::Libarchive

This is the main top-level module for using libarchive from Perl. It is the best place to start reading the documentation. It pulls in the other classes and libarchive constants so that you only need one use statement to effectively use libarchive.

Archive::Libarchive::API

This contains the full and complete API for all of the Archive::Libarchive classes. Because libarchive has hundreds of methods, the main documentation pages elsewhere only contain enough to be useful, and not to overwhelm.

Archive::Libarchive::Archive

The base class of all archive classes. This includes some common error reporting functionality among other things.

Archive::Libarchive::ArchiveWrite

This class is for creating new archives.

Archive::Libarchive::DiskRead

This class is for reading Archive::Libarchive::Entry objects from disk so that they can be written to Archive::Libarchive::ArchiveWrite objects.

Archive::Libarchive::DiskWrite

This class is for writing Archive::Libarchive::Entry objects to disk that have been written from Archive::Libarchive::ArchiveRead objects.

Archive::Libarchive::Entry

This class represents a file in an archive, or on disk.

Archive::Libarchive::EntryLinkResolver

This class exposes the libarchive link resolver API.

Archive::Libarchive::Match

This class exposes the libarchive match API.

Alien::Libarchive3

If a suitable system libarchive can't be found, then this Alien will be installed to provide it.

libarchive.org

The libarchive project home page.

https://github.com/libarchive/libarchive/wiki

The libarchive project wiki.

https://github.com/libarchive/libarchive/wiki/ManualPages

Some of the libarchive man pages are listed here.

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2021 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.