view release on metacpan or  search on metacpan

lib/Archive/Libarchive/XS/Function.pod  view on Meta::CPAN

you invoke this on every returned path, you'll get a full logical
traversal.

=head2 archive_read_disk_entry_from_file

 my $status = archive_read_disk_entry_from_file($archive, $entry, $fh, undef);
 my $status = archive_read_disk_entry_from_file($archive, $entry, $fh, \@stat);
 my $status = archive_read_disk_entry_from_file($archive, $entry, undef, \@stat);

Populates a struct archive_entry object with information about a particular file.  The archive_entry object must have already been created with L<archive_entry_new|Archive::Libarchive::XS::Function#archive_entry_new> and at least one of the
source path or path fields must already be set.  (If both are set, the source path will be used.)

Information is read from disk using the path name from the struct archive_entry object.  If a file handle ($fh) is provided, some information will be obtained using that file handle, on
platforms that support the appropriate system calls.

Note: The C API supports passing in a stat structure for some performance benefits.  Currently this is unsupported in the Perl version, and you must pass undef in as the forth argument,
for possible future compatibility.

Where necessary, user and group ids are converted to user and group names using the currently registered lookup functions above.  This affects the file ownership fields and ACL values in the
struct archive_entry object.

=head2 archive_read_disk_gname

 my $string = archive_read_disk_gname($archive, $gid);

Returns a group name given a gid value.  By default always
returns C<undef>.

=head2 archive_read_disk_new

 my $archive = archive_read_disk_new();

Allocates and initializes an archive object suitable for reading object information
from disk.

=head2 archive_read_disk_open

 my $status = archive_read_disk_open($archive, $string)

Allocates and initializes an archive object suitable for reading objects from disk.

=head2 archive_read_disk_set_atime_restored

 my $status = archive_read_disk_set_atime_restored($archive);

Request that the access time of the entry visited by traversal be restored.

=head2 archive_read_disk_set_behavior

 my $status = archive_read_disk_set_behavior($archive, $flags);

Undocumented libarchive function.

=head2 archive_read_disk_set_gname_lookup

 my $status = archive_read_disk_set_gname_lookup($archive, $data, $lookup_callback, $cleanup_callback);

Register a callback for the lookup of GID from group names.  In order to deregister call
C<archive_read_disk_set_gname_lookup> with both callback functions set to C<undef>.

See L<Archive::Libarchive::XS::Callback> for calling conventions for the lookup and cleanup callbacks.

=head2 archive_read_disk_set_standard_lookup

 my $status = archive_read_disk_set_standard_lookup($archive);

This convenience function installs a standard set of user and group name lookup functions.
These functions use C<getpwuid> and C<getgrgid> to convert ids to names, defaulting to C<undef>.
if the names cannot be looked up.  These functions also implement a simple memory cache to
reduce the number of calls to C<getpwuid> and C<getgrgid>.

=head2 archive_read_disk_set_symlink_hybrid

 my $status = archive_read_disk_set_symlink_hybrid($archive);

This sets the mode used for handling symbolic links.  The "hybrid" mode currently
behaves identically to the "logical" mode.

=head2 archive_read_disk_set_symlink_logical

 my $status = archive_read_disk_set_symlink_logical($archive);

This sets the mode used for handling symbolic links.  The "logical" mode follows
all symbolic links.

=head2 archive_read_disk_set_symlink_physical

 my $status = archive_read_disk_set_symlink_physical($archive);

This sets the mode used for handling symbolic links.  The "physical" mode does not
follow any symbolic links.

=head2 archive_read_disk_set_uname_lookup

 my $status = archive_read_disk_set_uname_lookup($archive, $data, $lookup_callback, $cleanup_callback);

Register a callback for the lookup of UID from user names.  In order to deregister call
C<archive_read_disk_setugname_lookup> with both callback functions set to C<undef>.

See L<Archive::Libarchive::XS::Callback> for calling conventions for the lookup and cleanup callbacks.

=head2 archive_read_disk_uname

 my $string = archive_read_disk_uname($archive, $gid);

