new

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

Create a new archive read object.

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.

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.

open_filename

 # archive_read_open_filename
 my $int = $r->open_filename($string, $size_t);

Open a single-file archive. The $size_t argument is the block size.

open_filenames

 # archive_read_open_filenames
 my $int = $r->open_filenames(\@filenames, $size_t);

Open a multi-file archive (typically for RAR format). The $size_t argument is the block size.

next_header

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

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

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.

read_data_block

 # archive_read_data_block
 my $int = $r->read_data_block(\$buffer, \$offset);

A zero-copy version of archive_read_data that also exposes the file offset of each returned block. Note that the client has no way to specify the desired size of the block. The API does guarantee that offsets will be strictly increasing and that returned blocks will not overlap.

Gotcha with this method is that it returns "ARCHIVE_EOF" when there is no more data to read instead of the number of bytes. The size can be determined from the length of the newly resized $buffer.

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

set_passphrase_callback

 # archive_read_set_passphrase_callback
 my $int = $r->set_passphrase_callback(sub ($r) {
   ...
   return $passphrase;
 });

Set a callback that will be called when a passphrase is required, for example with a .zip file with encrypted entries.