Returns a user name given a uid value.  By default always
returns C<undef>.

=head2 archive_read_extract

 my $status = archive_read_extract($archive, $entry, $flags);

A convenience function that wraps the corresponding archive_write_disk interfaces.  The first call to L<archive_read_extract|Archive::Libarchive::XS::Function#archive_read_extract> creates a restore object using L<archive_write_disk_new|Archive::Liba...
L<archive_write_disk_set_standard_lookup|Archive::Libarchive::XS::Function#archive_write_disk_set_standard_lookup>, then transparently invokes L<archive_write_disk_set_options|Archive::Libarchive::XS::Function#archive_write_disk_set_options>, L<archi...
create the entry on disk and copy data into it.  The flags argument is passed unmodified to L<archive_write_disk_set_options|Archive::Libarchive::XS::Function#archive_write_disk_set_options>.

=head2 archive_read_extract2

 my $status = archive_read_extract2($archive1, $entry, $archive2);

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
L<archive_write_disk_set_group_lookup|Archive::Libarchive::XS::Function#archive_write_disk_set_group_lookup>, and L<archive_write_disk_set_user_lookup|Archive::Libarchive::XS::Function#archive_write_disk_set_user_lookup>.  Note that L<archive_read_ex...
L<archive_write_disk_set_options|Archive::Libarchive::XS::Function#archive_write_disk_set_options> to set the restore options yourself.

=head2 archive_read_extract_set_skip_file

 my $status = archive_read_extract_set_skip_file($archive, $dev, $ino);

Record the dev/ino of a file that will not be written.  This is
generally set to the dev/ino of the archive being read.

=head2 archive_read_free

 my $status = archive_read_free($archive);

Invokes L<archive_read_close|Archive::Libarchive::XS::Function#archive_read_close> if it was not invoked manually, then
release all resources.

=head2 archive_read_header_position

 my $offset = archive_read_header_position($archive);

Retrieve the byte offset in UNCOMPRESSED data where last-read
header started.

=head2 archive_read_new

 my $archive = archive_read_new();

Allocates and initializes a archive object suitable for reading from an archive.
Returns an opaque archive which may be a perl style object, or a C pointer
(depending on the implementation), either way, it can be passed into
any of the read functions documented here with an C<$archive> argument.

=head2 archive_read_next_header

 my $status = archive_read_next_header($archive, $entry);

Read the header for the next entry and return an entry object
Returns an opaque archive which may be a perl style object, or a C pointer
(depending on the implementation), either way, it can be passed into
any of the functions documented here with an <$entry> argument.

=head2 archive_read_next_header2

 my $status = archive_read_next_header2($archive, $entry);

Read the header for the next entry and populate the provided entry object.

=head2 archive_read_open

 my $status = archive_read_open($archive, $data, $open_cb, $read_cb, $close_cb);

The same as C<archive_read_open2>, except that the skip callback is assumed to be C<undef>.

=head2 archive_read_open1

 my $status = archive_read_open1($archive);

Opening freezes the callbacks.

=head2 archive_read_open2

 my $status = archive_read_open2($archive, $data, $open_cb, $read_cb, $skip_cb, $close_cb);

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 C<archive_read_open_filename>, C<archive_read_open_FILE>, C<archive_read_open_fd>,
or C<archive_read_open_memory> instead.  The library invokes the client-provided functions to 
obtain raw bytes from the archive.

=head2 archive_read_open_fh

 my $status = archive_read_open_fh($archive, $fh, $block_size);

Like L<archive_read_open_filename|Archive::Libarchive::XS::Function#archive_read_open_filename>, except that it accepts a file handle and block
size rather than a filename.  Note that the file handle will not be automatically
closed at end-of-archive.

If not specified, a block size of 10240 will be used.

There is no corresponding archive_read_open_fh in the C version of libarchive.
This is provided in the place of C<archive_read_open_FILE> and C<archive_read_open_fd>,
which are not in the Perl bindings for libarchive.

=head2 archive_read_open_filename

 my $status = archive_read_open_filename($archive, $filename, $block_size);

Like C<archive_read_open>, except that it accepts a simple filename
and a block size.  This function is safe for use with tape drives
or other blocked devices.

If you pass in C<undef> as the C<$filename>, libarchive will use
standard in as the input archive.

=head2 archive_read_open_filenames

 my $status = archive_read_open_filenames($archive, \@filenames, $block_size);

Use this for reading multivolume files by filenames.

=head2 archive_read_open_memory

 my $status = archive_read_open_memory($archive, $buffer);

Like C<archive_read_open>, except that it uses a Perl scalar that holds the 
content of the archive.  This function does not make a copy of the data stored 
in C<$buffer>, so you should not modify the buffer until you have free the 
archive using C<archive_read_free>.

Bad things will happen if the buffer falls out of scope and is deallocated
before you free the archive, so make sure that there is a reference to the
buffer somewhere in your programmer until C<archive_read_free> is called.

=head2 archive_read_set_callback_data

 my $status = archive_read_set_callback_data($archive, $data);

Set the client data for callbacks.

=head2 archive_read_set_close_callback

 my $status = archive_read_set_close_callback($archive, $callback);

Set the close callback for the archive object.

=head2 archive_read_set_filter_option

 my $status = archive_read_set_filter_option($archive, $module, $option, $value);

Specifies an option that will be passed to currently-registered filters 
(including decompression filters).

If option and value are both C<undef>, these functions will do nothing 
and C<ARCHIVE_OK> will be returned.  If option is C<undef> but value is 
not, these functions will do nothing and C<ARCHIVE_FAILED> will be 
returned.

If module is not C<undef>, option and value will be provided to the filter 
or reader named module.  The return value will be that of the module.  
If there is no such module, C<ARCHIVE_FAILED> will be returned.

If module is C<NULL>, option and value will be provided to every registered 
module.  If any module returns C<ARCHIVE_FATAL>, this value will be 
returned immediately.  Otherwise, C<ARCHIVE_OK> will be returned if any 
module accepts the option, and C<ARCHIVE_FAILED> in all other cases.

=head2 archive_read_set_format

 my $status = archive_read_set_format($archive, $format);

Undocumented libarchive function.

=head2 archive_read_set_format_option

 my $status = archive_read_set_format_option($archive, $module, $option, $value);

Specifies an option that will be passed to currently-registered format 
readers.

If option and value are both C<undef>, these functions will do nothing 
and C<ARCHIVE_OK> will be returned.  If option is C<undef> but value is 
not, these functions will do nothing and C<ARCHIVE_FAILED> will be 
returned.

If module is not C<undef>, option and value will be provided to the filter 
or reader named module.  The return value will be that of the module.  
If there is no such module, C<ARCHIVE_FAILED> will be returned.

If module is C<NULL>, option and value will be provided to every registered 
module.  If any module returns C<ARCHIVE_FATAL>, this value will be 
returned immediately.  Otherwise, C<ARCHIVE_OK> will be returned if any 
module accepts the option, and C<ARCHIVE_FAILED> in all other cases.

=head2 archive_read_set_open_callback($archive, $callback)

 my $status = archive_read_set_open_callback($archive, $callback);

Set the open callback for the archive object.

lib/Archive/Libarchive/XS/Function.pod  view on Meta::CPAN

=head2 archive_read_support_format_iso9660

 my $status = archive_read_support_format_iso9660($archive);

Enable iso9660 archive format.

=head2 archive_read_support_format_lha

 my $status = archive_read_support_format_lha($archive);

Enable lha archive format.

=head2 archive_read_support_format_mtree

 my $status = archive_read_support_format_mtree($archive);

Enable mtree archive format.

=head2 archive_read_support_format_rar

 my $status = archive_read_support_format_rar($archive);

Enable rar archive format.

=head2 archive_read_support_format_raw

 my $status = archive_read_support_format_raw($archive);

Enable raw archive format.

=head2 archive_read_support_format_tar

 my $status = archive_read_support_format_tar($archive);

Enable tar archive format.

=head2 archive_read_support_format_xar

 my $status = archive_read_support_format_xar($archive);

Enable xar archive format.

=head2 archive_read_support_format_zip

 my $status = archive_read_support_format_zip($archive);

Enable zip archive format.

=head2 archive_seek_data

 my $count_or_status = archive_seek_data($archive, $offset, $whence);

Seek within the body of an entry.  Similar to C<lseek>.

=head2 archive_set_error

 my $status = archive_set_error($archive, $errno, $format, @args);

Sets the numeric error code and error description that will be returned by
L<archive_errno|Archive::Libarchive::XS::Function#archive_errno> and L<archive_error_string|Archive::Libarchive::XS::Function#archive_error_string>.  This function should be
used within I/O callbacks to set system-specific error codes and error
descriptions.  This function accepts a printf-like format string and
arguments (via perl's L<sprintf|perlfunc#sprintf>.

=head2 archive_version_number

 my $version = archive_version_number();

Return the libarchive version as an integer.

=head2 archive_version_string

 my $string = archive_version_string();

Return the libarchive as a version.

Returns a string value.

=head2 archive_write_add_filter

 my $status = archive_write_add_filter($archive, $code);

A convenience function to set the filter based on the code.

=head2 archive_write_add_filter_b64encode

 my $status = archive_write_add_filter_b64encode($archive);

Add b64encode filter

=head2 archive_write_add_filter_by_name

 my $status = archive_write_add_filter_by_name($archive, $name);

A convenience function to set the filter based on the name.

=head2 archive_write_add_filter_bzip2

 my $status = archive_write_add_filter_bzip2($archive);

Add bzip2 filter

=head2 archive_write_add_filter_compress

 my $status = archive_write_add_filter_compress($archive);

Add compress filter

=head2 archive_write_add_filter_grzip

 my $status = archive_write_add_filter_grzip($archive);

Add grzip filter

=head2 archive_write_add_filter_gzip

 my $status = archive_write_add_filter_gzip($archive);

Add gzip filter

=head2 archive_write_add_filter_lrzip

 my $status = archive_write_add_filter_lrzip($archive);

Add lrzip filter

=head2 archive_write_add_filter_lzip

 my $status = archive_write_add_filter_lzip($archive);

Add lzip filter

=head2 archive_write_add_filter_lzma

 my $status = archive_write_add_filter_lzma($archive);

Add lzma filter

=head2 archive_write_add_filter_lzop

 my $status = archive_write_add_filter_lzop($archive);

Add lzop filter

=head2 archive_write_add_filter_none

 my $status = archive_write_add_filter_none($archive);

Add none filter

=head2 archive_write_add_filter_program

 my $status = archive_write_add_filter_program($archive, $cmd);

The archive will be fed into the specified compression program. 
The output of that program is blocked and written to the client
write callbacks.

=head2 archive_write_add_filter_uuencode

 my $status = archive_write_add_filter_uuencode($archive);

Add uuencode filter

=head2 archive_write_add_filter_xz

 my $status = archive_write_add_filter_xz($archive);

Add xz filter

=head2 archive_write_close

 my $status = archive_write_close($archive)

Complete the archive and invoke the close callback.

=head2 archive_write_data

 my $status = archive_write_data($archive, $buffer);

Write data corresponding to the header just written.

This function returns the number of bytes actually written, or -1 on error.

=head2 archive_write_data_block

 my $count_or_status = archive_write_data_block($archive, $buffer, $offset);

Writes the buffer to the current entry in the given archive
starting at the given offset.

=head2 archive_write_disk_gid

 my $int64 = archive_write_disk_gid($archive, $string, $int64);

Undocumented libarchive function.

=head2 archive_write_disk_new

 my $archive = archive_write_disk_new();

Allocates and initializes a struct archive object suitable for
writing objects to disk.

Returns an opaque archive which may be a perl style object, or a C pointer
(Depending on the implementation), either way, it can be passed into
any of the write functions documented here with an C<$archive> argument.

=head2 archive_write_disk_set_group_lookup

 my $status = archive_write_disk_set_group_lookup($archive, $data, $lookup_callback, $cleanup_callback);

Register a callback for the lookup of group names from group id numbers.  In order to deregister
call C<archive_write_disk_set_group_lookup> with both callback functions set to C<undef>.

See L<Archive::Libarchive::XS::Callback> for calling conventions for the lookup and cleanup callbacks.

=head2 archive_write_disk_set_options

 my $status = archive_write_disk_set_options($archive, $flags);

The options field consists of a bitwise OR of one or more of the 
following values:

=over 4

=item ARCHIVE_EXTRACT_OWNER

=item ARCHIVE_EXTRACT_PERM

=item ARCHIVE_EXTRACT_TIME

=item ARCHIVE_EXTRACT_NO_OVERWRITE

=item ARCHIVE_EXTRACT_UNLINK

=item ARCHIVE_EXTRACT_ACL

=item ARCHIVE_EXTRACT_FFLAGS

=item ARCHIVE_EXTRACT_XATTR

=item ARCHIVE_EXTRACT_SECURE_SYMLINKS

=item ARCHIVE_EXTRACT_SECURE_NODOTDOT

=item ARCHIVE_EXTRACT_SPARSE

=back

=head2 archive_write_disk_set_skip_file

 my $status = archive_write_disk_set_skip_file($archive, $device, $inode);

Records the device and inode numbers of a file that should not be 
overwritten.  This is typically used to ensure that an extraction 
process does not overwrite the archive from which objects are being 
read.  This capability is technically unnecessary but can be a 
significant performance optimization in practice.

=head2 archive_write_disk_set_standard_lookup

 my $status = archive_write_disk_set_standard_lookup($archive);

This convenience function installs a standard set of user and
group lookup functions.  These functions use C<getpwnam> and
C<getgrnam> to convert names to ids, defaulting to the ids
if the names cannot be looked up.  These functions also implement
a simple memory cache to reduce the number of calls to 
C<getpwnam> and C<getgrnam>.

=head2 archive_write_disk_set_user_lookup

 my $status = archive_write_disk_set_user_lookup($archive, $data, $lookup_callback, $cleanup_callback);

Register a callback for the lookup of user names from user id numbers.  In order to deregister
call C<archive_write_disk_set_user_lookup> with both callback functions set to C<undef>.

See L<Archive::Libarchive::XS::Callback> for calling conventions for the lookup and cleanup callbacks.

=head2 archive_write_disk_uid

 my $int64 = archive_write_disk_uid($archive, $string, $int64);

Undocumented libarchive function.

=head2 archive_write_fail

 my $status = archive_write_fail($archive);

Marks the archive as FATAL so that a subsequent C<free> operation
won't try to C<close> cleanly.  Provides a fast abort capability
when the client discovers that things have gone wrong.

=head2 archive_write_finish_entry

 my $status = archive_write_finish_entry($archive)

Close out the entry just written.  Ordinarily, 
clients never need to call this, as it is called 
automatically by C<archive_write_next_header> and 
C<archive_write_close> as needed.  However, some
file attributes are written to disk only after 
the file is closed, so this can be necessary 
if you need to work with the file on disk right away.

=head2 archive_write_free

 my $status = archive_write_free($archive);

Invokes C<archive_write_close> if it was not invoked manually, then
release all resources.

=head2 archive_write_get_bytes_in_last_block

 my $count = archive_write_get_bytes_per_block($archive);

Retrieve the currently-set value for last block size.  A value of -1 
here indicates that the library should use default values.

=head2 archive_write_get_bytes_per_block

 my $count = archive_write_get_bytes_per_block($archive);

Retrieve the block size to be used for writing.  A value of -1 here 
indicates that the library should use default values.  A value of zero 
indicates that internal blocking is suppressed.

=head2 archive_write_header

 my $status = archive_write_header($archive, $entry);

Build and write a header using the data in the provided struct archive_entry structure.
You can use C<archive_entry_new> to create an C<$entry> object and populate it with
C<archive_entry_set*> functions.

=head2 archive_write_new

 my $archive = archive_write_new();