cmclark00/retro-imager
1
0
Fork 0
mirror of https://github.com/cmclark00/retro-imager.git synced 2025-05-19 08:25:21 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Qt/QML edition

Browse source
This commit is contained in:
Floris Bos 2020-03-04 16:55:40 +01:00
commit d7b361ba44
2168 changed files with 721948 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

2
dependencies/libarchive-3.4.2/doc/wiki/.ignore_me vendored Normal file
View file

@ -0,0 +1,2 @@
*** PLEASE DO NOT DELETE THIS FILE! ***
This file is used to track an otherwise empty directory in git.

133
dependencies/libarchive-3.4.2/doc/wiki/Makefile vendored Normal file
View file

@ -0,0 +1,133 @@
default: all
ManPageArchiveEntry3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry.3 > ManPageArchiveEntry3.wiki
ManPageArchiveEntryAcl3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_acl.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_acl.3 > ManPageArchiveEntryAcl3.wiki
ManPageArchiveEntryLinkify3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_linkify.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_linkify.3 > ManPageArchiveEntryLinkify3.wiki
ManPageArchiveEntryMisc3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_misc.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_misc.3 > ManPageArchiveEntryMisc3.wiki
ManPageArchiveEntryPaths3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_paths.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_paths.3 > ManPageArchiveEntryPaths3.wiki
ManPageArchiveEntryPerms3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_perms.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_perms.3 > ManPageArchiveEntryPerms3.wiki
ManPageArchiveEntryStat3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_stat.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_stat.3 > ManPageArchiveEntryStat3.wiki
ManPageArchiveEntryTime3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_entry_time.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_entry_time.3 > ManPageArchiveEntryTime3.wiki
ManPageArchiveRead3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read.3 > ManPageArchiveRead3.wiki
ManPageArchiveReadAddPassphrase3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_add_passphrase.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_add_passphrase.3 > ManPageArchiveReadAddPassphrase3.wiki
ManPageArchiveReadData3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_data.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_data.3 > ManPageArchiveReadData3.wiki
ManPageArchiveReadDisk3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_disk.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_disk.3 > ManPageArchiveReadDisk3.wiki
ManPageArchiveReadExtract3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_extract.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_extract.3 > ManPageArchiveReadExtract3.wiki
ManPageArchiveReadFilter3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_filter.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_filter.3 > ManPageArchiveReadFilter3.wiki
ManPageArchiveReadFormat3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_format.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_format.3 > ManPageArchiveReadFormat3.wiki
ManPageArchiveReadFree3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_free.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_free.3 > ManPageArchiveReadFree3.wiki
ManPageArchiveReadHeader3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_header.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_header.3 > ManPageArchiveReadHeader3.wiki
ManPageArchiveReadNew3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_new.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_new.3 > ManPageArchiveReadNew3.wiki
ManPageArchiveReadOpen3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_open.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_open.3 > ManPageArchiveReadOpen3.wiki
ManPageArchiveReadSetOptions3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_read_set_options.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_read_set_options.3 > ManPageArchiveReadSetOptions3.wiki
ManPageArchiveUtil3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_util.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_util.3 > ManPageArchiveUtil3.wiki
ManPageArchiveWrite3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write.3 > ManPageArchiveWrite3.wiki
ManPageArchiveWriteBlocksize3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_blocksize.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_blocksize.3 > ManPageArchiveWriteBlocksize3.wiki
ManPageArchiveWriteData3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_data.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_data.3 > ManPageArchiveWriteData3.wiki
ManPageArchiveWriteDisk3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_disk.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_disk.3 > ManPageArchiveWriteDisk3.wiki
ManPageArchiveWriteFilter3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_filter.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_filter.3 > ManPageArchiveWriteFilter3.wiki
ManPageArchiveWriteFinishEntry3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_finish_entry.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_finish_entry.3 > ManPageArchiveWriteFinishEntry3.wiki
ManPageArchiveWriteFormat3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_format.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_format.3 > ManPageArchiveWriteFormat3.wiki
ManPageArchiveWriteFree3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_free.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_free.3 > ManPageArchiveWriteFree3.wiki
ManPageArchiveWriteHeader3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_header.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_header.3 > ManPageArchiveWriteHeader3.wiki
ManPageArchiveWriteNew3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_new.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_new.3 > ManPageArchiveWriteNew3.wiki
ManPageArchiveWriteOpen3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_open.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_open.3 > ManPageArchiveWriteOpen3.wiki
ManPageArchiveWriteSetOptions3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_set_options.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_set_options.3 > ManPageArchiveWriteSetOptions3.wiki
ManPageArchiveWriteSetPassphrase3.wiki: ../mdoc2wiki.awk ../../libarchive/archive_write_set_passphrase.3
awk -f ../mdoc2wiki.awk < ../../libarchive/archive_write_set_passphrase.3 > ManPageArchiveWriteSetPassphrase3.wiki
ManPageCpio5.wiki: ../mdoc2wiki.awk ../../libarchive/cpio.5
awk -f ../mdoc2wiki.awk < ../../libarchive/cpio.5 > ManPageCpio5.wiki
ManPageLibarchiveFormats5.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive-formats.5
awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive-formats.5 > ManPageLibarchiveFormats5.wiki
ManPageLibarchive3.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive.3
awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive.3 > ManPageLibarchive3.wiki
ManPageLibarchiveChanges3.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive_changes.3
awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive_changes.3 > ManPageLibarchiveChanges3.wiki
ManPageLibarchiveInternals3.wiki: ../mdoc2wiki.awk ../../libarchive/libarchive_internals.3
awk -f ../mdoc2wiki.awk < ../../libarchive/libarchive_internals.3 > ManPageLibarchiveInternals3.wiki
ManPageMtree5.wiki: ../mdoc2wiki.awk ../../libarchive/mtree.5
awk -f ../mdoc2wiki.awk < ../../libarchive/mtree.5 > ManPageMtree5.wiki
ManPageTar5.wiki: ../mdoc2wiki.awk ../../libarchive/tar.5
awk -f ../mdoc2wiki.awk < ../../libarchive/tar.5 > ManPageTar5.wiki
ManPageBsdtar1.wiki: ../mdoc2wiki.awk ../../tar/bsdtar.1
awk -f ../mdoc2wiki.awk < ../../tar/bsdtar.1 > ManPageBsdtar1.wiki
ManPageBsdcpio1.wiki: ../mdoc2wiki.awk ../../cpio/bsdcpio.1
awk -f ../mdoc2wiki.awk < ../../cpio/bsdcpio.1 > ManPageBsdcpio1.wiki
all: ManPageArchiveEntry3.wiki ManPageArchiveEntryAcl3.wiki ManPageArchiveEntryLinkify3.wiki ManPageArchiveEntryMisc3.wiki ManPageArchiveEntryPaths3.wiki ManPageArchiveEntryPerms3.wiki ManPageArchiveEntryStat3.wiki ManPageArchiveEntryTime3.wiki ManPageArchiveRead3.wiki ManPageArchiveReadAddPassphrase3.wiki ManPageArchiveReadData3.wiki ManPageArchiveReadDisk3.wiki ManPageArchiveReadExtract3.wiki ManPageArchiveReadFilter3.wiki ManPageArchiveReadFormat3.wiki ManPageArchiveReadFree3.wiki ManPageArchiveReadHeader3.wiki ManPageArchiveReadNew3.wiki ManPageArchiveReadOpen3.wiki ManPageArchiveReadSetOptions3.wiki ManPageArchiveUtil3.wiki ManPageArchiveWrite3.wiki ManPageArchiveWriteBlocksize3.wiki ManPageArchiveWriteData3.wiki ManPageArchiveWriteDisk3.wiki ManPageArchiveWriteFilter3.wiki ManPageArchiveWriteFinishEntry3.wiki ManPageArchiveWriteFormat3.wiki ManPageArchiveWriteFree3.wiki ManPageArchiveWriteHeader3.wiki ManPageArchiveWriteNew3.wiki ManPageArchiveWriteOpen3.wiki ManPageArchiveWriteSetOptions3.wiki ManPageArchiveWriteSetPassphrase3.wiki ManPageCpio5.wiki ManPageLibarchiveFormats5.wiki ManPageLibarchive3.wiki ManPageLibarchiveChanges3.wiki ManPageLibarchiveInternals3.wiki ManPageMtree5.wiki ManPageTar5.wiki ManPageBsdtar1.wiki ManPageBsdcpio1.wiki

123
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntry3.wiki vendored Normal file
View file

@ -0,0 +1,123 @@
ARCHIVE_ENTRY(3) manual page
== NAME ==
'''archive_entry_clear''',
'''archive_entry_clone''',
'''archive_entry_free''',
'''archive_entry_new'''
- functions for managing archive entry descriptions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''struct archive_entry *''
<br>
'''archive_entry_clear'''(''struct archive_entry *'');
<br>
''struct archive_entry *''
<br>
'''archive_entry_clone'''(''struct archive_entry *'');
<br>
''void''
<br>
'''archive_entry_free'''(''struct archive_entry *'');
<br>
''struct archive_entry *''
<br>
'''archive_entry_new'''(''void'');
== DESCRIPTION ==
These functions create and manipulate data objects that
represent entries within an archive.
You can think of a
'''struct archive_entry'''
as a heavy-duty version of
'''struct stat :'''
it includes everything from
'''struct stat'''
plus associated pathname, textual group and user names, etc.
These objects are used by
[[ManPageibarchive3]]
to represent the metadata associated with a particular
entry in an archive.
=== Create and Destroy===
There are functions to allocate, destroy, clear, and copy
''archive_entry''
objects:
<dl>
<dt>'''archive_entry_clear'''()</dt><dd>
Erases the object, resetting all internal fields to the
same state as a newly-created object.
This is provided to allow you to quickly recycle objects
without thrashing the heap.
</dd><dt>'''archive_entry_clone'''()</dt><dd>
A deep copy operation; all text fields are duplicated.
</dd><dt>'''archive_entry_free'''()</dt><dd>
Releases the
'''struct archive_entry'''
object.
</dd><dt>'''archive_entry_new'''()</dt><dd>
Allocate and return a blank
'''struct archive_entry'''
object.
</dd></dl>
=== Function groups===
Due to high number of functions, the accessor functions can be found in
man pages grouped by the purpose.
<dl>
<dt>[[ManPagerchiventrycl3]]</dt><dd>
Access Control List manipulation
</dd><dt>[[ManPagerchiventryaths3]]</dt><dd>
Path name manipulation
</dd><dt>[[ManPagerchiventryerms3]]</dt><dd>
User, group and mode manipulation
</dd><dt>[[ManPagerchiventrytat3]]</dt><dd>
Functions not in the other groups and copying to/from
''struct'' stat.
</dd><dt>[[ManPagerchiventryime3]]</dt><dd>
Time field manipulation
</dd></dl>
Most of the functions set or read entries in an object.
Such functions have one of the following forms:
<dl>
<dt>'''archive_entry_set_XXXX'''()</dt><dd>
Stores the provided data in the object.
In particular, for strings, the pointer is stored,
not the referenced string.
</dd><dt>'''archive_entry_copy_XXXX'''()</dt><dd>
As above, except that the referenced data is copied
into the object.
</dd><dt>'''archive_entry_XXXX'''()</dt><dd>
Returns the specified data.
In the case of strings, a const-qualified pointer to
the string is returned.
</dd></dl>
String data can be set or accessed as wide character strings
or normal
''char''
strings.
The functions that use wide character strings are suffixed with
'''_w'''.
Note that these are different representations of the same data:
For example, if you store a narrow string and read the corresponding
wide string, the object will transparently convert formats
using the current locale.
Similarly, if you store a wide string and then store a
narrow string for the same data, the previously-set wide string will
be discarded in favor of the new data.
== SEE ALSO ==
[[ManPagerchiventrycl3]],
[[ManPagerchiventryaths3]],
[[ManPagerchiventryerms3]],
[[ManPagerchiventryime3]],
[[ManPageibarchive3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The
'''libarchive'''
library was written by
Tim Kientzle &lt;kientzle@acm.org.&gt;

458
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryAcl3.wiki vendored Normal file
View file

@ -0,0 +1,458 @@
ARCHIVE_ENTRY_ACL(3) manual page
== NAME ==
'''archive_entry_acl_add_entry''',
'''archive_entry_acl_add_entry_w''',
'''archive_entry_acl_clear''',
'''archive_entry_acl_count''',
'''archive_entry_acl_from_text''',
'''archive_entry_acl_from_text_w''',
'''archive_entry_acl_next''',
'''archive_entry_acl_reset''',
'''archive_entry_acl_to_text''',
'''archive_entry_acl_to_text_w''',
'''archive_entry_acl_types'''
- functions for manipulating Access Control Lists in archive entry descriptions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''void''
<br>
'''archive_entry_acl_add_entry'''(''struct archive_entry *a'', ''int type'', ''int permset'', ''int tag'', ''int qualifier'', ''const char *name'');
<br>
''void''
<br>
'''archive_entry_acl_add_entry_w'''(''struct archive_entry *a'', ''int type'', ''int permset'', ''int tag'', ''int qualifier'', ''const wchar_t *name'');
<br>
''void''
<br>
'''archive_entry_acl_clear'''(''struct archive_entry *a'');
<br>
''int''
<br>
'''archive_entry_acl_count'''(''struct archive_entry *a'', ''int type'');
<br>
''int''
<br>
'''archive_entry_acl_from_text'''(''struct archive_entry *a'', ''const char *text'', ''int type'');
<br>
''int''
<br>
'''archive_entry_acl_from_text_w'''(''struct archive_entry *a'', ''const wchar_t *text'', ''int type'');
<br>
''int''
<br>
'''archive_entry_acl_next'''(''struct archive_entry *a'', ''int type'', ''int *ret_type'', ''int *ret_permset'', ''int *ret_tag'', ''int *ret_qual'', ''const char **ret_name'');
<br>
''int''
<br>
'''archive_entry_acl_reset'''(''struct archive_entry *a'', ''int type'');
<br>
''char *''
<br>
'''archive_entry_acl_to_text'''(''struct archive_entry *a'', ''ssize_t *len_p'', ''int flags'');
<br>
''wchar_t *''
<br>
'''archive_entry_acl_to_text_w'''(''struct archive_entry *a'', ''ssize_t *len_p'', ''int flags'');
<br>
''int''
<br>
'''archive_entry_acl_types'''(''struct archive_entry *a'');
== DESCRIPTION ==
The
"Access Control Lists (ACLs)"
extend the standard Unix permission model.
The ACL interface of
'''libarchive'''
supports both POSIX.1e and NFSv4 style ACLs.
Use of ACLs is restricted by
various levels of ACL support in operating systems, file systems and archive
formats.
=== POSIX.1e Access Control Lists===
A POSIX.1e ACL consists of a number of independent entries.
Each entry specifies the permission set as a bitmask of basic permissions.
Valid permissions in the
are:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_READ (.B r )
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_WRITE (.B w )
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_EXECUTE (.B x )
</dd></dl>
The permissions correspond to the normal Unix permissions.
The
specifies the principal to which the permission applies.
Valid values are:
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_USER
The user specified by the name field.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_USER_OBJ
The owner of the file.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_GROUP
The group specified by the name field.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_GROUP_OBJ
The group which owns the file.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_MASK
The maximum permissions to be obtained via group permissions.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_OTHER
Any principal who is not the file owner or a member of the owning group.
</dd>
The principals
ARCHIVE_ENTRY_ACL_USER_OBJ,
ARCHIVE_ENTRY_ACL_GROUP_OBJ
and
ARCHIVE_ENTRY_ACL_OTHER
are equivalent to user, group and other in the classic Unix permission
model and specify non-extended ACL entries.
All files have an access ACL
()
ARCHIVE_ENTRY_ACL_TYPE_ACCESS.
This specifies the permissions required for access to the file itself.
Directories have an additional ACL
()
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT,
which controls the initial access ACL for newly-created directory entries.
=== NFSv4 Access Control Lists===
A NFSv4 ACL consists of multiple individual entries called Access Control
Entries (ACEs).
There are four possible types of a NFSv4 ACE:
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ALLOW
Allow principal to perform actions requiring given permissions.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_DENY
Prevent principal from performing actions requiring given permissions.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_AUDIT
Log access attempts by principal which require given permissions.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ALARM
Trigger a system alarm on access attempts by principal which require given
permissions.
</dd>
The
specifies the principal to which the permission applies.
Valid values are:
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_USER
The user specified by the name field.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_USER_OBJ
The owner of the file.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_GROUP
The group specified by the name field.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_GROUP_OBJ
The group which owns the file.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_EVERYONE
Any principal who is not the file owner or a member of the owning group.
</dd>
Entries with the
ARCHIVE_ENTRY_ACL_USER
or
ARCHIVE_ENTRY_ACL_GROUP
tag store the user and group name in the
string and optionally the user or group ID in the
integer.
NFSv4 ACE permissions and flags are stored in the same
bitfield.
Some permissions share the same constant and permission character
but have different effect on directories than on files.
The following ACE permissions are supported:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_READ_DATA (.B r )
Read data (file).
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (.B r )
List entries (directory).
</dd><dt>ARCHIVE_ENTRY_ACL_WRITE_DATA (.B w )</dt><dd>
Write data (file).
</dd><dt>ARCHIVE_ENTRY_ACL_ADD_FILE (.B w )</dt><dd>
Create files (directory).
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_EXECUTE (.B x )
Execute file or change into a directory.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_APPEND_DATA (.B p )
Append data (file).
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (.B p )
Create subdirectories (directory).
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_DELETE_CHILD (.B D )
Remove files and subdirectories inside a directory.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_DELETE (.B d )
Remove file or directory.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (.B a )
Read file or directory attributes.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (.B A )
Write file or directory attributes.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (.B R )
Read named file or directory attributes.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (.B W )
Write named file or directory attributes.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_READ_ACL (.B c )
Read file or directory ACL.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_WRITE_ACL (.B C )
Write file or directory ACL.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_WRITE_OWNER (.B o )
Change owner of a file or directory.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_SYNCHRONIZE (.B s )
Use synchronous I/O.
</dd></dl>
The following NFSv4 ACL inheritance flags are supported:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (.B f )
Inherit parent directory ACE to files.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (.B d )
Inherit parent directory ACE to subdirectories.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (.B i )
Only inherit, do not apply the permission on the directory itself.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (.B n )
Do not propagate inherit flags.
Only first-level entries inherit ACLs.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (.B S )
Trigger alarm or audit on successful access.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (.B F )
Trigger alarm or audit on failed access.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (.B I )
Mark that ACE was inherited.
</dd></dl>
=== Functions===
'''archive_entry_acl_add_entry'''()
and
'''archive_entry_acl_add_entry_w'''()
add a single ACL entry.
For the access ACL and non-extended principals, the classic Unix permissions
are updated.
An archive entry cannot contain both POSIX.1e and NFSv4 ACL entries.
'''archive_entry_acl_clear'''()
removes all ACL entries and resets the enumeration pointer.
'''archive_entry_acl_count'''()
counts the ACL entries that have the given type mask.
can be the bitwise-or of
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
</dd></dl>
for POSIX.1e ACLs and
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ALLOW
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_DENY
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_AUDIT
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ALARM
</dd></dl>
for NFSv4 ACLs.
For POSIX.1e ACLs if
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
is included and at least one extended ACL entry is found,
the three non-extended ACLs are added.
'''archive_entry_acl_from_text'''()
and
'''archive_entry_acl_from_text_w'''()
add new
(or merge with existing)
ACL entries from
(wide)
text.
The argument
may take one of the following values:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_NFS4
</dd></dl>
Supports all formats that can be created with
'''archive_entry_acl_to_text'''()
or respectively
'''archive_entry_acl_to_text_w'''().
Existing ACL entries are preserved.
To get a clean new ACL from text
'''archive_entry_acl_clear'''()
must be called first.
Entries prefixed with
"default:"
are treated as
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
unless
is
ARCHIVE_ENTRY_ACL_TYPE_NFS4.
Invalid entries, non-parseable ACL entries and entries beginning with
the
Sq #
character
(comments)
are skipped.
'''archive_entry_acl_next'''()
return the next entry of the ACL list.
This functions may only be called after
'''archive_entry_acl_reset'''()
has indicated the presence of extended ACL entries.
'''archive_entry_acl_reset'''()
prepare reading the list of ACL entries with
'''archive_entry_acl_next'''().
The function returns 0 if no non-extended ACLs are found.
In this case, the access permissions should be obtained by
[[ManPagerchiventryode3]]
or set using
[[chmod(2)|http://www.freebsd.org/cgi/man.cgi?query=chmod&sektion=2]].
Otherwise, the function returns the same value as
'''archive_entry_acl_count'''().
'''archive_entry_acl_to_text'''()
and
'''archive_entry_acl_to_text_w'''()
convert the ACL entries for the given type into a
(wide)
string of ACL entries separated by newline.
If the pointer
is not NULL, then the function shall return the length of the string
(not including the NULL terminator)
in the location pointed to by
.
The
argument is a bitwise-or.
The following flags are effective only on POSIX.1e ACL:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
Output access ACLs.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
Output POSIX.1e default ACLs.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
Prefix each default ACL entry with the word
"default:".
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
The mask and other ACLs don not contain a double colon.
</dd></dl>
The following flags are effecive only on NFSv4 ACL:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_STYLE_COMPACT
Do not output minus characters for unset permissions and flags in NFSv4 ACL
permission and flag fields.
</dd></dl>
The following flags are effective on both POSIX.1e and NFSv4 ACL:
<dl>
<dt></dt><dd>
ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
Add an additional colon-separated field containing the user or group id.
</dd><dt></dt><dd>
ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA
Separate ACL entries with comma instead of newline.
</dd></dl>
If the archive entry contains NFSv4 ACLs, all types of NFSv4 ACLs are returned.
It the entry contains POSIX.1e ACLs and none of the flags
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
or
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
are specified, both access and default entries are returned and default entries
are prefixed with
"default:".
'''archive_entry_acl_types'''()
get ACL entry types contained in an archive entry's ACL.
As POSIX.1e and NFSv4
ACL entries cannot be mixed, this function is a very efficient way to detect if
an ACL already contains POSIX.1e or NFSv4 ACL entries.
== RETURN VALUES ==
'''archive_entry_acl_count'''()
and
'''archive_entry_acl_reset'''()
returns the number of ACL entries that match the given type mask.
For POSIX.1e ACLS if the type mask includes
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
and at least one extended ACL entry exists, the three classic Unix
permissions are counted.
'''archive_entry_acl_from_text'''()
and
'''archive_entry_acl_from_text_w'''()
return
ARCHIVE_OK
if all entries were successfully parsed and
ARCHIVE_WARN
if one or more entries were invalid or non-parseable.
'''archive_entry_acl_next'''()
returns
ARCHIVE_OK
on success,
ARCHIVE_EOF
if no more ACL entries exist
and
ARCHIVE_WARN
if
'''archive_entry_acl_reset'''()
has not been called first.
'''archive_entry_acl_to_text'''()
returns a string representing the ACL entries matching the given type and
flags on success or NULL on error.
'''archive_entry_acl_to_text_w'''()
returns a wide string representing the ACL entries matching the given type
and flags on success or NULL on error.
'''archive_entry_acl_types'''()
returns a bitmask of ACL entry types or 0 if archive entry has no ACL entries.
== SEE ALSO ==
[[ManPagerchiventry3]],
[[ManPageibarchive3]]

197
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryLinkify3.wiki vendored Normal file
View file

@ -0,0 +1,197 @@
ARCHIVE_ENTRY_LINKIFY(3) manual page
== NAME ==
'''archive_entry_linkresolver''',
'''archive_entry_linkresolver_new''',
'''archive_entry_linkresolver_set_strategy''',
'''archive_entry_linkresolver_free''',
'''archive_entry_linkify'''
- hardlink resolver functions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''struct archive_entry_linkresolver *''
<br>
'''archive_entry_linkresolver_new'''(''void'');
<br>
''void''
<br>
'''archive_entry_linkresolver_set_strategy'''(''struct archive_entry_linkresolver *resolver'', ''int format'');
<br>
''void''
<br>
'''archive_entry_linkresolver_free'''(''struct archive_entry_linkresolver *resolver'');
<br>
''void''
<br>
'''archive_entry_linkify'''(''struct archive_entry_linkresolver *resolver'', ''struct archive_entry **entry'', ''struct archive_entry **sparse'');
== DESCRIPTION ==
Programs that want to create archives have to deal with hardlinks.
Hardlinks are handled in different ways by the archive formats.
The basic strategies are:
<ol>
<li>
Ignore hardlinks and store the body for each reference (old cpio, zip).
</li><li>
Store the body the first time an inode is seen (ustar, pax).
</li><li>
Store the body the last time an inode is seen (new cpio).
</li></ol>
The
'''archive_entry_linkresolver'''
functions help by providing a unified interface and handling the complexity
behind the scene.
The
'''archive_entry_linkresolver'''
functions assume that
''archive_entry''
instances have valid nlinks, inode and device values.
The inode and device value is used to match entries.
The nlinks value is used to determined if all references have been found and
if the internal references can be recycled.
The
'''archive_entry_linkresolver_new'''()
function allocates a new link resolver.
The instance can be freed using
'''archive_entry_linkresolver_free'''().
All deferred entries are flushed and the internal storage is freed.
The
'''archive_entry_linkresolver_set_strategy'''()
function selects the optimal hardlink strategy for the given format.
The format code can be obtained from
[[ManPagerchiveormat3]].
The function can be called more than once, but it is recommended to
flush all deferred entries first.
The
'''archive_entry_linkify'''()
function is the core of
'''archive_entry_linkresolver'''.
The
'''entry'''()
argument points to the
''archive_entry''
that should be written.
Depending on the strategy one of the following actions is taken:
<ol>
<li>
For the simple archive formats
''*entry''
is left unmodified and
''*sparse''
is set to
NULL.
</li><li>
For tar like archive formats,
''*sparse''
is set to
NULL.
If
''*entry''
is
NULL,
no action is taken.
If the hardlink count of
''*entry''
is larger than 1 and the file type is a regular file or symbolic link,
the internal list is searched for a matching inode.
If such an inode is found, the link count is decremented and the file size
of
''*entry''
is set to 0 to notify that no body should be written.
If no such inode is found, a copy of the entry is added to the internal cache
with a link count reduced by one.
</li><li>
For new cpio like archive formats a value for
''*entry''
of
NULL
is used to flush deferred entries.
In that case
''*entry''
is set to an arbitrary deferred entry and the entry itself is removed from the
internal list.
If the internal list is empty,
''*entry''
is set to
NULL.
In either case,
''*sparse''
is set to
NULL
and the function returns.
If the hardlink count of
''*entry''
is one or the file type is a directory or device,
''*sparse''
is set to
NULL
and no further action is taken.
Otherwise, the internal list is searched for a matching inode.
If such an inode is not found, the entry is added to the internal list,
both
''*entry''
and
''*sparse''
are set to
NULL
and the function returns.
If such an inode is found, the link count is decremented.
If it remains larger than one, the existing entry on the internal list
is swapped with
''*entry''
after retaining the link count.
The existing entry is returned in
''*entry''.
If the link count reached one, the new entry is also removed from the
internal list and returned in
''*sparse''.
Otherwise
''*sparse''
is set to
NULL.
</li></ol>
The general usage is therefore:
<ol>
<li>
For each new archive entry, call
'''archive_entry_linkify'''().
</li><li>
Keep in mind that the entries returned may have a size of 0 now.
</li><li>
If
''*entry''
is not
NULL,
archive it.
</li><li>
If
''*sparse''
is not
NULL,
archive it.
</li><li>
After all entries have been written to disk, call
'''archive_entry_linkify'''()
with
''*entry''
set to
NULL
and archive the returned entry as long as it is not
NULL.
</li></ol>
== RETURN VALUES ==
'''archive_entry_linkresolver_new'''()
returns
NULL
on
[[malloc(3)|http://www.freebsd.org/cgi/man.cgi?query=malloc&sektion=3]]
failures.
== SEE ALSO ==
[[ManPagerchiventry3]]

41
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryMisc3.wiki vendored Normal file
View file

@ -0,0 +1,41 @@
ARCHIVE_ENTRY_MISC(3) manual page
== NAME ==
'''archive_entry_symlink_type''',
'''archive_entry_set_symlink_type'''
- miscellaneous functions for manipulating properties of archive_entry
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''int''
<br>
'''archive_entry_symlink_type'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_symlink_type'''(''struct archive_entry *a'', ''int'');
== DESCRIPTION ==
The function
'''archive_entry_symlink_type'''()
returns and the function
'''archive_entry_set_symlink_type'''()
sets the type of the symbolic link stored in an archive entry.
These functions
have special meaning on operating systems that support multiple symbolic link
types (e.g. Microsoft Windows).
Supported values are:
<dl>
<dt>AE_SYMLINK_TYPE_UNDEFINED</dt><dd>
Symbolic link target type is not defined (default on unix systems)
</dd><dt>AE_SYMLINK_TYPE_FILE</dt><dd>
Symbolic link points to a file
</dd><dt>AE_SYMLINK_TYPE_DIRECTORY</dt><dd>
Symbolic link points to a directory
</dd></dl>
== SEE ALSO ==
[[ManPagerchiventry3]],
[[ManPagerchiventryaths3]],
[[ManPagerchiventrytat3]],
[[ManPageibarchive3]]

175
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryPaths3.wiki vendored Normal file
View file

@ -0,0 +1,175 @@
ARCHIVE_ENTRY_PATHS(3) manual page
== NAME ==
'''archive_entry_hardlink''',
'''archive_entry_hardlink_w''',
'''archive_entry_set_hardlink''',
'''archive_entry_copy_hardlink''',
'''archive_entry_copy_hardlink_w''',
'''archive_entry_update_hardlink_utf8''',
'''archive_entry_set_link''',
'''archive_entry_copy_link''',
'''archive_entry_copy_link_w''',
'''archive_entry_update_link_utf8''',
'''archive_entry_pathname''',
'''archive_entry_pathname_w''',
'''archive_entry_set_pathname''',
'''archive_entry_copy_pathname''',
'''archive_entry_copy_pathname_w''',
'''archive_entry_update_pathname_utf8''',
'''archive_entry_sourcepath''',
'''archive_entry_copy_sourcepath''',
'''archive_entry_symlink''',
'''archive_entry_symlink_w''',
'''archive_entry_set_symlink''',
'''archive_entry_copy_symlink''',
'''archive_entry_copy_symlink_w''',
'''archive_entry_update_symlink_utf8'''
- functions for manipulating path names in archive entry descriptions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''const char *''
<br>
'''archive_entry_hardlink'''(''struct archive_entry *a'');
<br>
''const wchar_t *''
<br>
'''archive_entry_hardlink_w'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_hardlink'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_hardlink'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_hardlink_w'''(''struct archive_entry *a '', ''const'', ''wchar_t'', ''*path"'');
<br>
''int''
<br>
'''archive_entry_update_hardlink_utf8'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_set_link'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_link'''(''struct archive_entry *a'', '' const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_link_w'''(''struct archive_entry *a'', '' const wchar_t *path'');
<br>
''int''
<br>
'''archive_entry_update_link_utf8'''(''struct archive_entry *a'', '' const char *path'');
<br>
''const char *''
<br>
'''archive_entry_pathname'''(''struct archive_entry *a'');
<br>
''const wchar_t *''
<br>
'''archive_entry_pathname_w'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_pathname'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_pathname'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_pathname_w'''(''struct archive_entry *a'', ''const wchar_t *path'');
<br>
''int''
<br>
'''archive_entry_update_pathname_utf8'''(''struct archive_entry *a'', ''const char *path'');
<br>
''const char *''
<br>
'''archive_entry_sourcepath'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_copy_sourcepath'''(''struct archive_entry *a'', ''const char *path'');
<br>
''const char *''
<br>
'''archive_entry_symlink'''(''struct archive_entry *a'');
<br>
''const wchar_t *''
<br>
'''archive_entry_symlink_w'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_symlink'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_symlink'''(''struct archive_entry *a'', ''const char *path'');
<br>
''void''
<br>
'''archive_entry_copy_symlink_w'''(''struct archive_entry *a'', ''const wchar_t *path'');
<br>
''int''
<br>
'''archive_entry_update_symlink_utf8'''(''struct archive_entry *a'', ''const char *path'');
== DESCRIPTION ==
Path names supported by
[[ManPagerchiventry3]]:
<dl>
<dt>hardlink</dt><dd>
Destination of the hardlink.
</dd><dt>link</dt><dd>
Update only.
For a symlink, update the destination.
Otherwise, make the entry a hardlink and alter
the destination for that.
</dd><dt>pathname</dt><dd>
Path in the archive
</dd><dt>sourcepath</dt><dd>
Path on the disk for use by
[[ManPagerchiveeadisk3]].
</dd><dt>symlink</dt><dd>
Destination of the symbolic link.
</dd></dl>
Path names can be provided in one of three different ways:
<dl>
<dt>char *</dt><dd>
Multibyte strings in the current locale.
</dd><dt>wchar_t *</dt><dd>
Wide character strings in the current locale.
The accessor functions are named
'''XXX_w'''().
</dd><dt>UTF-8</dt><dd>
Unicode strings encoded as UTF-8.
These are convenience functions to update both the multibyte and wide
character strings at the same time.
</dd></dl>
The sourcepath is a pure filesystem concept and never stored in an
archive directly.
For that reason, it is only available as multibyte string.
The link path is a convenience function for conditionally setting
hardlink or symlink destination.
It doesn't have a corresponding get accessor function.
'''archive_entry_set_XXX'''()
is an alias for
'''archive_entry_copy_XXX'''().
== SEE ALSO ==
[[ManPagerchiventry3]],
[[ManPageibarchive3]]

222
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryPerms3.wiki vendored Normal file
View file

@ -0,0 +1,222 @@
ARCHIVE_ENTRY_PERMS(3) manual page
== NAME ==
'''archive_entry_gid''',
'''archive_entry_set_gid''',
'''archive_entry_uid''',
'''archive_entry_set_uid''',
'''archive_entry_perm''',
'''archive_entry_set_perm''',
'''archive_entry_strmode''',
'''archive_entry_uname''',
'''archive_entry_uname_w''',
'''archive_entry_set_uname''',
'''archive_entry_copy_uname''',
'''archive_entry_copy_uname_w''',
'''archive_entry_update_uname_utf8''',
'''archive_entry_gname''',
'''archive_entry_gname_w''',
'''archive_entry_set_gname''',
'''archive_entry_copy_gname''',
'''archive_entry_copy_gname_w''',
'''archive_entry_update_gname_utf8''',
'''archive_entry_fflags''',
'''archive_entry_fflags_text''',
'''archive_entry_set_fflags''',
'''archive_entry_copy_fflags_text''',
'''archive_entry_copy_fflags_text_w'''
- functions for manipulating ownership and permissions in archive entry descriptions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''gid_t''
<br>
'''archive_entry_gid'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_gid'''(''struct archive_entry *a'', ''gid_t gid'');
<br>
''uid_t''
<br>
'''archive_entry_uid'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_uid'''(''struct archive_entry *a'', ''uid_t uid'');
<br>
''mode_t''
<br>
'''archive_entry_perm'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_perm'''(''struct archive_entry *a'', ''mode_t mode'');
<br>
''const char *''
<br>
'''archive_entry_strmode'''(''struct archive_entry *a'');
<br>
''const char *''
<br>
'''archive_entry_gname'''(''struct archive_entry *a'');
<br>
''const wchar_t *''
<br>
'''archive_entry_gname_w'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_gname'''(''struct archive_entry *a'', ''const char *a'');
<br>
''void''
<br>
'''archive_entry_copy_gname'''(''struct archive_entry *a'', ''const char *name'');
<br>
''void''
<br>
'''archive_entry_copy_gname_w'''(''struct archive_entry *a'', ''const wchar_t *name'');
<br>
''int''
<br>
'''archive_entry_update_gname_utf8'''(''struct archive_entry *a'', ''const char *name'');
<br>
''const char *''
<br>
'''archive_entry_uname'''(''struct archive_entry *a'');
<br>
''const wchar_t *''
<br>
'''archive_entry_uname_w'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_uname'''(''struct archive_entry *a'', ''const char *name'');
<br>
''void''
<br>
'''archive_entry_copy_uname'''(''struct archive_entry *a'', ''const char *name'');
<br>
''void''
<br>
'''archive_entry_copy_uname_w'''(''struct archive_entry *a'', ''const wchar_t *name'');
<br>
''int''
<br>
'''archive_entry_update_uname_utf8'''(''struct archive_entry *a'', ''const char *name'');
<br>
''void''
<br>
'''archive_entry_fflags'''(''struct archive_entry *a'', ''unsigned long *set_bits'', ''unsigned long *clear_bits'');
<br>
''const char *''
<br>
'''archive_entry_fflags_text'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_fflags'''(''struct archive_entry *a'', ''unsigned long set_bits'', ''unsigned long clear_bits'');
<br>
''const char *''
<br>
'''archive_entry_copy_fflags_text'''(''struct archive_entry *a'', ''const char *text'');
<br>
''const wchar_t *''
<br>
'''archive_entry_copy_fflags_text_w'''(''struct archive_entry *a'', ''const wchar_t *text'');
== DESCRIPTION ==
=== User id, group id and mode===
The functions
'''archive_entry_uid'''(),
'''archive_entry_gid'''(),
and
'''archive_entry_perm'''()
can be used to extract the user id, group id and permission from the given entry.
The corresponding functions
'''archive_entry_set_uid'''(),
'''archive_entry_set_gid'''(),
and
'''archive_entry_set_perm'''()
store the given user id, group id and permission in the entry.
The permission is also set as a side effect of calling
'''archive_entry_set_mode'''().
'''archive_entry_strmode'''()
returns a string representation of the permission as used by the long mode of
[[ls(1)|http://www.freebsd.org/cgi/man.cgi?query=ls&sektion=1]].
=== User and group name===
User and group names can be provided in one of three different ways:
<dl>
<dt>char *</dt><dd>
Multibyte strings in the current locale.
</dd><dt>wchar_t *</dt><dd>
Wide character strings in the current locale.
The accessor functions are named
'''XXX_w'''().
</dd><dt>UTF-8</dt><dd>
Unicode strings encoded as UTF-8.
These are convenience functions to update both the multibyte and wide
character strings at the same time.
</dd></dl>
'''archive_entry_set_XXX'''()
is an alias for
'''archive_entry_copy_XXX'''().
=== File Flags===
File flags are transparently converted between a bitmap
representation and a textual format.
For example, if you set the bitmap and ask for text, the library
will build a canonical text format.
However, if you set a text format and request a text format,
you will get back the same text, even if it is ill-formed.
If you need to canonicalize a textual flags string, you should first set the
text form, then request the bitmap form, then use that to set the bitmap form.
Setting the bitmap format will clear the internal text representation
and force it to be reconstructed when you next request the text form.
The bitmap format consists of two integers, one containing bits
that should be set, the other specifying bits that should be
cleared.
Bits not mentioned in either bitmap will be ignored.
Usually, the bitmap of bits to be cleared will be set to zero.
In unusual circumstances, you can force a fully-specified set
of file flags by setting the bitmap of flags to clear to the complement
of the bitmap of flags to set.
(This differs from
[[fflagstostr(3)|http://www.freebsd.org/cgi/man.cgi?query=fflagstostr&sektion=3]],
which only includes names for set bits.)
Converting a bitmap to a textual string is a platform-specific
operation; bits that are not meaningful on the current platform
will be ignored.
The canonical text format is a comma-separated list of flag names.
The
'''archive_entry_copy_fflags_text'''()
and
'''archive_entry_copy_fflags_text_w'''()
functions parse the provided text and set the internal bitmap values.
This is a platform-specific operation; names that are not meaningful
on the current platform will be ignored.
The function returns a pointer to the start of the first name that was not
recognized, or NULL if every name was recognized.
Note that every name \(em including names that follow an unrecognized
name \(em will be evaluated, and the bitmaps will be set to reflect
every name that is recognized.
(In particular, this differs from
[[strtofflags(3)|http://www.freebsd.org/cgi/man.cgi?query=strtofflags&sektion=3]],
which stops parsing at the first unrecognized name.)
== SEE ALSO ==
[[ManPagerchiventry3]],
[[ManPagerchiventrycl3]],
[[ManPagerchiveeadisk3]],
[[ManPagerchiveriteisk3]],
[[ManPageibarchive3]]
== BUGS ==
The platform types
''uid_t''
and
''gid_t''
are often 16 or 32 bit wide.
In this case it is possible that the ids can not be correctly restored
from archives and get truncated.

308
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryStat3.wiki vendored Normal file
View file

@ -0,0 +1,308 @@
ARCHIVE_ENTRY_STAT(3) manual page
== NAME ==
'''archive_entry_stat''',
'''archive_entry_copy_stat''',
'''archive_entry_filetype''',
'''archive_entry_set_filetype''',
'''archive_entry_mode''',
'''archive_entry_set_mode''',
'''archive_entry_size''',
'''archive_entry_size_is_set''',
'''archive_entry_set_size''',
'''archive_entry_unset_size''',
'''archive_entry_dev''',
'''archive_entry_set_dev''',
'''archive_entry_dev_is_set''',
'''archive_entry_devmajor''',
'''archive_entry_set_devmajor''',
'''archive_entry_devminor''',
'''archive_entry_set_devminor''',
'''archive_entry_ino''',
'''archive_entry_set_ino''',
'''archive_entry_ino_is_set''',
'''archive_entry_ino64''',
'''archive_entry_set_ino64''',
'''archive_entry_nlink''',
'''archive_entry_rdev''',
'''archive_entry_set_rdev''',
'''archive_entry_rdevmajor''',
'''archive_entry_set_rdevmajor''',
'''archive_entry_rdevminor''',
'''archive_entry_set_rdevminor'''
- accessor functions for manipulating archive entry descriptions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''const struct stat *''
<br>
'''archive_entry_stat'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_copy_stat'''(''struct archive_entry *a'', ''const struct stat *sb'');
<br>
''mode_t''
<br>
'''archive_entry_filetype'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_filetype'''(''struct archive_entry *a'', ''unsigned int type'');
<br>
''mode_t''
<br>
'''archive_entry_mode'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_mode'''(''struct archive_entry *a'', ''mode_t mode'');
<br>
''int64_t''
<br>
'''archive_entry_size'''(''struct archive_entry *a'');
<br>
''int''
<br>
'''archive_entry_size_is_set'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_size'''(''struct archive_entry *a'', ''int64_t size'');
<br>
''void''
<br>
'''archive_entry_unset_size'''(''struct archive_entry *a'');
<br>
''dev_t''
<br>
'''archive_entry_dev'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_dev'''(''struct archive_entry *a'', ''dev_t dev'');
<br>
''int''
<br>
'''archive_entry_dev_is_set'''(''struct archive_entry *a'');
<br>
''dev_t''
<br>
'''archive_entry_devmajor'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_devmajor'''(''struct archive_entry *a'', ''dev_t major'');
<br>
''dev_t''
<br>
'''archive_entry_devminor'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_devminor'''(''struct archive_entry *a'', ''dev_t minor'');
<br>
''ino_t''
<br>
'''archive_entry_ino'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_ino'''(''struct archive_entry *a'', ''unsigned long ino'');
<br>
''int''
<br>
'''archive_entry_ino_is_set'''(''struct archive_entry *a'');
<br>
''int64_t''
<br>
'''archive_entry_ino64'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_ino64'''(''struct archive_entry *a'', ''int64_t ino'');
<br>
''unsigned int''
<br>
'''archive_entry_nlink'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_nlink'''(''struct archive_entry *a'', ''unsigned int count'');
<br>
''dev_t''
<br>
'''archive_entry_rdev'''(''struct archive_entry *a'');
<br>
''dev_t''
<br>
'''archive_entry_rdevmajor'''(''struct archive_entry *a'');
<br>
''dev_t''
<br>
'''archive_entry_rdevminor'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_rdev'''(''struct archive_entry *a'', ''dev_t dev'');
<br>
''void''
<br>
'''archive_entry_set_rdevmajor'''(''struct archive_entry *a'', ''dev_t major'');
<br>
''void''
<br>
'''archive_entry_set_rdevminor'''(''struct archive_entry *a'', ''dev_t minor'');
== DESCRIPTION ==
=== Copying to and from ''struct'' stat===
The function
'''archive_entry_stat'''()
converts the various fields stored in the archive entry to the format
used by
[[stat(2)|http://www.freebsd.org/cgi/man.cgi?query=stat&sektion=2]].
The return value remains valid until either
'''archive_entry_clear'''()
or
'''archive_entry_free'''()
is called.
It is not affected by calls to the set accessor functions.
It currently sets the following values in
''struct'' stat:
''st_atime'',
''st_ctime'',
''st_dev'',
''st_gid'',
''st_ino'',
''st_mode'',
''st_mtime'',
''st_nlink'',
''st_rdev'',
''st_size'',
''st_uid''.
In addition,
''st_birthtime''
and high-precision information for time-related fields
will be included on platforms that support it.
The function
'''archive_entry_copy_stat'''()
copies fields from the platform's
''struct'' stat.
Fields not provided by
''struct'' stat
are unchanged.
=== General accessor functions===
The functions
'''archive_entry_filetype'''()
and
'''archive_entry_set_filetype'''()
get respectively set the filetype.
The file type is one of the following constants:
<dl>
<dt>AE_IFREG</dt><dd>
Regular file
</dd><dt>AE_IFLNK</dt><dd>
Symbolic link
</dd><dt>AE_IFSOCK</dt><dd>
Socket
</dd><dt>AE_IFCHR</dt><dd>
Character device
</dd><dt>AE_IFBLK</dt><dd>
Block device
</dd><dt>AE_IFDIR</dt><dd>
Directory
</dd><dt>AE_IFIFO</dt><dd>
Named pipe (fifo)
</dd></dl>
Not all file types are supported by all platforms.
The constants used by
[[stat(2)|http://www.freebsd.org/cgi/man.cgi?query=stat&sektion=2]]
may have different numeric values from the
corresponding constants above.
The functions
'''archive_entry_mode'''()
and
'''archive_entry_set_mode'''()
get/set a combination of file type and permissions and provide the
equivalent of
''st_mode''.
Use of
'''archive_entry_filetype'''()
and
'''archive_entry_perm'''()
for getting and
'''archive_entry_set_filetype'''()
and
'''archive_entry_set_perm'''()
for setting is recommended.
The function
'''archive_entry_size'''()
returns the file size, if it has been set, and 0 otherwise.
'''archive_entry_size'''()
can be used to query that status.
'''archive_entry_set_size'''()
and
'''archive_entry_unset_size'''()
set and unset the size, respectively.
The number of references (hardlinks) can be obtained by calling
'''archive_entry_nlinks'''()
and set with
'''archive_entry_set_nlinks'''().
=== Identifying unique files===
The functions
'''archive_entry_dev'''()
and
'''archive_entry_ino64'''()
are used by
[[ManPagerchiventryinkify3]]
to find hardlinks.
The pair of device and inode is supposed to identify hardlinked files.
The device major and minor number can be obtained independently using
'''archive_entry_devmajor'''()
and
'''archive_entry_devminor'''().
The device can be set either via
'''archive_entry_set_dev'''()
or by the combination of major and minor number using
'''archive_entry_set_devmajor'''()
and
'''archive_entry_set_devminor'''().
The inode number can be obtained using
'''archive_entry_ino'''().
This is a legacy interface that uses the platform
''ino_t'',
which may be very small.
To set the inode number,
'''archive_entry_set_ino64'''()
is the preferred interface.
=== Accessor functions for block and character devices===
Block and character devices are characterised either using a device number
or a pair of major and minor number.
The combined device number can be obtained with
'''archive_device_rdev'''()
and set with
'''archive_device_set_rdev'''().
The major and minor numbers are accessed by
'''archive_device_rdevmajor'''(),
'''archive_device_rdevminor'''()
'''archive_device_set_rdevmajor'''()
and
'''archive_device_set_rdevminor'''().
The process of splitting the combined device number into major and
minor number and the reverse process of combing them differs between
platforms.
Some archive formats use the combined form, while other formats use
the split form.
== SEE ALSO ==
[[stat(2)|http://www.freebsd.org/cgi/man.cgi?query=stat&sektion=2]],
[[ManPagerchiventrycl3]],
[[ManPagerchiventryerms3]],
[[ManPagerchiventryime3]],
[[ManPageibarchive3]]

138
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveEntryTime3.wiki vendored Normal file
View file

@ -0,0 +1,138 @@
ARCHIVE_ENTRY_TIME(3) manual page
== NAME ==
'''archive_entry_atime''',
'''archive_entry_atime_nsec''',
'''archive_entry_atime_is_set''',
'''archive_entry_set_atime''',
'''archive_entry_unset_atime''',
'''archive_entry_birthtime''',
'''archive_entry_birthtime_nsec''',
'''archive_entry_birthtime_is_set''',
'''archive_entry_set_birthtime''',
'''archive_entry_unset_birthtime''',
'''archive_entry_ctime''',
'''archive_entry_ctime_nsec''',
'''archive_entry_ctime_is_set''',
'''archive_entry_set_ctime''',
'''archive_entry_unset_ctime''',
'''archive_entry_mtime''',
'''archive_entry_mtime_nsec''',
'''archive_entry_mtime_is_set''',
'''archive_entry_set_mtime''',
'''archive_entry_unset_mtime'''
- functions for manipulating times in archive entry descriptions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive_entry.h></nowiki>'''
<br>
''time_t''
<br>
'''archive_entry_atime'''(''struct archive_entry *a'');
<br>
''long''
<br>
'''archive_entry_atime_nsec'''(''struct archive_entry *a'');
<br>
''int''
<br>
'''archive_entry_atime_is_set'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_atime'''(''struct archive_entry *a'', ''time_t sec'', ''long nanosec'');
<br>
''void''
<br>
'''archive_entry_unset_atime'''(''struct archive_entry *a'');
<br>
''time_t''
<br>
'''archive_entry_birthtime'''(''struct archive_entry *a'');
<br>
''long''
<br>
'''archive_entry_birthtime_nsec'''(''struct archive_entry *a'');
<br>
''int''
<br>
'''archive_entry_birthtime_is_set'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_birthtime'''(''struct archive_entry *a'', ''time_t sec'', ''long nanosec'');
<br>
''void''
<br>
'''archive_entry_unset_birthtime'''(''struct archive_entry *a'');
<br>
''time_t''
<br>
'''archive_entry_ctime'''(''struct archive_entry *a'');
<br>
''long''
<br>
'''archive_entry_ctime_nsec'''(''struct archive_entry *a'');
<br>
''int''
<br>
'''archive_entry_ctime_is_set'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_ctime'''(''struct archive_entry *a'', ''time_t sec'', ''long nanosec'');
<br>
''void''
<br>
'''archive_entry_unset_ctime'''(''struct archive_entry *a'');
<br>
''time_t''
<br>
'''archive_entry_mtime'''(''struct archive_entry *a'');
<br>
''long''
<br>
'''archive_entry_mtime_nsec'''(''struct archive_entry *a'');
<br>
''int''
<br>
'''archive_entry_mtime_is_set'''(''struct archive_entry *a'');
<br>
''void''
<br>
'''archive_entry_set_mtime'''(''struct archive_entry *a'', ''time_t sec'', ''long nanosec'');
<br>
''void''
<br>
'''archive_entry_unset_mtime'''(''struct archive_entry *a'');
== DESCRIPTION ==
These functions create and manipulate the time fields in an
''archive_entry''.
Supported time fields are atime (access time), birthtime (creation time),
ctime (last time an inode property was changed) and mtime (modification time).
[[ManPageibarchive3]]
provides a high-resolution interface.
The timestamps are truncated automatically depending on the archive format
(for archiving) or the filesystem capabilities (for restoring).
All timestamp fields are optional.
The
'''XXX_unset'''()
functions can be used to mark the corresponding field as missing.
The current state can be queried using
'''XXX_is_set'''().
Unset time fields have a second and nanosecond field of 0.
== SEE ALSO ==
[[ManPagerchiventry3]],
[[ManPageibarchive3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The
'''libarchive'''
library was written by
Tim Kientzle &lt;kientzle@acm.org.&gt;

208
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveRead3.wiki vendored Normal file
View file

@ -0,0 +1,208 @@
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.
== 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(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);
}
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]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadxtract3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadeader3]],
[[ManPagerchiveeadew3]],
[[ManPagerchiveeadpen3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[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.

42
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadAddPassphrase3.wiki vendored Normal file
View file

@ -0,0 +1,42 @@
ARCHIVE_READ_ADD_PASSPHRASE(3) manual page
== NAME ==
'''archive_read_add_passphrase''',
'''archive_read_set_passphrase_callback'''
- functions for reading encrypted archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_read_add_passphrase'''(''struct archive *'', ''const char *passphrase'');
<br>
''int''
<br>
'''archive_read_set_passphrase_callback'''(''struct archive *'', ''void *client_data'', ''archive_passphrase_callback *'');
== DESCRIPTION ==
<dl>
<dt>'''archive_read_add_passphrase'''()</dt><dd>
Register passphrases for reading an encryption archive.
If
''passphrase''
is
NULL
or empty, this function will do nothing and
'''ARCHIVE_FAILED'''
will be returned.
Otherwise,
'''ARCHIVE_OK'''
will be returned.
</dd><dt>'''archive_read_set_passphrase_callback'''()</dt><dd>
Register a callback function that will be invoked to get a passphrase
for decryption after trying all the passphrases registered by the
'''archive_read_add_passphrase'''()
function failed.
</dd></dl>
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiveeadetptions3]],
[[ManPageibarchive3]]

101
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadData3.wiki vendored Normal file
View file

@ -0,0 +1,101 @@
ARCHIVE_READ_DATA(3) manual page
== NAME ==
'''archive_read_data''',
'''archive_read_data_block''',
'''archive_read_data_skip''',
'''archive_read_data_into_fd'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''la_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_fd'''(''struct archive *'', ''int fd'');
== DESCRIPTION ==
<dl>
<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.
Note that this function is invoked automatically by
'''archive_read_next_header2'''()
if the previous entry was not completely consumed.
</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></dl>
== 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).
'''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.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiveeadxtract3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadeader3]],
[[ManPagerchiveeadpen3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[ManPageTar5]]

321
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadDisk3.wiki vendored Normal file
View file

@ -0,0 +1,321 @@
ARCHIVE_READ_DISK(3) manual page
== NAME ==
'''archive_read_disk_new''',
'''archive_read_disk_set_behavior''',
'''archive_read_disk_set_symlink_logical''',
'''archive_read_disk_set_symlink_physical''',
'''archive_read_disk_set_symlink_hybrid''',
'''archive_read_disk_entry_from_file''',
'''archive_read_disk_gname''',
'''archive_read_disk_uname''',
'''archive_read_disk_set_uname_lookup''',
'''archive_read_disk_set_gname_lookup''',
'''archive_read_disk_set_standard_lookup'''
- functions for reading objects from disk
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''struct archive *''
<br>
'''archive_read_disk_new'''(''void'');
<br>
''int''
<br>
'''archive_read_disk_set_behavior'''(''struct archive *'', ''int'');
<br>
''int''
<br>
'''archive_read_disk_set_symlink_logical'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_disk_set_symlink_physical'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_disk_set_symlink_hybrid'''(''struct archive *'');
<br>
''const char *''
<br>
'''archive_read_disk_gname'''(''struct archive *'', ''gid_t'');
<br>
''const char *''
<br>
'''archive_read_disk_uname'''(''struct archive *'', ''uid_t'');
<br>
''int''
<br>
'''archive_read_disk_set_gname_lookup'''(''struct archive *'', ''void *'', ''const char *(*lookup)(void *, gid_t)'', ''void (*cleanup)(void *)'');
<br>
''int''
<br>
'''archive_read_disk_set_uname_lookup'''(''struct archive *'', ''void *'', ''const char *(*lookup)(void *, uid_t)'', ''void (*cleanup)(void *)'');
<br>
''int''
<br>
'''archive_read_disk_set_standard_lookup'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_disk_entry_from_file'''(''struct archive *'', ''struct archive_entry *'', ''int fd'', ''const struct stat *'');
== DESCRIPTION ==
These functions provide an API for reading information about
objects on disk.
In particular, they provide an interface for populating
'''struct archive_entry'''
objects.
<dl>
<dt>'''archive_read_disk_new'''()</dt><dd>
Allocates and initializes a
'''struct archive'''
object suitable for reading object information from disk.
</dd><dt>'''archive_read_disk_set_behavior'''()</dt><dd>
Configures various behavior options when reading entries from disk.
The flags field consists of a bitwise OR of one or more of the
following values:
<dl>
<dt>'''ARCHIVE_READDISK_HONOR_NODUMP'''</dt><dd>
Skip files and directories with the nodump file attribute (file flag) set.
By default, the nodump file attribute is ignored.
</dd><dt>'''ARCHIVE_READDISK_MAC_COPYFILE'''</dt><dd>
Mac OS X specific.
Read metadata (ACLs and extended attributes) with
[[copyfile(3)|http://www.freebsd.org/cgi/man.cgi?query=copyfile&sektion=3]].
By default, metadata is read using
[[copyfile(3)|http://www.freebsd.org/cgi/man.cgi?query=copyfile&sektion=3]].
</dd><dt>'''ARCHIVE_READDISK_NO_ACL'''</dt><dd>
Do not read Access Control Lists.
By default, ACLs are read from disk.
</dd><dt>'''ARCHIVE_READDISK_NO_FFLAGS'''</dt><dd>
Do not read file attributes (file flags).
By default, file attributes are read from disk.
See
[[chattr(1)|http://www.freebsd.org/cgi/man.cgi?query=chattr&sektion=1]]
(Linux)
or
[[chflags(1)|http://www.freebsd.org/cgi/man.cgi?query=chflags&sektion=1]]
(FreeBSD, Mac OS X)
for more information on file attributes.
</dd><dt>'''ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS'''</dt><dd>
Do not traverse mount points.
By default, mount points are traversed.
</dd><dt>'''ARCHIVE_READDISK_NO_XATTR'''</dt><dd>
Do not read extended file attributes (xattrs).
By default, extended file attributes are read from disk.
See
[[xattr(7)|http://www.freebsd.org/cgi/man.cgi?query=xattr&sektion=7]]
(Linux,)
[[xattr(2)|http://www.freebsd.org/cgi/man.cgi?query=xattr&sektion=2]]
(Mac OS X,)
or
[[getextattr(8)|http://www.freebsd.org/cgi/man.cgi?query=getextattr&sektion=8]]
(FreeBSD)
for more information on extended file attributes.
</dd><dt>'''ARCHIVE_READDISK_RESTORE_ATIME'''</dt><dd>
Restore access time of traversed files.
By default, access time of traversed files is not restored.
</dd></dl>
</dd><dt>
'''archive_read_disk_set_symlink_logical'''(),
'''archive_read_disk_set_symlink_physical'''(),
'''archive_read_disk_set_symlink_hybrid'''()
</dt> <dd>
This sets the mode used for handling symbolic links.
The
"logical"
mode follows all symbolic links.
The
"physical"
mode does not follow any symbolic links.
The
"hybrid"
mode currently behaves identically to the
"logical"
mode.
</dd><dt>
'''archive_read_disk_gname'''(),
'''archive_read_disk_uname'''()
</dt> <dd>
Returns a user or group name given a gid or uid value.
By default, these always return a NULL string.
</dd><dt>
'''archive_read_disk_set_gname_lookup'''(),
'''archive_read_disk_set_uname_lookup'''()
</dt> <dd>
These allow you to override the functions used for
user and group name lookups.
You may also provide a
'''void *'''
pointer to a private data structure and a cleanup function for
that data.
The cleanup function will be invoked when the
'''struct archive'''
object is destroyed or when new lookup functions are registered.
</dd><dt>'''archive_read_disk_set_standard_lookup'''()</dt><dd>
This convenience function installs a standard set of user
and group name lookup functions.
These functions use
[[getpwuid(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwuid&sektion=3]]
and
[[getgrgid(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrgid&sektion=3]]
to convert ids to names, defaulting to NULL if the names cannot
be looked up.
These functions also implement a simple memory cache to reduce
the number of calls to
[[getpwuid(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwuid&sektion=3]]
and
[[getgrgid(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrgid&sektion=3]].
</dd><dt>'''archive_read_disk_entry_from_file'''()</dt><dd>
Populates a
'''struct archive_entry'''
object with information about a particular file.
The
'''archive_entry'''
object must have already been created with
[[ManPagerchiventryew3]]
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 descriptor is provided, some information will be obtained using
that file descriptor, on platforms that support the appropriate
system calls.
If a pointer to a
'''struct stat'''
is provided, information from that structure will be used instead
of reading from the disk where appropriate.
This can provide performance benefits in scenarios where
'''struct stat'''
information has already been read from the disk as a side effect
of some other operation.
(For example, directory traversal libraries often provide this information.)
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.
</dd></dl>
More information about the
''struct'' archive
object and the overall design of the library can be found in the
[[ManPageibarchive3]]
overview.
== EXAMPLES ==
The following illustrates basic usage of the library by
showing how to use it to copy an item on disk into an archive.
```text
void
file_to_archive(struct archive *a, const char *name)
{
char buff[8192];
size_t bytes_read;
struct archive *ard;
struct archive_entry *entry;
int fd;
ard = archive_read_disk_new();
archive_read_disk_set_standard_lookup(ard);
entry = archive_entry_new();
fd = open(name, O_RDONLY);
if (fd < 0)
return;
archive_entry_copy_pathname(entry, name);
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
archive_write_header(a, entry);
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
archive_write_data(a, buff, bytes_read);
archive_write_finish_entry(a);
archive_read_free(ard);
archive_entry_free(entry);
}
```
== RETURN VALUES ==
Most functions return
'''ARCHIVE_OK'''
(zero) on success, or one of several negative
error codes for errors.
Specific error codes include:
'''ARCHIVE_RETRY'''
for operations that might succeed if retried,
'''ARCHIVE_WARN'''
for unusual conditions that do not prevent further operations, and
'''ARCHIVE_FATAL'''
for serious errors that make remaining operations impossible.
'''archive_read_disk_new'''()
returns a pointer to a newly-allocated
'''struct archive'''
object or NULL if the allocation failed for any reason.
'''archive_read_disk_gname'''()
and
'''archive_read_disk_uname'''()
return
'''const char *'''
pointers to the textual name or NULL if the lookup failed for any reason.
The returned pointer points to internal storage that
may be reused on the next call to either of these functions;
callers should copy the string if they need to continue accessing it.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchivetil3]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteisk3]],
[[ManPageibarchive3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
The
'''archive_read_disk'''
interface was added to
'''libarchive''' 2.6
and first appeared in
FreeBSD 8.0.
== AUTHORS ==
The
'''libarchive'''
library was written by
Tim Kientzle &lt;kientzle@FreeBSD.org.&gt;
== BUGS ==
The
"standard"
user name and group name lookup functions are not the defaults because
[[getgrgid(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrgid&sektion=3]]
and
[[getpwuid(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwuid&sektion=3]]
are sometimes too large for particular applications.
The current design allows the application author to use a more
compact implementation when appropriate.
The full list of metadata read from disk by
'''archive_read_disk_entry_from_file'''()
is necessarily system-dependent.
The
'''archive_read_disk_entry_from_file'''()
function reads as much information as it can from disk.
Some method should be provided to limit this so that clients who
do not need ACLs, for instance, can avoid the extra work needed
to look up such information.
This API should provide a set of methods for walking a directory tree.
That would make it a direct parallel of the
[[ManPagerchiveead3]]
API.
When such methods are implemented, the
"hybrid"
symbolic link mode will make sense.

102
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadExtract3.wiki vendored Normal file
View file

@ -0,0 +1,102 @@
ARCHIVE_READ_EXTRACT(3) manual page
== NAME ==
'''archive_read_extract''',
'''archive_read_extract2''',
'''archive_read_extract_set_progress_callback'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<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'');
== DESCRIPTION ==
<dl>
<dt>'''archive_read_extract'''(), '''archive_read_extract_set_skip_file'''()</dt><dd>
A convenience function that wraps the corresponding
[[ManPagerchiveriteisk3]]
interfaces.
The first call to
'''archive_read_extract'''()
creates a restore object using
[[ManPagerchiveriteiskew3]]
and
[[ManPagerchiveriteiskettandardookup3]],
then transparently invokes
[[ManPagerchiveriteisketptions3]],
[[ManPagerchiveriteeader3]],
[[ManPagerchiveriteata3]],
and
[[ManPagerchiveriteinishntry3]]
to create the entry on disk and copy data into it.
The
''flags''
argument is passed unmodified to
[[ManPagerchiveriteisketptions3]].
</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
[[ManPagerchiveriteisketroupookup3]],
and
[[ManPagerchiveriteisketserookup3]].
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></dl>
== 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).
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadpen3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[ManPageTar5]]

143
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadFilter3.wiki vendored Normal file
View file

@ -0,0 +1,143 @@
ARCHIVE_READ_FILTER(3) manual page
== NAME ==
'''archive_read_support_filter_all''',
'''archive_read_support_filter_bzip2''',
'''archive_read_support_filter_compress''',
'''archive_read_support_filter_gzip''',
'''archive_read_support_filter_lz4''',
'''archive_read_support_filter_lzma''',
'''archive_read_support_filter_none''',
'''archive_read_support_filter_rpm''',
'''archive_read_support_filter_uu''',
'''archive_read_support_filter_xz''',
'''archive_read_support_filter_zstd''',
'''archive_read_support_filter_program''',
'''archive_read_support_filter_program_signature'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_read_support_filter_all'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_bzip2'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_compress'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_grzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_gzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_lrzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_lz4'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_lzma'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_lzop'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_none'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_rpm'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_uu'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_xz'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_zstd'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_filter_program'''(''struct archive *'', ''const char *cmd'');
<br>
''int''
<br>
'''archive_read_support_filter_program_signature'''(''struct archive *'', ''const char *cmd'', ''const void *signature'', ''size_t signature_length'');
== DESCRIPTION ==
<dl>
<dt>
'''archive_read_support_filter_bzip2'''(),
'''archive_read_support_filter_compress'''(),
'''archive_read_support_filter_grzip'''(),
'''archive_read_support_filter_gzip'''(),
'''archive_read_support_filter_lrzip'''(),
'''archive_read_support_filter_lz4'''(),
'''archive_read_support_filter_lzma'''(),
'''archive_read_support_filter_lzop'''(),
'''archive_read_support_filter_none'''(),
'''archive_read_support_filter_rpm'''(),
'''archive_read_support_filter_uu'''(),
'''archive_read_support_filter_xz'''(),
'''archive_read_support_filter_zstd'''(),
</dt> <dd>
Enables auto-detection code and decompression support for the
specified compression.
These functions may fall back on external programs if an appropriate
library was not available at build time.
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_filter_all'''()</dt><dd>
Enables all available decompression filters.
</dd><dt>'''archive_read_support_filter_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_filter_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></dl>
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
if the compression is fully supported,
'''ARCHIVE_WARN'''
if the compression is supported only through an external program.
'''archive_read_support_filter_none'''()
always succeeds.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPagerchiveead3]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadormat3]],
[[ManPageibarchive3]]

174
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadFormat3.wiki vendored Normal file
View file

@ -0,0 +1,174 @@
ARCHIVE_READ_FORMAT(3) manual page
== NAME ==
'''archive_read_support_format_7zip''',
'''archive_read_support_format_all''',
'''archive_read_support_format_ar''',
'''archive_read_support_format_by_code''',
'''archive_read_support_format_cab''',
'''archive_read_support_format_cpio''',
'''archive_read_support_format_empty''',
'''archive_read_support_format_iso9660''',
'''archive_read_support_format_lha''',
'''archive_read_support_format_mtree''',
'''archive_read_support_format_rar''',
'''archive_read_support_format_raw''',
'''archive_read_support_format_tar''',
'''archive_read_support_format_xar''',
'''archive_read_support_format_zip'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_read_support_format_7zip'''(''struct archive *'');
<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_by_code'''(''struct archive *'', ''int'');
<br>
''int''
<br>
'''archive_read_support_format_cab'''(''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_lha'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_format_mtree'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_format_rar'''(''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_xar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_support_format_zip'''(''struct archive *'');
== DESCRIPTION ==
<dl>
<dt>
'''archive_read_support_format_7zip'''(),
'''archive_read_support_format_ar'''(),
'''archive_read_support_format_cab'''(),
'''archive_read_support_format_cpio'''(),
'''archive_read_support_format_iso9660'''(),
'''archive_read_support_format_lha'''(),
'''archive_read_support_format_mtree'''(),
'''archive_read_support_format_rar'''(),
'''archive_read_support_format_raw'''(),
'''archive_read_support_format_tar'''(),
'''archive_read_support_format_xar'''(),
'''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.
</dd><dt>'''archive_read_support_format_all'''()</dt><dd>
Enables support for all available formats except the
"raw"
format (see below).
</dd><dt>'''archive_read_support_format_by_code'''()</dt><dd>
Enables a single format specified by the format code.
This can be useful when reading a single archive twice;
use
'''archive_format'''()
after reading the first time and pass the resulting code
to this function to selectively enable only the necessary
format support.
Note: In statically-linked executables, this will cause
your program to include support for every format.
If executable size is a concern, you may wish to avoid
using this function.
</dd><dt>'''archive_read_support_format_empty'''()</dt><dd>
Enables support for treating empty files as empty archives.
Because empty files are valid for several different formats,
it is not possible to accurately determine a format for
an empty file based purely on contents.
So empty files are treated by libarchive as a distinct
format.
</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></dl>
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[ManPageTar5]]
== 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.
Using the
"raw"
handler together with any other handler will often work
but can produce surprising results.

68
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadFree3.wiki vendored Normal file
View file

@ -0,0 +1,68 @@
ARCHIVE_READ_FREE(3) manual page
== NAME ==
'''archive_read_close''',
'''archive_read_finish''',
'''archive_read_free'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_read_close'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_finish'''(''struct archive *'');
<br>
''int''
<br>
'''archive_read_free'''(''struct archive *'');
== DESCRIPTION ==
<dl>
<dt>'''archive_read_close'''()</dt><dd>
Complete the archive and invoke the close callback.
</dd><dt>'''archive_read_finish'''()</dt><dd>
This is a deprecated synonym for
'''archive_read_free'''().
The new name was introduced with libarchive 3.0.
Applications that need to compile with either libarchive 2
or libarchive 3 should continue to use the
'''archive_read_finish'''()
name.
Both names will be supported until libarchive 4.0 is
released, which is not expected to occur earlier
than 2013.
</dd><dt>'''archive_read_free'''()</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>
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadew3]],
[[ManPagerchiveeadpen3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]]

63
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadHeader3.wiki vendored Normal file
View file

@ -0,0 +1,63 @@
ARCHIVE_READ_HEADER(3) manual page
== NAME ==
'''archive_read_next_header''',
'''archive_read_next_header2'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_read_next_header'''(''struct archive *'', ''struct archive_entry **'');
<br>
''int''
<br>
'''archive_read_next_header2'''(''struct archive *'', ''struct archive_entry *'');
== DESCRIPTION ==
<dl>
<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></dl>
== RETURN VALUES ==
These functions return
'''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).
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadxtract3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadpen3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[ManPageTar5]]

32
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadNew3.wiki vendored Normal file
View file

@ -0,0 +1,32 @@
ARCHIVE_READ_NEW(3) manual page
== NAME ==
'''archive_read_new'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''struct archive *''
<br>
'''archive_read_new'''(''void'');
== DESCRIPTION ==
Allocates and initializes a
'''struct archive'''
object suitable for reading from an archive.
NULL
is returned on error.
A complete description of the
'''struct archive'''
object can be found in the overview manual page for
[[ManPageibarchive3]].
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[ManPageTar5]]

190
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadOpen3.wiki vendored Normal file
View file

@ -0,0 +1,190 @@
ARCHIVE_READ_OPEN(3) manual page
== NAME ==
'''archive_read_open''',
'''archive_read_open2''',
'''archive_read_open_fd''',
'''archive_read_open_FILE''',
'''archive_read_open_filename''',
'''archive_read_open_memory'''
- functions for reading streaming archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<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 *'', ''const void *buff'', ''size_t size'');
== DESCRIPTION ==
<dl>
<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></dl>
A complete description of the
'''struct archive'''
and
'''struct archive_entry'''
objects can be found in the overview manual page for
[[ManPageibarchive3]].
== CLIENT CALLBACKS ==
The callback functions must match the following prototypes:
<ul>
<li>
''typedef la_ssize_t''
'''archive_read_callback'''(''struct archive *'', ''void *client_data'', ''const void **buffer'')
</li><li>
''typedef la_int64_t''
'''archive_skip_callback'''(''struct archive *'', ''void *client_data'', ''off_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
```text
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'''.
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiveeadata3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPageibarchive3]],
[[ManPageTar5]]

218
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveReadSetOptions3.wiki vendored Normal file
View file

@ -0,0 +1,218 @@
ARCHIVE_READ_OPTIONS(3) manual page
== NAME ==
'''archive_read_set_filter_option''',
'''archive_read_set_format_option''',
'''archive_read_set_option''',
'''archive_read_set_options'''
- functions controlling options for reading archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
<br>
''int''
<br>
'''archive_read_set_filter_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
<br>
''int''
<br>
'''archive_read_set_format_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
<br>
''int''
<br>
'''archive_read_set_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
<br>
''int''
<br>
'''archive_read_set_options'''(''struct archive *'', ''const char *options'');
== DESCRIPTION ==
These functions provide a way for libarchive clients to configure
specific read modules.
<dl>
<dt>
'''archive_read_set_filter_option'''(),
'''archive_read_set_format_option'''()
</dt> <dd>
Specifies an option that will be passed to currently-registered
filters (including decompression filters) or format readers.
If
''option''
and
''value''
are both
NULL,
these functions will do nothing and
'''ARCHIVE_OK'''
will be returned.
If
''option''
is
NULL
but
''value''
is not, these functions will do nothing and
'''ARCHIVE_FAILED'''
will be returned.
If
''module''
is not
NULL,
''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,
'''ARCHIVE_FAILED'''
will be returned.
If
''module''
is
NULL,
''option''
and
''value''
will be provided to every registered module.
If any module returns
'''ARCHIVE_FATAL''',
this value will be returned immediately.
Otherwise,
'''ARCHIVE_OK'''
will be returned if any module accepts the option, and
'''ARCHIVE_FAILED'''
in all other cases.
</dd><dt>
'''archive_read_set_option'''()
</dt> <dd>
Calls
'''archive_read_set_format_option'''(),
then
'''archive_read_set_filter_option'''().
If either function returns
'''ARCHIVE_FATAL''',
'''ARCHIVE_FATAL'''
will be returned
immediately.
Otherwise, greater of the two values will be returned.
</dd><dt>
'''archive_read_set_options'''()
</dt> <dd>
''options''
is a comma-separated list of options.
If
''options''
is
NULL
or empty,
'''ARCHIVE_OK'''
will be returned immediately.
Calls
'''archive_read_set_option'''()
with each option in turn.
If any
'''archive_read_set_option'''()
call returns
'''ARCHIVE_FATAL''',
'''ARCHIVE_FATAL'''
will be returned immediately.
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>
</dd></dl>
== OPTIONS ==
<dl>
<dt>Format cab</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd></dl>
</dd><dt>Format cpio</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd></dl>
</dd><dt>Format iso9660</dt><dd>
<dl>
<dt>'''joliet'''</dt><dd>
Support Joliet extensions.
Defaults to enabled, use
'''!joliet'''
to disable.
</dd><dt>'''rockridge'''</dt><dd>
Support RockRidge extensions.
Defaults to enabled, use
'''!rockridge'''
to disable.
</dd></dl>
</dd><dt>Format lha</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd></dl>
</dd><dt>Format mtree</dt><dd>
<dl>
<dt>'''checkfs'''</dt><dd>
Allow reading information missing from the mtree from the file system.
Disabled by default.
</dd></dl>
</dd><dt>Format rar</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd></dl>
</dd><dt>Format tar</dt><dd>
<dl>
<dt>'''compat-2x'''</dt><dd>
Libarchive 2.x incorrectly encoded Unicode filenames on
some platforms.
This option mimics the libarchive 2.x filename handling
so that such archives can be read correctly.
</dd><dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd><dt>'''mac-ext'''</dt><dd>
Support Mac OS metadata extension that records data in special
files beginning with a period and underscore.
Defaults to enabled on Mac OS, disabled on other platforms.
Use
'''!mac-ext'''
to disable.
</dd><dt>'''read_concatenated_archives'''</dt><dd>
Ignore zeroed blocks in the archive, which occurs when multiple tar archives
have been concatenated together.
Without this option, only the contents of
the first concatenated archive would be read.
</dd></dl>
</dd></dl>
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]]

218
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveUtil3.wiki vendored Normal file
View file

@ -0,0 +1,218 @@
ARCHIVE_UTIL(3) manual page
== NAME ==
'''archive_clear_error''',
'''archive_compression''',
'''archive_compression_name''',
'''archive_copy_error''',
'''archive_errno''',
'''archive_error_string''',
'''archive_file_count''',
'''archive_filter_code''',
'''archive_filter_count''',
'''archive_filter_name''',
'''archive_format''',
'''archive_format_name''',
'''archive_position''',
'''archive_set_error'''
- libarchive utility functions
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''void''
<br>
'''archive_clear_error'''(''struct archive *'');
<br>
''int''
<br>
'''archive_compression'''(''struct archive *'');
<br>
''const char *''
<br>
'''archive_compression_name'''(''struct archive *'');
<br>
''void''
<br>
'''archive_copy_error'''(''struct archive *'', ''struct archive *'');
<br>
''int''
<br>
'''archive_errno'''(''struct archive *'');
<br>
''const char *''
<br>
'''archive_error_string'''(''struct archive *'');
<br>
''int''
<br>
'''archive_file_count'''(''struct archive *'');
<br>
''int''
<br>
'''archive_filter_code'''(''struct archive *'', ''int'');
<br>
''int''
<br>
'''archive_filter_count'''(''struct archive *'', ''int'');
<br>
''const char *''
<br>
'''archive_filter_name'''(''struct archive *'', ''int'');
<br>
''int''
<br>
'''archive_format'''(''struct archive *'');
<br>
''const char *''
<br>
'''archive_format_name'''(''struct archive *'');
<br>
''int64_t''
<br>
'''archive_position'''(''struct archive *'', ''int'');
<br>
''void''
<br>
'''archive_set_error'''(''struct archive *'', ''int error_code'', ''const char *fmt'', ''...'');
== DESCRIPTION ==
These functions provide access to various information about the
'''struct archive'''
object used in the
[[ManPageibarchive3]]
library.
<dl>
<dt>'''archive_clear_error'''()</dt><dd>
Clears any error information left over from a previous call.
Not generally used in client code.
</dd><dt>'''archive_compression'''()</dt><dd>
Synonym for
'''archive_filter_code'''(''a'', ''0'').
</dd><dt>'''archive_compression_name'''()</dt><dd>
Synonym for
'''archive_filter_name'''(''a'', ''0'').
</dd><dt>'''archive_copy_error'''()</dt><dd>
Copies error information from one archive to another.
</dd><dt>'''archive_errno'''()</dt><dd>
Returns a numeric error code (see
[[errno(2)|http://www.freebsd.org/cgi/man.cgi?query=errno&sektion=2]])
indicating the reason for the most recent error return.
Note that this can not be reliably used to detect whether an
error has occurred.
It should be used only after another libarchive function
has returned an error status.
</dd><dt>'''archive_error_string'''()</dt><dd>
Returns a textual error message suitable for display.
The error message here is usually more specific than that
obtained from passing the result of
'''archive_errno'''()
to
[[strerror(3)|http://www.freebsd.org/cgi/man.cgi?query=strerror&sektion=3]].
</dd><dt>'''archive_file_count'''()</dt><dd>
Returns a count of the number of files processed by this archive object.
The count is incremented by calls to
[[ManPagerchiveriteeader3]]
or
[[ManPagerchiveeadexteader3]].
</dd><dt>'''archive_filter_code'''()</dt><dd>
Returns a numeric code identifying the indicated filter.
See
'''archive_filter_count'''()
for details of the numbering.
</dd><dt>'''archive_filter_count'''()</dt><dd>
Returns the number of filters in the current pipeline.
For read archive handles, these filters are added automatically
by the automatic format detection.
For write archive handles, these filters are added by calls to the various
'''archive_write_add_filter_XXX'''()
functions.
Filters in the resulting pipeline are numbered so that filter 0
is the filter closest to the format handler.
As a convenience, functions that expect a filter number will
accept -1 as a synonym for the highest-numbered filter.
For example, when reading a uuencoded gzipped tar archive, there
are three filters:
filter 0 is the gunzip filter,
filter 1 is the uudecode filter,
and filter 2 is the pseudo-filter that wraps the archive read functions.
In this case, requesting
'''archive_position'''(''a'', ''-1'')
would be a synonym for
'''archive_position'''(''a'', ''2'')
which would return the number of bytes currently read from the archive, while
'''archive_position'''(''a'', ''1'')
would return the number of bytes after uudecoding, and
'''archive_position'''(''a'', ''0'')
would return the number of bytes after decompression.
</dd><dt>'''archive_filter_name'''()</dt><dd>
Returns a textual name identifying the indicated filter.
See
'''archive_filter_count'''()
for details of the numbering.
</dd><dt>'''archive_format'''()</dt><dd>
Returns a numeric code indicating the format of the current
archive entry.
This value is set by a successful call to
'''archive_read_next_header'''().
Note that it is common for this value to change from
entry to entry.
For example, a tar archive might have several entries that
utilize GNU tar extensions and several entries that do not.
These entries will have different format codes.
</dd><dt>'''archive_format_name'''()</dt><dd>
A textual description of the format of the current entry.
</dd><dt>'''archive_position'''()</dt><dd>
Returns the number of bytes read from or written to the indicated filter.
In particular,
'''archive_position'''(''a'', ''0'')
returns the number of bytes read or written by the format handler, while
'''archive_position'''(''a'', ''-1'')
returns the number of bytes read or written to the archive.
See
'''archive_filter_count'''()
for details of the numbering here.
</dd><dt>'''archive_set_error'''()</dt><dd>
Sets the numeric error code and error description that will be returned
by
'''archive_errno'''()
and
'''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.
However, you should be careful to use only the following printf
format specifiers:
"%c",
"%d",
"%jd",
"%jo",
"%ju",
"%jx",
"%ld",
"%lo",
"%lu",
"%lx",
"%o",
"%u",
"%s",
"%x",
"%%".
Field-width specifiers and other printf features are
not uniformly supported and should not be used.
</dd></dl>
== SEE ALSO ==
[[ManPagerchiveead3]],
[[ManPagerchiverite3]],
[[ManPageibarchive3]],
[[printf(3)|http://www.freebsd.org/cgi/man.cgi?query=printf&sektion=3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The
'''libarchive'''
library was written by
Tim Kientzle &lt;kientzle@acm.org.&gt;

222
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWrite3.wiki vendored Normal file
View file

@ -0,0 +1,222 @@
ARCHIVE_WRITE(3) manual page
== NAME ==
'''archive_write'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
== DESCRIPTION ==
These functions provide a complete API for creating streaming
archive files.
The general process is to first create the
'''struct archive'''
object, set any desired options, initialize the archive, append entries, then
close the archive and release all resources.
=== Create archive object===
See
[[ManPagerchiveriteew3]].
To write an archive, you must first obtain an initialized
'''struct archive'''
object from
'''archive_write_new'''().
=== Enable filters and formats, configure block size and padding===
See
[[ManPagerchiveriteilter3]],
[[ManPagerchiveriteormat3]]
and
[[ManPagerchiveritelocksize3]].
You can then modify this object for the desired operations with the
various
'''archive_write_set_XXX'''()
functions.
In particular, you will need to invoke appropriate
'''archive_write_add_XXX'''()
and
'''archive_write_set_XXX'''()
functions to enable the corresponding compression and format
support.
=== Set options===
See
[[ManPagerchiveriteetptions3]].
=== Open archive===
See
[[ManPagerchiveritepen3]].
Once you have prepared the
'''struct archive'''
object, you call
'''archive_write_open'''()
to actually open the archive and prepare it for writing.
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 write the archive data.
=== Produce archive===
See
[[ManPagerchiveriteeader3]]
and
[[ManPagerchiveriteata3]].
Individual archive entries are written in a three-step
process:
You first initialize a
'''struct archive_entry'''
structure with information about the new entry.
At a minimum, you should set the pathname of the
entry and provide a
''struct'' stat
with a valid
''st_mode''
field, which specifies the type of object and
''st_size''
field, which specifies the size of the data portion of the object.
=== Release resources===
See
[[ManPagerchiveriteree3]].
After all entries have been written, use the
'''archive_write_free'''()
function to release all resources.
== EXAMPLES ==
The following sketch 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]],
[[write(2)|http://www.freebsd.org/cgi/man.cgi?query=write&sektion=2]],
and
[[close(2)|http://www.freebsd.org/cgi/man.cgi?query=close&sektion=2]]
system calls.
```text
#ifdef __linux__
#define _FILE_OFFSET_BITS 64
#endif
#include <sys/stat.h>
#include <archive.h>
#include <archive_entry.h>
#include <fcntl.h>
#include <stdlib.h>
#include <unistd.h>
struct mydata {
const char *name;
int fd;
};
int
myopen(struct archive *a, void *client_data)
{
struct mydata *mydata = client_data;
mydata->fd = open(mydata->name, O_WRONLY | O_CREAT, 0644);
if (mydata->fd >= 0)
return (ARCHIVE_OK);
else
return (ARCHIVE_FATAL);
}
la_ssize_t
mywrite(struct archive *a, void *client_data, const void *buff, size_t n)
{
struct mydata *mydata = client_data;
return (write(mydata->fd, buff, n));
}
int
myclose(struct archive *a, void *client_data)
{
struct mydata *mydata = client_data;
if (mydata->fd > 0)
close(mydata->fd);
return (0);
}
void
write_archive(const char *outname, const char **filename)
{
struct mydata *mydata = malloc(sizeof(struct mydata));
struct archive *a;
struct archive_entry *entry;
struct stat st;
char buff[8192];
int len;
int fd;
a = archive_write_new();
mydata->name = outname;
/* Set archive format and filter according to output file extension.
* If it fails, set default format. Platform depended function.
* See supported formats in archive_write_set_format_filter_by_ext.c */
if (archive_write_set_format_filter_by_ext(a, outname) != ARCHIVE_OK) {
archive_write_add_filter_gzip(a);
archive_write_set_format_ustar(a);
}
archive_write_open(a, mydata, myopen, mywrite, myclose);
while (*filename) {
stat(*filename, &st);
entry = archive_entry_new();
archive_entry_copy_stat(entry, &st);
archive_entry_set_pathname(entry, *filename);
archive_write_header(a, entry);
if ((fd = open(*filename, O_RDONLY)) != -1) {
len = read(fd, buff, sizeof(buff));
while (len > 0) {
archive_write_data(a, buff, len);
len = read(fd, buff, sizeof(buff));
}
close(fd);
}
archive_entry_free(entry);
filename++;
}
archive_write_free(a);
}
int main(int argc, const char **argv)
{
const char *outname;
argv++;
outname = *argv++;
write_archive(outname, argv);
return 0;
}
```
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[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 ==
There are many peculiar bugs in historic tar implementations that may cause
certain programs to reject archives written by this library.
For example, several historic implementations calculated header checksums
incorrectly and will thus reject valid archives; GNU tar does not fully support
pax interchange format; some old tar implementations required specific
field terminations.
The default pax interchange format eliminates most of the historic
tar limitations and provides a generic key/value attribute facility
for vendor-defined extensions.
One oversight in POSIX is the failure to provide a standard attribute
for large device numbers.
This library uses
"SCHILY.devminor"
and
"SCHILY.devmajor"
for device numbers that exceed the range supported by the backwards-compatible
ustar header.
These keys are compatible with Joerg Schilling's
'''star'''
archiver.
Other implementations may not recognize these keys and will thus be unable
to correctly restore device nodes with large device numbers from archives
created by this library.

93
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteBlocksize3.wiki vendored Normal file
View file

@ -0,0 +1,93 @@
ARCHIVE_WRITE_BLOCKSIZE(3) manual page
== NAME ==
'''archive_write_get_bytes_per_block''',
'''archive_write_set_bytes_per_block''',
'''archive_write_get_bytes_in_last_block''',
'''archive_write_set_bytes_in_last_block'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_get_bytes_per_block'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_bytes_per_block'''(''struct archive *'', ''int bytes_per_block'');
<br>
''int''
<br>
'''archive_write_get_bytes_in_last_block'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_bytes_in_last_block'''(''struct archive *'', ''int'');
== DESCRIPTION ==
<dl>
<dt>'''archive_write_set_bytes_per_block'''()</dt><dd>
Sets the block size used for writing the archive data.
Every call to the write callback function, except possibly the last one, will
use this value for the length.
The default is to use a block size of 10240 bytes.
Note that a block size of zero will suppress internal blocking
and cause writes to be sent directly to the write callback as they occur.
</dd><dt>'''archive_write_get_bytes_per_block'''()</dt><dd>
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.
</dd><dt>'''archive_write_set_bytes_in_last_block'''()</dt><dd>
Sets the block size used for writing the last block.
If this value is zero, the last block will be padded to the same size
as the other blocks.
Otherwise, the final block will be padded to a multiple of this size.
In particular, setting it to 1 will cause the final block to not be padded.
For compressed output, any padding generated by this option
is applied only after the compression.
The uncompressed data is always unpadded.
The default is to pad the last block to the full block size (note that
'''archive_write_open_filename'''()
will set this based on the file type).
Unlike the other
"set"
functions, this function can be called after the archive is opened.
</dd><dt>'''archive_write_get_bytes_in_last_block'''()</dt><dd>
Retrieve the currently-set value for last block size.
A value of -1 here indicates that the library should use default values.
</dd></dl>
== RETURN VALUES ==
'''archive_write_set_bytes_per_block'''()
and
'''archive_write_set_bytes_in_last_block'''()
return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
'''archive_write_get_bytes_per_block'''()
and
'''archive_write_get_bytes_in_last_block'''()
return currently configured block size
Po
```text
-1
```
indicates the default block size
Pc,
or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

61
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteData3.wiki vendored Normal file
View file

@ -0,0 +1,61 @@
ARCHIVE_WRITE_DATA(3) manual page
== NAME ==
'''archive_write_data''',
'''archive_write_data_block'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''la_ssize_t''
<br>
'''archive_write_data'''(''struct archive *'', ''const void *'', ''size_t'');
<br>
''la_ssize_t''
<br>
'''archive_write_data_block'''(''struct archive *'', ''const void *'', ''size_t size'', ''int64_t offset'');
== DESCRIPTION ==
<dl>
<dt>'''archive_write_data'''()</dt><dd>
Write data corresponding to the header just written.
</dd><dt>'''archive_write_data_block'''()</dt><dd>
Write data corresponding to the header just written.
This is like
'''archive_write_data'''()
except that it performs a seek on the file being
written to the specified offset before writing the data.
This is useful when restoring sparse files from archive
formats that support sparse files.
Returns number of bytes written or -1 on error.
(Note: This is currently not supported for
'''archive_write'''
handles, only for
'''archive_write_disk'''
handles.
</dd></dl>
== RETURN VALUES ==
This function returns the number of bytes actually written, or
a negative error code on error.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== BUGS ==
In libarchive 3.x, this function sometimes returns
zero on success instead of returning the number of bytes written.
Specifically, this occurs when writing to an
''archive_write_disk''
handle.
Clients should treat any value less than zero as an error
and consider any non-negative value as success.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveriteinishntry3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

335
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteDisk3.wiki vendored Normal file
View file

@ -0,0 +1,335 @@
ARCHIVE_WRITE_DISK(3) manual page
== NAME ==
'''archive_write_disk_new''',
'''archive_write_disk_set_options''',
'''archive_write_disk_set_skip_file''',
'''archive_write_disk_set_group_lookup''',
'''archive_write_disk_set_standard_lookup''',
'''archive_write_disk_set_user_lookup'''
- functions for creating objects on disk
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''struct archive *''
<br>
'''archive_write_disk_new'''(''void'');
<br>
''int''
<br>
'''archive_write_disk_set_options'''(''struct archive *'', ''int flags'');
<br>
''int''
<br>
'''archive_write_disk_set_skip_file'''(''struct archive *'', ''dev_t'', ''ino_t'');
<br>
''int''
<br>
'''archive_write_disk_set_group_lookup'''(''struct archive *'', ''void *'', ''gid_t (*)(void *, const char *gname, gid_t gid)'', ''void (*cleanup)(void *)'');
<br>
''int''
<br>
'''archive_write_disk_set_standard_lookup'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_disk_set_user_lookup'''(''struct archive *'', ''void *'', ''uid_t (*)(void *, const char *uname, uid_t uid)'', ''void (*cleanup)(void *)'');
== DESCRIPTION ==
These functions provide a complete API for creating objects on
disk from
'''struct archive_entry'''
descriptions.
They are most naturally used when extracting objects from an archive
using the
'''archive_read'''()
interface.
The general process is to read
'''struct archive_entry'''
objects from an archive, then write those objects to a
'''struct archive'''
object created using the
'''archive_write_disk'''()
family functions.
This interface is deliberately very similar to the
'''archive_write'''()
interface used to write objects to a streaming archive.
<dl>
<dt>'''archive_write_disk_new'''()</dt><dd>
Allocates and initializes a
'''struct archive'''
object suitable for writing objects to disk.
</dd><dt>'''archive_write_disk_set_skip_file'''()</dt><dd>
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.
</dd><dt>'''archive_write_disk_set_options'''()</dt><dd>
The options field consists of a bitwise OR of one or more of the
following values:
<dl>
<dt>'''ARCHIVE_EXTRACT_ACL'''</dt><dd>
Attempt to restore Access Control Lists.
By default, extended ACLs are ignored.
</dd><dt>'''ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS'''</dt><dd>
Before removing a file system object prior to replacing it, clear
platform-specific file flags which might prevent its removal.
</dd><dt>'''ARCHIVE_EXTRACT_FFLAGS'''</dt><dd>
Attempt to restore file attributes (file flags).
By default, file attributes are ignored.
See
[[chattr(1)|http://www.freebsd.org/cgi/man.cgi?query=chattr&sektion=1]]
(Linux)
or
[[chflags(1)|http://www.freebsd.org/cgi/man.cgi?query=chflags&sektion=1]]
(FreeBSD, Mac OS X)
for more information on file attributes.
</dd><dt>'''ARCHIVE_EXTRACT_MAC_METADATA'''</dt><dd>
Mac OS X specific.
Restore metadata using
[[copyfile(3)|http://www.freebsd.org/cgi/man.cgi?query=copyfile&sektion=3]].
By default,
[[copyfile(3)|http://www.freebsd.org/cgi/man.cgi?query=copyfile&sektion=3]]
metadata is ignored.
</dd><dt>'''ARCHIVE_EXTRACT_NO_OVERWRITE'''</dt><dd>
Existing files on disk will not be overwritten.
By default, existing regular files are truncated and overwritten;
existing directories will have their permissions updated;
other pre-existing objects are unlinked and recreated from scratch.
</dd><dt>'''ARCHIVE_EXTRACT_OWNER'''</dt><dd>
The user and group IDs should be set on the restored file.
By default, the user and group IDs are not restored.
</dd><dt>'''ARCHIVE_EXTRACT_PERM'''</dt><dd>
Full permissions (including SGID, SUID, and sticky bits) should
be restored exactly as specified, without obeying the
current umask.
Note that SUID and SGID bits can only be restored if the
user and group ID of the object on disk are correct.
If
'''ARCHIVE_EXTRACT_OWNER'''
is not specified, then SUID and SGID bits will only be restored
if the default user and group IDs of newly-created objects on disk
happen to match those specified in the archive entry.
By default, only basic permissions are restored, and umask is obeyed.
</dd><dt>'''ARCHIVE_EXTRACT_SAFE_WRITES'''</dt><dd>
Extract files atomically, by first creating a unique temporary file and then
renaming it to its required destination name.
This avoids a race where an application might see a partial file (or no
file) during extraction.
</dd><dt>'''ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS'''</dt><dd>
Refuse to extract an absolute path.
The default is to not refuse such paths.
</dd><dt>'''ARCHIVE_EXTRACT_SECURE_NODOTDOT'''</dt><dd>
Refuse to extract a path that contains a
''..''
element anywhere within it.
The default is to not refuse such paths.
Note that paths ending in
''..''
always cause an error, regardless of this flag.
</dd><dt>'''ARCHIVE_EXTRACT_SECURE_SYMLINKS'''</dt><dd>
Refuse to extract any object whose final location would be altered
by a symlink on disk.
This is intended to help guard against a variety of mischief
caused by archives that (deliberately or otherwise) extract
files outside of the current directory.
The default is not to perform this check.
If
</dd><dt>'''ARCHIVE_EXTRACT_SPARSE'''</dt><dd>
Scan data for blocks of NUL bytes and try to recreate them with holes.
This results in sparse files, independent of whether the archive format
supports or uses them.
'''ARCHIVE_EXTRACT_UNLINK'''
is specified together with this option, the library will
remove any intermediate symlinks it finds and return an
error only if such symlink could not be removed.
</dd><dt>'''ARCHIVE_EXTRACT_TIME'''</dt><dd>
The timestamps (mtime, ctime, and atime) should be restored.
By default, they are ignored.
Note that restoring of atime is not currently supported.
</dd><dt>'''ARCHIVE_EXTRACT_UNLINK'''</dt><dd>
Existing files on disk will be unlinked before any attempt to
create them.
In some cases, this can prove to be a significant performance improvement.
By default, existing files are truncated and rewritten, but
the file is not recreated.
In particular, the default behavior does not break existing hard links.
</dd><dt>'''ARCHIVE_EXTRACT_XATTR'''</dt><dd>
Attempt to restore extended file attributes.
By default, they are ignored.
See
[[xattr(7)|http://www.freebsd.org/cgi/man.cgi?query=xattr&sektion=7]]
(Linux,)
[[xattr(2)|http://www.freebsd.org/cgi/man.cgi?query=xattr&sektion=2]]
(Mac OS X,)
or
[[getextattr(8)|http://www.freebsd.org/cgi/man.cgi?query=getextattr&sektion=8]]
(FreeBSD)
for more information on extended file attributes.
</dd></dl>
</dd><dt>
'''archive_write_disk_set_group_lookup'''(),
'''archive_write_disk_set_user_lookup'''()
</dt> <dd>
The
'''struct archive_entry'''
objects contain both names and ids that can be used to identify users
and groups.
These names and ids describe the ownership of the file itself and
also appear in ACL lists.
By default, the library uses the ids and ignores the names, but
this can be overridden by registering user and group lookup functions.
To register, you must provide a lookup function which
accepts both a name and id and returns a suitable id.
You may also provide a
'''void *'''
pointer to a private data structure and a cleanup function for
that data.
The cleanup function will be invoked when the
'''struct archive'''
object is destroyed.
</dd><dt>'''archive_write_disk_set_standard_lookup'''()</dt><dd>
This convenience function installs a standard set of user
and group lookup functions.
These functions use
[[getpwnam(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwnam&sektion=3]]
and
[[getgrnam(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrnam&sektion=3]]
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
[[getpwnam(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwnam&sektion=3]]
and
[[getgrnam(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrnam&sektion=3]].
</dd></dl>
More information about the
''struct'' archive
object and the overall design of the library can be found in the
[[ManPageibarchive3]]
overview.
Many of these functions are also documented under
[[ManPagerchiverite3]].
== RETURN VALUES ==
Most functions return
'''ARCHIVE_OK'''
(zero) on success, or one of several non-zero
error codes for errors.
Specific error codes include:
'''ARCHIVE_RETRY'''
for operations that might succeed if retried,
'''ARCHIVE_WARN'''
for unusual conditions that do not prevent further operations, and
'''ARCHIVE_FATAL'''
for serious errors that make remaining operations impossible.
'''archive_write_disk_new'''()
returns a pointer to a newly-allocated
'''struct archive'''
object.
'''archive_write_data'''()
returns a count of the number of bytes actually written,
or
```text
-1
```
on error.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveead3]],
[[ManPagerchiverite3]],
[[ManPageibarchive3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
The
'''archive_write_disk'''
interface was added to
'''libarchive''' 2.0
and first appeared in
FreeBSD 6.3.
== AUTHORS ==
The
'''libarchive'''
library was written by
Tim Kientzle &lt;kientzle@acm.org.&gt;
== BUGS ==
Directories are actually extracted in two distinct phases.
Directories are created during
'''archive_write_header'''(),
but final permissions are not set until
'''archive_write_close'''().
This separation is necessary to correctly handle borderline
cases such as a non-writable directory containing
files, but can cause unexpected results.
In particular, directory permissions are not fully
restored until the archive is closed.
If you use
[[chdir(2)|http://www.freebsd.org/cgi/man.cgi?query=chdir&sektion=2]]
to change the current directory between calls to
'''archive_read_extract'''()
or before calling
'''archive_read_close'''(),
you may confuse the permission-setting logic with
the result that directory permissions are restored
incorrectly.
The library attempts to create objects with filenames longer than
'''PATH_MAX'''
by creating prefixes of the full path and changing the current directory.
Currently, this logic is limited in scope; the fixup pass does
not work correctly for such objects and the symlink security check
option disables the support for very long pathnames.
Restoring the path
''aa/../bb''
does create each intermediate directory.
In particular, the directory
''aa''
is created as well as the final object
''bb''.
In theory, this can be exploited to create an entire directory hierarchy
with a single request.
Of course, this does not work if the
'''ARCHIVE_EXTRACT_NODOTDOT'''
option is specified.
Implicit directories are always created obeying the current umask.
Explicit objects are created obeying the current umask unless
'''ARCHIVE_EXTRACT_PERM'''
is specified, in which case they current umask is ignored.
SGID and SUID bits are restored only if the correct user and
group could be set.
If
'''ARCHIVE_EXTRACT_OWNER'''
is not specified, then no attempt is made to set the ownership.
In this case, SGID and SUID bits are restored only if the
user and group of the final object happen to match those specified
in the entry.
The
"standard"
user-id and group-id lookup functions are not the defaults because
[[getgrnam(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrnam&sektion=3]]
and
[[getpwnam(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwnam&sektion=3]]
are sometimes too large for particular applications.
The current design allows the application author to use a more
compact implementation when appropriate.
There should be a corresponding
'''archive_read_disk'''
interface that walks a directory hierarchy and returns archive
entry objects.

134
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteFilter3.wiki vendored Normal file
View file

@ -0,0 +1,134 @@
ARCHIVE_WRITE_FILTER(3) manual page
== NAME ==
'''archive_write_add_filter_b64encode''',
'''archive_write_add_filter_by_name''',
'''archive_write_add_filter_bzip2''',
'''archive_write_add_filter_compress''',
'''archive_write_add_filter_grzip''',
'''archive_write_add_filter_gzip''',
'''archive_write_add_filter_lrzip''',
'''archive_write_add_filter_lz4''',
'''archive_write_add_filter_lzip''',
'''archive_write_add_filter_lzma''',
'''archive_write_add_filter_lzop''',
'''archive_write_add_filter_none''',
'''archive_write_add_filter_program''',
'''archive_write_add_filter_uuencode''',
'''archive_write_add_filter_xz''',
'''archive_write_add_filter_zstd'''
- functions enabling output filters
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_add_filter_b64encode'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_bzip2'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_compress'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_grzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_gzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_lrzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_lz4'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_lzip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_lzma'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_lzop'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_none'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_program'''(''struct archive *'', ''const char * cmd'');
<br>
''int''
<br>
'''archive_write_add_filter_uuencode'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_xz'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_add_filter_zstd'''(''struct archive *'');
== DESCRIPTION ==
<dl>
<dt>
'''archive_write_add_filter_bzip2'''(),
'''archive_write_add_filter_compress'''(),
'''archive_write_add_filter_grzip'''(),
'''archive_write_add_filter_gzip'''(),
'''archive_write_add_filter_lrzip'''(),
'''archive_write_add_filter_lz4'''(),
'''archive_write_add_filter_lzip'''(),
'''archive_write_add_filter_lzma'''(),
'''archive_write_add_filter_lzop'''(),
'''archive_write_add_filter_xz'''(),
'''archive_write_add_filter_zstd'''(),
</dt> <dd>
The resulting archive will be compressed as specified.
Note that the compressed output is always properly blocked.
</dd><dt>
'''archive_write_add_filter_b64encode'''(),
'''archive_write_add_filter_uuencode'''(),
</dt> <dd>
The output will be encoded as specified.
The encoded output is always properly blocked.
</dd><dt>'''archive_write_add_filter_none'''()</dt><dd>
This is never necessary.
It is provided only for backwards compatibility.
</dd><dt>'''archive_write_add_filter_program'''()</dt><dd>
The archive will be fed into the specified compression program.
The output of that program is blocked and written to the client
write callbacks.
</dd></dl>
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteormat3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

50
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteFinishEntry3.wiki vendored Normal file
View file

@ -0,0 +1,50 @@
ARCHIVE_WRITE_FINISH_ENTRY(3) manual page
== NAME ==
'''archive_write_finish_entry'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_finish_entry'''(''struct archive *'');
== DESCRIPTION ==
Close out the entry just written.
In particular, this writes out the final padding required by some formats.
Ordinarily, clients never need to call this, as it
is called automatically by
'''archive_write_header'''()
and
'''archive_write_close'''()
as needed.
For
'''archive_write_disk'''
handles, this flushes pending file attribute changes like modification time.
== RETURN VALUES ==
This function returns
'''ARCHIVE_OK'''
on success, or one of several non-zero
error codes for errors.
Specific error codes include:
'''ARCHIVE_RETRY'''
for operations that might succeed if retried,
'''ARCHIVE_WARN'''
for unusual conditions that do not prevent further operations, and
'''ARCHIVE_FATAL'''
for serious errors that make remaining operations impossible.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveriteata3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

190
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteFormat3.wiki vendored Normal file
View file

@ -0,0 +1,190 @@
ARCHIVE_WRITE_FORMAT(3) manual page
== NAME ==
'''archive_write_set_format''',
'''archive_write_set_format_7zip''',
'''archive_write_set_format_ar''',
'''archive_write_set_format_ar_bsd''',
'''archive_write_set_format_ar_svr4''',
'''archive_write_set_format_by_name''',
'''archive_write_set_format_cpio''',
'''archive_write_set_format_cpio_newc''',
'''archive_write_set_format_filter_by_ext''',
'''archive_write_set_format_filter_by_ext_def''',
'''archive_write_set_format_gnutar''',
'''archive_write_set_format_iso9660''',
'''archive_write_set_format_mtree''',
'''archive_write_set_format_mtree_classic''',
'''archive_write_set_format_mtree_default''',
'''archive_write_set_format_pax''',
'''archive_write_set_format_pax_restricted''',
'''archive_write_set_format_raw''',
'''archive_write_set_format_shar''',
'''archive_write_set_format_shar_dump''',
'''archive_write_set_format_ustar''',
'''archive_write_set_format_v7tar''',
'''archive_write_set_format_warc''',
'''archive_write_set_format_xar''',
'''archive_write_set_format_zip'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_set_format'''(''struct archive *'', ''int code'');
<br>
''int''
<br>
'''archive_write_set_format_7zip'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_ar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_ar_bsd'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_ar_svr4'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_by_name'''(''struct archive *'', ''const char *name'');
<br>
''int''
<br>
'''archive_write_set_format_cpio'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_cpio_newc'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_filter_by_ext'''(''struct archive *'', ''const char *filename'');
<br>
''int''
<br>
'''archive_write_set_format_filter_by_ext_def'''(''struct archive *'', ''const char *filename'', ''const char *def_ext'');
<br>
''int''
<br>
'''archive_write_set_format_gnutar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_iso9660'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_mtree'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_pax'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_pax_restricted'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_raw'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_shar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_shar_dump'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_ustar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_v7tar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_warc'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_xar'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_set_format_zip'''(''struct archive *'');
== DESCRIPTION ==
These functions set the format that will be used for the archive.
The library can write a variety of common archive formats.
<dl>
<dt>'''archive_write_set_format'''()</dt><dd>
Sets the format based on the format code (see
''archive.h''
for the full list of format codes).
In particular, this can be used in conjunction with
'''archive_format'''()
to create a new archive with the same format as an existing archive.
</dd><dt>'''archive_write_set_format_by_name'''()</dt><dd>
Sets the corresponding format based on the common name.
</dd><dt>
'''archive_write_set_format_filter_by_ext'''(),
'''archive_write_set_format_filter_by_ext_def'''()
</dt> <dd>
Sets both filters and format based on the output filename.
Supported extensions: .7z, .zip, .jar, .cpio, .iso, .a, .ar, .tar, .tgz, .tar.gz, .tar.bz2, .tar.xz
</dd><dt>
'''archive_write_set_format_7zip'''()
'''archive_write_set_format_ar_bsd'''(),
'''archive_write_set_format_ar_svr4'''(),
'''archive_write_set_format_cpio'''()
'''archive_write_set_format_cpio_newc'''()
'''archive_write_set_format_gnutar'''()
'''archive_write_set_format_iso9660'''()
'''archive_write_set_format_mtree'''()
'''archive_write_set_format_mtree_classic'''()
'''archive_write_set_format_pax'''()
'''archive_write_set_format_pax_restricted'''()
'''archive_write_set_format_raw'''()
'''archive_write_set_format_shar'''()
'''archive_write_set_format_shar_dump'''()
'''archive_write_set_format_ustar'''()
'''archive_write_set_format_v7tar'''()
'''archive_write_set_format_warc'''()
'''archive_write_set_format_xar'''()
'''archive_write_set_format_zip'''()
</dt> <dd>
Set the format as specified.
More details on the formats supported by libarchive can be found in the
[[ManPageibarchiveormats5]]
manual page.
</dd></dl>
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageibarchiveormats5]],
[[ManPageMtree5]],
[[ManPageTar5]]

73
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteFree3.wiki vendored Normal file
View file

@ -0,0 +1,73 @@
ARCHIVE_WRITE_FREE(3) manual page
== NAME ==
'''archive_write_fail''',
'''archive_write_close''',
'''archive_write_finish''',
'''archive_write_free'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_fail'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_close'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_finish'''(''struct archive *'');
<br>
''int''
<br>
'''archive_write_free'''(''struct archive *'');
== DESCRIPTION ==
<dl>
<dt>'''archive_write_fail'''()</dt><dd>
Always returns
'''ARCHIVE_FATAL'''.
This marks the archive object as being unusable;
after calling this function, the only call that can succeed is
'''archive_write_free'''()
to release the resources.
This can be used to speed recovery when the archive creation
must be aborted.
Note that the created archive is likely to be malformed in this case;
</dd><dt>'''archive_write_close'''()</dt><dd>
Complete the archive and invoke the close callback.
</dd><dt>'''archive_write_finish'''()</dt><dd>
This is a deprecated synonym for
'''archive_write_free'''().
</dd><dt>'''archive_write_free'''()</dt><dd>
Invokes
'''archive_write_close'''()
if necessary, then releases all resources.
If you need detailed information about
'''archive_write_close'''()
failures, you should be careful to call it separately, as
you cannot obtain error information after
'''archive_write_free'''()
returns.
</dd></dl>
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

44
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteHeader3.wiki vendored Normal file
View file

@ -0,0 +1,44 @@
ARCHIVE_WRITE_HEADER(3) manual page
== NAME ==
'''archive_write_header'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_header'''(''struct archive *'', ''struct archive_entry *'');
== DESCRIPTION ==
Build and write a header using the data in the provided
'''struct archive_entry'''
structure.
See
[[ManPagerchiventry3]]
for information on creating and populating
'''struct archive_entry'''
objects.
== RETURN VALUES ==
This function returns
'''ARCHIVE_OK'''
on success, or one of the following on error:
'''ARCHIVE_RETRY'''
for operations that might succeed if retried,
'''ARCHIVE_WARN'''
for unusual conditions that do not prevent further operations, and
'''ARCHIVE_FATAL'''
for serious errors that make remaining operations impossible.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

31
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteNew3.wiki vendored Normal file
View file

@ -0,0 +1,31 @@
ARCHIVE_WRITE_NEW(3) manual page
== NAME ==
'''archive_write_new'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''struct archive *''
<br>
'''archive_write_new'''(''void'');
== DESCRIPTION ==
Allocates and initializes a
'''struct archive'''
object suitable for writing a tar archive.
NULL
is returned on error.
A complete description of the
'''struct archive'''
object can be found in the overview manual page for
[[ManPageibarchive3]].
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

208
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteOpen3.wiki vendored Normal file
View file

@ -0,0 +1,208 @@
ARCHIVE_WRITE_OPEN(3) manual page
== NAME ==
'''archive_write_open''',
'''archive_write_open_fd''',
'''archive_write_open_FILE''',
'''archive_write_open_filename''',
'''archive_write_open_memory'''
- functions for creating archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_open'''(''struct archive *'', ''void *client_data'', ''archive_open_callback *'', ''archive_write_callback *'', ''archive_close_callback *'');
<br>
''int''
<br>
'''archive_write_open_fd'''(''struct archive *'', ''int fd'');
<br>
''int''
<br>
'''archive_write_open_FILE'''(''struct archive *'', ''FILE *file'');
<br>
''int''
<br>
'''archive_write_open_filename'''(''struct archive *'', ''const char *filename'');
<br>
''int''
<br>
'''archive_write_open_memory'''(''struct archive *'', ''void *buffer'', ''size_t bufferSize'', ''size_t *outUsed'');
== DESCRIPTION ==
<dl>
<dt>'''archive_write_open'''()</dt><dd>
Freeze the settings, open the archive, and prepare for writing entries.
This is the most generic form of this function, which accepts
pointers to three callback functions which will be invoked by
the compression layer to write the constructed archive.
This does not alter the default archive padding.
</dd><dt>'''archive_write_open_fd'''()</dt><dd>
A convenience form of
'''archive_write_open'''()
that accepts a file descriptor.
The
'''archive_write_open_fd'''()
function is safe for use with tape drives or other
block-oriented devices.
</dd><dt>'''archive_write_open_FILE'''()</dt><dd>
A convenience form of
'''archive_write_open'''()
that accepts a
''FILE *''
pointer.
Note that
'''archive_write_open_FILE'''()
is not safe for writing to tape drives or other devices
that require correct blocking.
</dd><dt>'''archive_write_open_file'''()</dt><dd>
A deprecated synonym for
'''archive_write_open_filename'''().
</dd><dt>'''archive_write_open_filename'''()</dt><dd>
A convenience form of
'''archive_write_open'''()
that accepts a filename.
A NULL argument indicates that the output should be written to standard output;
an argument of
"-"
will open a file with that name.
If you have not invoked
'''archive_write_set_bytes_in_last_block'''(),
then
'''archive_write_open_filename'''()
will adjust the last-block padding depending on the file:
it will enable padding when writing to standard output or
to a character or block device node, it will disable padding otherwise.
You can override this by manually invoking
'''archive_write_set_bytes_in_last_block'''()
before calling
'''archive_write_open'''().
The
'''archive_write_open_filename'''()
function is safe for use with tape drives or other
block-oriented devices.
</dd><dt>'''archive_write_open_memory'''()</dt><dd>
A convenience form of
'''archive_write_open'''()
that accepts a pointer to a block of memory that will receive
the archive.
The final
''size_t *''
argument points to a variable that will be updated
after each write to reflect how much of the buffer
is currently in use.
You should be careful to ensure that this variable
remains allocated until after the archive is
closed.
This function will disable padding unless you
have specifically set the block size.
</dd></dl>
More information about the
''struct'' archive
object and the overall design of the library can be found in the
[[ManPageibarchive3]]
overview.
Note that the convenience forms above vary in how
they block the output.
See
[[ManPagerchiveritelocksize3]]
if you need to control the block size used for writes
or the end-of-file padding behavior.
== CLIENT CALLBACKS ==
To use this library, you will need to define and register
callback functions that will be invoked to write data to the
resulting archive.
These functions are registered by calling
'''archive_write_open'''():
<ul>
<li>
''typedef int''
'''archive_open_callback'''(''struct archive *'', ''void *client_data'')
</li></ul>
The open callback is invoked by
'''archive_write_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'''.
<ul>
<li>
''typedef la_ssize_t''
'''archive_write_callback'''(''struct archive *'', ''void *client_data'', ''const void *buffer'', ''size_t length'')
</li></ul>
The write callback is invoked whenever the library
needs to write raw bytes to the archive.
For correct blocking, each call to the write callback function
should translate into a single
[[write(2)|http://www.freebsd.org/cgi/man.cgi?query=write&sektion=2]]
system call.
This is especially critical when writing archives to tape drives.
On success, the write callback should return the
number of bytes actually written.
On error, the callback should invoke
'''archive_set_error'''()
to register an error code and message and return -1.
<ul>
<li>
''typedef int''
'''archive_close_callback'''(''struct archive *'', ''void *client_data'')
</li></ul>
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'''.
Note that if the client-provided write callback function
returns a non-zero value, that error will be propagated back to the caller
through whatever API function resulted in that call, which
may include
'''archive_write_header'''(),
'''archive_write_data'''(),
'''archive_write_close'''(),
'''archive_write_finish'''(),
or
'''archive_write_free'''().
The client callback can call
'''archive_set_error'''()
to provide values that can then be retrieved by
'''archive_errno'''()
and
'''archive_error_string'''().
== RETURN VALUES ==
These functions return
'''ARCHIVE_OK'''
on success, or
'''ARCHIVE_FATAL'''.
== ERRORS ==
Detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiverite3]],
[[ManPagerchiveritelocksize3]],
[[ManPagerchiveriteilter3]],
[[ManPagerchiveriteormat3]],
[[ManPagerchiveriteew3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

663
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteSetOptions3.wiki vendored Normal file
View file

@ -0,0 +1,663 @@
ARCHIVE_WRITE_OPTIONS(3) manual page
== NAME ==
'''archive_write_set_filter_option''',
'''archive_write_set_format_option''',
'''archive_write_set_option''',
'''archive_write_set_options'''
- functions controlling options for writing archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
<br>
''int''
<br>
'''archive_write_set_filter_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
<br>
''int''
<br>
'''archive_write_set_format_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
<br>
''int''
<br>
'''archive_write_set_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
<br>
''int''
<br>
'''archive_write_set_options'''(''struct archive *'', ''const char *options'');
== DESCRIPTION ==
These functions provide a way for libarchive clients to configure
specific write modules.
<dl>
<dt>
'''archive_write_set_filter_option'''(),
'''archive_write_set_format_option'''()
</dt> <dd>
Specifies an option that will be passed to the currently-registered
filters (including decompression filters) or format readers.
If
''option''
and
''value''
are both
NULL,
these functions will do nothing and
'''ARCHIVE_OK'''
will be returned.
If
''option''
is
NULL
but
''value''
is not, these functions will do nothing and
'''ARCHIVE_FAILED'''
will be returned.
If
''module''
is not
NULL,
''option''
and
''value''
will be provided to the filter or reader named
''module''.
The return value will be either
'''ARCHIVE_OK'''
if the option was successfully handled or
'''ARCHIVE_WARN'''
if the option was unrecognized by the module or could otherwise
not be handled.
If there is no such module,
'''ARCHIVE_FAILED'''
will be returned.
If
''module''
is
NULL,
''option''
and
''value''
will be provided to every registered module.
If any module returns
'''ARCHIVE_FATAL''',
this value will be returned immediately.
Otherwise,
'''ARCHIVE_OK'''
will be returned if any module accepts the option, and
'''ARCHIVE_FAILED'''
in all other cases.
</dd><dt>'''archive_write_set_option'''()</dt><dd>
Calls
'''archive_write_set_format_option'''(),
then
'''archive_write_set_filter_option'''().
If either function returns
'''ARCHIVE_FATAL''',
'''ARCHIVE_FATAL'''
will be returned
immediately.
Otherwise, the greater of the two values will be returned.
</dd><dt>'''archive_write_set_options'''()</dt><dd>
''options''
is a comma-separated list of options.
If
''options''
is
NULL
or empty,
'''ARCHIVE_OK'''
will be returned immediately.
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>
</dd></dl>
== OPTIONS ==
<dl>
<dt>Filter b64encode</dt><dd>
<dl>
<dt>'''mode'''</dt><dd>
The value is interpreted as octal digits specifying the file mode.
</dd><dt>'''name'''</dt><dd>
The value specifies the file name.
</dd></dl>
</dd><dt>Filter bzip2</dt><dd>
<dl>
<dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
bzip2 compression level. Supported values are from 1 to 9.
</dd></dl>
</dd><dt>Filter gzip</dt><dd>
<dl>
<dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
gzip compression level. Supported values are from 0 to 9.
</dd><dt>'''timestamp'''</dt><dd>
Store timestamp. This is enabled by default.
</dd></dl>
</dd><dt>Filter lrzip</dt><dd>
<dl>
<dt>'''compression'''=''type''</dt><dd>
Use
''type''
as compression method.
Supported values are
"bzip2",
"gzipi",
"lzo"
(ultra fast,)
and
"zpaq"
(best, extremely slow.)
</dd><dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
lrzip compression level. Supported values are from 1 to 9.
</dd></dl>
</dd><dt>Filter lz4</dt><dd>
<dl>
<dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
lz4 compression level. Supported values are from 0 to 9.
</dd><dt>'''stream-checksum'''</dt><dd>
Enable stream checksum. This is enabled by default.
</dd><dt>'''block-checksum'''</dt><dd>
Enable block checksum. This is disabled by default.
</dd><dt>'''block-size'''</dt><dd>
The value is interpreted as a decimal integer specifying the
lz4 compression block size. Supported values are from 4 to 7
(default.)
</dd><dt>'''block-dependence'''</dt><dd>
Use the previous block of the block being compressed for
a compression dictionary to improve compression ratio.
This is disabled by default.
</dd></dl>
</dd><dt>Filter lzop</dt><dd>
<dl>
<dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
lzop compression level. Supported values are from 1 to 9.
</dd></dl>
</dd><dt>Filter uuencode</dt><dd>
<dl>
<dt>'''mode'''</dt><dd>
The value is interpreted as octal digits specifying the file mode.
</dd><dt>'''name'''</dt><dd>
The value specifies the file name.
</dd></dl>
</dd><dt>Filter xz</dt><dd>
<dl>
<dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
compression level. Supported values are from 0 to 9.
</dd><dt>'''threads'''</dt><dd>
The value is interpreted as a decimal integer specifying the
number of threads for multi-threaded lzma compression.
If supported, the default value is read from
'''lzma_cputhreads'''().
</dd></dl>
</dd><dt>Filter zstd</dt><dd>
<dl>
<dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
compression level. Supported values are from 1 to 22.
</dd></dl>
</dd><dt>Format 7zip</dt><dd>
<dl>
<dt>'''compression'''</dt><dd>
The value is one of
"store",
"deflate",
"bzip2",
"lzma1",
"lzma2"
or
"ppmd"
to indicate how the following entries should be compressed.
Note that this setting is ignored for directories, symbolic links,
and other special entries.
</dd><dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
compression level.
Values between 0 and 9 are supported.
The interpretation of the compression level depends on the chosen
compression method.
</dd></dl>
</dd><dt>Format cpio</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd></dl>
</dd><dt>Format gnutar</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file, group and user names.
</dd></dl>
</dd><dt>Format iso9660 - volume metadata</dt><dd>
These options are used to set standard ISO9660 metadata.
<dl>
<dt>'''abstract-file'''=''filename''</dt><dd>
The file with the specified name will be identified in the ISO9660 metadata
as holding the abstract for this volume.
Default: none.
</dd><dt>'''application-id'''=''filename''</dt><dd>
The file with the specified name will be identified in the ISO9660 metadata
as holding the application identifier for this volume.
Default: none.
</dd><dt>'''biblio-file'''=''filename''</dt><dd>
The file with the specified name will be identified in the ISO9660 metadata
as holding the bibliography for this volume.
Default: none.
</dd><dt>'''copyright-file'''=''filename''</dt><dd>
The file with the specified name will be identified in the ISO9660 metadata
as holding the copyright for this volume.
Default: none.
</dd><dt>'''publisher'''=''filename''</dt><dd>
The file with the specified name will be identified in the ISO9660 metadata
as holding the publisher information for this volume.
Default: none.
</dd><dt>'''volume-id'''=''string''</dt><dd>
The specified string will be used as the Volume Identifier in the ISO9660 metadata.
It is limited to 32 bytes.
Default: none.
</dd></dl>
</dd><dt>Format iso9660 - boot support</dt><dd>
These options are used to make an ISO9660 image that can be directly
booted on various systems.
<dl>
<dt>'''boot'''=''filename''</dt><dd>
The file matching this name will be used as the El Torito boot image file.
</dd><dt>'''boot-catalog'''=''name''</dt><dd>
The name that will be used for the El Torito boot catalog.
Default:
''boot.catalog''
</dd><dt>'''boot-info-table'''</dt><dd>
The boot image file provided by the
'''boot'''=''filename''
option will be edited with appropriate boot information in bytes 8 through 64.
Default: disabled
</dd><dt>'''boot-load-seg'''=''hexadecimal-number''</dt><dd>
The load segment for a no-emulation boot image.
</dd><dt>'''boot-load-size'''=''decimal-number''</dt><dd>
The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image.
Some very old BIOSes can only load very small images, setting this
value to 4 will often allow such BIOSes to load the first part of
the boot image (which will then need to be intelligent enough to
load the rest of itself).
This should not be needed unless you are trying to support systems with very old BIOSes.
This defaults to the full size of the image.
</dd><dt>'''boot-type'''=''value''</dt><dd>
Specifies the boot semantics used by the El Torito boot image:
If the
''value''
is
'''fd''',
then the boot image is assumed to be a bootable floppy image.
If the
''value''
is
'''hd''',
then the boot image is assumed to be a bootable hard disk image.
If the
''value''
is
'''no-emulation''',
the boot image is used without floppy or hard disk emulation.
If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then
the default is
'''fd''',
otherwise the default is
'''no-emulation'''.
</dd></dl>
</dd><dt>Format iso9660 - filename and size extensions</dt><dd>
Various extensions to the base ISO9660 format.
<dl>
<dt>'''allow-ldots'''</dt><dd>
If enabled, allows filenames to begin with a leading period.
If disabled, filenames that begin with a leading period will have
that period replaced by an underscore character in the standard ISO9660
namespace.
This does not impact names stored in the Rockridge or Joliet extension area.
Default: disabled.
</dd><dt>'''allow-lowercase'''</dt><dd>
If enabled, allows filenames to contain lowercase characters.
If disabled, filenames will be forced to uppercase.
This does not impact names stored in the Rockridge or Joliet extension area.
Default: disabled.
</dd><dt>'''allow-multidot'''</dt><dd>
If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification.
If disabled, additional periods will be converted to underscore characters.
This does not impact names stored in the Rockridge or Joliet extension area.
Default: disabled.
</dd><dt>'''allow-period'''</dt><dd>
If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification.
If disabled, trailing periods will be converted to underscore characters.
This does not impact names stored in the Rockridge or Joliet extension area.
Default: disabled.
</dd><dt>'''allow-pvd-lowercase'''</dt><dd>
If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification.
If disabled, characters will be converted to uppercase ASCII.
Default: disabled.
</dd><dt>'''allow-sharp-tilde'''</dt><dd>
If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification.
If disabled, such characters will be converted to underscore characters.
Default: disabled.
</dd><dt>'''allow-vernum'''</dt><dd>
If enabled, version numbers will be included with files.
If disabled, version numbers will be suppressed, in violation of the ISO9660 standard.
This does not impact names stored in the Rockridge or Joliet extension area.
Default: enabled.
</dd><dt>'''iso-level'''</dt><dd>
This enables support for file size and file name extensions in the
core ISO9660 area.
The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas.
<dl>
<dt>'''iso-level=1'''</dt><dd>
The most compliant form of ISO9660 image.
Filenames are limited to 8.3 uppercase format,
directory names are limited to 8 uppercase characters,
files are limited to 4 GiB,
the complete ISO9660 image cannot exceed 4 GiB.
</dd><dt>'''iso-level=2'''</dt><dd>
Filenames are limited to 30 uppercase characters with a 30-character extension,
directory names are limited to 30 characters,
files are limited to 4 GiB.
</dd><dt>'''iso-level=3'''</dt><dd>
As with
'''iso-level=2''',
except that files may exceed 4 GiB.
</dd><dt>'''iso-level=4'''</dt><dd>
As with
'''iso-level=3''',
except that filenames may be up to 193 characters
and may include arbitrary 8-bit characters.
</dd></dl>
</dd><dt>'''joliet'''</dt><dd>
Microsoft's Joliet extensions store a completely separate set of directory information about each file.
In particular, this information includes Unicode filenames of up to 255 characters.
Default: enabled.
</dd><dt>'''limit-depth'''</dt><dd>
If enabled, libarchive will use directory relocation records to ensure that
no pathname exceeds the ISO9660 limit of 8 directory levels.
If disabled, no relocation will occur.
Default: enabled.
</dd><dt>'''limit-dirs'''</dt><dd>
If enabled, libarchive will cause an error if there are more than
65536 directories.
If disabled, there is no limit on the number of directories.
Default: enabled
</dd><dt>'''pad'''</dt><dd>
If enabled, 300 kiB of zero bytes will be appended to the end of the archive.
Default: enabled
</dd><dt>'''relaxed-filenames'''</dt><dd>
If enabled, all 7-bit ASCII characters are permitted in filenames
(except lowercase characters unless
'''allow-lowercase'''
is also specified).
This violates ISO9660 standards.
This does not impact names stored in the Rockridge or Joliet extension area.
Default: disabled.
</dd><dt>'''rockridge'''</dt><dd>
The Rockridge extensions store an additional set of POSIX-style file
information with each file, including mtime, atime, ctime, permissions,
and long filenames with arbitrary 8-bit characters.
These extensions also support symbolic links and other POSIX file types.
Default: enabled.
</dd></dl>
</dd><dt>Format iso9660 - zisofs support</dt><dd>
The zisofs extensions permit each file to be independently compressed
using a gzip-compatible compression.
This can provide significant size savings, but requires the reading
system to have support for these extensions.
These extensions are disabled by default.
<dl>
<dt>'''compression-level'''=number</dt><dd>
The compression level used by the deflate compressor.
Ranges from 0 (least effort) to 9 (most effort).
Default: 6
</dd><dt>'''zisofs'''</dt><dd>
Synonym for
'''zisofs=direct'''.
</dd><dt>'''zisofs=direct'''</dt><dd>
Compress each file in the archive.
Unlike
'''zisofs=indirect''',
this is handled entirely within libarchive and does not require a
separate utility.
For best results, libarchive tests each file and will store
the file uncompressed if the compression does not actually save any space.
In particular, files under 2k will never be compressed.
Note that boot image files are never compressed.
</dd><dt>'''zisofs=indirect'''</dt><dd>
Recognizes files that have already been compressed with the
'''mkzftree'''
utility and sets up the necessary file metadata so that
readers will correctly identify these as zisofs-compressed files.
</dd><dt>'''zisofs-exclude'''=''filename''</dt><dd>
Specifies a filename that should not be compressed when using
'''zisofs=direct'''.
This option can be provided multiple times to suppress compression
on many files.
</dd></dl>
</dd><dt>Format mtree</dt><dd>
<dl>
<dt>'''cksum''', '''device''', '''flags''', '''gid''', '''gname''', '''indent''', '''link''', '''md5''', '''mode''', '''nlink''', '''rmd160''', '''sha1''', '''sha256''', '''sha384''', '''sha512''', '''size''', '''time''', '''uid''', '''uname'''</dt><dd>
Enable a particular keyword in the mtree output.
Prefix with an exclamation mark to disable the corresponding keyword.
The default is equivalent to
"device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname".
</dd><dt>'''all'''</dt><dd>
Enables all of the above keywords.
</dd><dt>'''use-set'''</dt><dd>
Enables generation of
'''/set'''
lines that specify default values for the following files and/or directories.
</dd><dt>'''indent'''</dt><dd>
XXX needs explanation XXX
</dd></dl>
</dd><dt>Format newc</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd></dl>
</dd><dt>Format pax</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file, group and user names.
The value is one of
"BINARY"
or
"UTF-8".
With
"BINARY"
there is no character conversion, with
"UTF-8"
names are converted to UTF-8.
</dd><dt>'''xattrheader'''</dt><dd>
When storing extended attributes, this option configures which
headers should be written. The value is one of
"all",
"LIBARCHIVE",
or
"SCHILY".
By default, both
"LIBARCHIVE.xattr"
and
"SCHILY.xattr"
headers are written.
</dd></dl>
</dd><dt>Format ustar</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file, group and user names.
</dd></dl>
</dd><dt>Format v7tar</dt><dd>
<dl>
<dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file, group and user names.
</dd></dl>
</dd><dt>Format warc</dt><dd>
<dl>
<dt>'''omit-warcinfo'''</dt><dd>
Set to
"true"
to disable output of the warcinfo record.
</dd></dl>
</dd><dt>Format xar</dt><dd>
<dl>
<dt>'''checksum'''=''type''</dt><dd>
Use
''type''
as file checksum method.
Supported values are
"none",
"md5",
and
"sha1"
(default.)
</dd><dt>'''compression'''=''type''</dt><dd>
Use
''type''
as compression method.
Supported values are
"none",
"bzip2",
"gzip"
(default,)
"lzma"
and
"xz".
</dd><dt>'''compression_level'''</dt><dd>
The value is a decimal integer from 1 to 9 specifying the compression level.
</dd><dt>'''toc-checksum'''=''type''</dt><dd>
Use
''type''
as table of contents checksum method.
Supported values are
"none",
"md5"
and
"sha1"
(default.)
</dd></dl>
</dd><dt>Format zip</dt><dd>
<dl>
<dt>'''compression'''</dt><dd>
The value is either
"store"
or
"deflate"
to indicate how the following entries should be compressed.
Note that this setting is ignored for directories, symbolic links,
and other special entries.
</dd><dt>'''compression-level'''</dt><dd>
The value is interpreted as a decimal integer specifying the
compression level.
Values between 0 and 9 are supported.
A compression level of 0 switches the compression method to
"store",
other values will enable
"deflate"
compression with the given level.
</dd><dt>'''encryption'''</dt><dd>
Enable encryption using traditional zip encryption.
</dd><dt>'''encryption'''=''type''</dt><dd>
Use
''type''
as encryption type.
Supported values are
"zipcrypt"
(traditional zip encryption,)
"aes128"
(WinZip AES-128 encryption)
and
"aes256"
(WinZip AES-256 encryption.)
</dd><dt>'''experimental'''</dt><dd>
This boolean option enables or disables experimental Zip features
that may not be compatible with other Zip implementations.
</dd><dt>'''fakecrc32'''</dt><dd>
This boolean option disables CRC calculations.
All CRC fields are set to zero.
It should not be used except for testing purposes.
</dd><dt>'''hdrcharset'''</dt><dd>
The value is used as a character set name that will be
used when translating file names.
</dd><dt>'''zip64'''</dt><dd>
Zip64 extensions provide additional file size information
for entries larger than 4 GiB.
They also provide extended file offset and archive size information
when archives exceed 4 GiB.
By default, the Zip writer selectively enables these extensions only as needed.
In particular, if the file size is unknown, the Zip writer will
include Zip64 extensions to guard against the possibility that the
file might be larger than 4 GiB.
Setting this boolean option will force the writer to use Zip64 extensions
even for small files that would not otherwise require them.
This is primarily useful for testing.
Disabling this option with
'''!zip64'''
will force the Zip writer to avoid Zip64 extensions:
It will reject files with size greater than 4 GiB,
it will reject any new entries once the total archive size reaches 4 GiB,
and it will not use Zip64 extensions for files with unknown size.
In particular, this can improve compatibility when generating archives
where the entry sizes are not known in advance.
</dd></dl>
</dd></dl>
== EXAMPLES ==
The following example creates an archive write handle to
create a gzip-compressed ISO9660 format image.
The two options here specify that the ISO9660 archive will use
''kernel.img''
as the boot image for El Torito booting, and that the gzip
compressor should use the maximum compression level.
```text
a = archive_write_new();
archive_write_add_filter_gzip(a);
archive_write_set_format_iso9660(a);
archive_write_set_options(a, "boot=kernel.img,compression=9");
archive_write_open_filename(a, filename, blocksize);
```
== ERRORS ==
More detailed error codes and textual descriptions are available from the
'''archive_errno'''()
and
'''archive_error_string'''()
functions.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchiverite3]],
[[ManPageibarchive3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The options support for libarchive was originally implemented by
Michihiro NAKAJIMA.
== BUGS ==

42
dependencies/libarchive-3.4.2/doc/wiki/ManPageArchiveWriteSetPassphrase3.wiki vendored Normal file
View file

@ -0,0 +1,42 @@
ARCHIVE_WRITE_SET_PASSPHRASE(3) manual page
== NAME ==
'''archive_write_set_passphrase''',
'''archive_write_set_passphrase_callback'''
- functions for writing encrypted archives
== LIBRARY ==
Streaming Archive Library (libarchive, -larchive)
== SYNOPSIS ==
'''<nowiki>#include <archive.h></nowiki>'''
<br>
''int''
<br>
'''archive_write_set_passphrase'''(''struct archive *'', ''const char *passphrase'');
<br>
''int''
<br>
'''archive_write_set_passphrase_callback'''(''struct archive *'', ''void *client_data'', ''archive_passphrase_callback *'');
== DESCRIPTION ==
<dl>
<dt>'''archive_write_set_passphrase'''()</dt><dd>
Set a passphrase for writing an encrypted archive.
If
''passphrase''
is
NULL
or empty, this function will do nothing and
'''ARCHIVE_FAILED'''
will be returned.
Otherwise,
'''ARCHIVE_OK'''
will be returned.
</dd><dt>'''archive_write_set_passphrase_callback'''()</dt><dd>
Register a callback function that will be invoked to get a passphrase
for encryption if the passphrase was not set by the
'''archive_write_set_passphrase'''()
function.
</dd></dl>
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]]

416
dependencies/libarchive-3.4.2/doc/wiki/ManPageBsdcpio1.wiki vendored Normal file
View file

@ -0,0 +1,416 @@
CPIO(1) manual page
== NAME ==
'''cpio'''
- copy files to and from archives
== SYNOPSIS ==
<br>
'''cpio'''
-i
<nowiki>[</nowiki>''options''<nowiki>]</nowiki>
<nowiki>[</nowiki>''pattern'' ...<nowiki>]</nowiki>
<nowiki>[</nowiki>''&lt;'' archive<nowiki>]</nowiki>
<br>
'''cpio'''
-o
<nowiki>[</nowiki>''options''<nowiki>]</nowiki>
''&lt;'' name-list
<nowiki>[</nowiki>''>'' archive<nowiki>]</nowiki>
<br>
'''cpio'''
-p
<nowiki>[</nowiki>''options''<nowiki>]</nowiki>
''dest-dir''
''&lt;'' name-list
== DESCRIPTION ==
'''cpio'''
copies files between archives and directories.
This implementation can extract from tar, pax, cpio, zip, jar, ar,
and ISO 9660 cdrom images and can create tar, pax, cpio, ar,
and shar archives.
The first option to
'''cpio'''
is a mode indicator from the following list:
<dl>
<dt>-i</dt><dd>
Input.
Read an archive from standard input (unless overridden) and extract the
contents to disk or (if the
-t
option is specified)
list the contents to standard output.
If one or more file patterns are specified, only files matching
one of the patterns will be extracted.
</dd><dt>-o</dt><dd>
Output.
Read a list of filenames from standard input and produce a new archive
on standard output (unless overridden) containing the specified items.
</dd><dt>-p</dt><dd>
Pass-through.
Read a list of filenames from standard input and copy the files to the
specified directory.
</dd></dl>
== OPTIONS ==
Unless specifically stated otherwise, options are applicable in
all operating modes.
<dl>
<dt>-0, --null</dt><dd>
Read filenames separated by NUL characters instead of newlines.
This is necessary if any of the filenames being read might contain newlines.
</dd><dt>-A</dt><dd>
(o mode only)
Append to the specified archive.
(Not yet implemented.)
</dd><dt>-a</dt><dd>
(o and p modes)
Reset access times on files after they are read.
</dd><dt>-B</dt><dd>
(o mode only)
Block output to records of 5120 bytes.
</dd><dt>-C ''size''</dt><dd>
(o mode only)
Block output to records of
''size''
bytes.
</dd><dt>-c</dt><dd>
(o mode only)
Use the old POSIX portable character format.
Equivalent to
--format ''odc''.
</dd><dt>-d, --make-directories</dt><dd>
(i and p modes)
Create directories as necessary.
</dd><dt>-E ''file''</dt><dd>
(i mode only)
Read list of file name patterns from
''file''
to list and extract.
</dd><dt>-F ''file'', --file ''file''</dt><dd>
Read archive from or write archive to
''file''.
</dd><dt>-f ''pattern''</dt><dd>
(i mode only)
Ignore files that match
''pattern''.
</dd><dt>-H ''format'', --format ''format''</dt><dd>
(o mode only)
Produce the output archive in the specified format.
Supported formats include:
<dl>
<dt>''cpio''</dt><dd>
Synonym for
''odc''.
</dd><dt>''newc''</dt><dd>
The SVR4 portable cpio format.
</dd><dt>''odc''</dt><dd>
The old POSIX.1 portable octet-oriented cpio format.
</dd><dt>''pax''</dt><dd>
The POSIX.1 pax format, an extension of the ustar format.
</dd><dt>''ustar''</dt><dd>
The POSIX.1 tar format.
</dd></dl>
The default format is
''odc''.
See
[[ManPageibarchiveormats5]]
for more complete information about the
formats currently supported by the underlying
[[ManPageibarchive3]]
library.
</dd><dt>-h, --help</dt><dd>
Print usage information.
</dd><dt>-I ''file''</dt><dd>
Read archive from
''file''.
</dd><dt>-i, --extract</dt><dd>
Input mode.
See above for description.
</dd><dt>--insecure</dt><dd>
(i and p mode only)
Disable security checks during extraction or copying.
This allows extraction via symbolic links, absolute paths,
and path names containing
Sq ..
in the name.
</dd><dt>-J, --xz</dt><dd>
(o mode only)
Compress the file with xz-compatible compression before writing it.
In input mode, this option is ignored; xz compression is recognized
automatically on input.
</dd><dt>-j</dt><dd>
Synonym for
-y.
</dd><dt>-L</dt><dd>
(o and p modes)
All symbolic links will be followed.
Normally, symbolic links are archived and copied as symbolic links.
With this option, the target of the link will be archived or copied instead.
</dd><dt>-l, --link</dt><dd>
(p mode only)
Create links from the target directory to the original files,
instead of copying.
</dd><dt>--lrzip</dt><dd>
(o mode only)
Compress the resulting archive with
[[lrzip(1)|http://www.freebsd.org/cgi/man.cgi?query=lrzip&sektion=1]].
In input mode, this option is ignored.
</dd><dt>--lz4</dt><dd>
(o mode only)
Compress the archive with lz4-compatible compression before writing it.
In input mode, this option is ignored; lz4 compression is recognized
automatically on input.
</dd><dt>--zstd</dt><dd>
(o mode only)
Compress the archive with zstd-compatible compression before writing it.
In input mode, this option is ignored; zstd compression is recognized
automatically on input.
</dd><dt>--lzma</dt><dd>
(o mode only)
Compress the file with lzma-compatible compression before writing it.
In input mode, this option is ignored; lzma compression is recognized
automatically on input.
</dd><dt>--lzop</dt><dd>
(o mode only)
Compress the resulting archive with
[[lzop(1)|http://www.freebsd.org/cgi/man.cgi?query=lzop&sektion=1]].
In input mode, this option is ignored.
</dd><dt>--passphrase ''passphrase''</dt><dd>
The
''passphrase''
is used to extract or create an encrypted archive.
Currently, zip is only a format that
'''cpio'''
can handle encrypted archives.
You shouldn't use this option unless you realize how insecure
use of this option is.
</dd><dt>-m, --preserve-modification-time</dt><dd>
(i and p modes)
Set file modification time on created files to match
those in the source.
</dd><dt>-n, --numeric-uid-gid</dt><dd>
(i mode, only with
-t)
Display numeric uid and gid.
By default,
'''cpio'''
displays the user and group names when they are provided in the
archive, or looks up the user and group names in the system
password database.
</dd><dt>--no-preserve-owner</dt><dd>
(i mode only)
Do not attempt to restore file ownership.
This is the default when run by non-root users.
</dd><dt>-O ''file''</dt><dd>
Write archive to
''file''.
</dd><dt>-o, --create</dt><dd>
Output mode.
See above for description.
</dd><dt>-p, --pass-through</dt><dd>
Pass-through mode.
See above for description.
</dd><dt>--preserve-owner</dt><dd>
(i mode only)
Restore file ownership.
This is the default when run by the root user.
</dd><dt>--quiet</dt><dd>
Suppress unnecessary messages.
</dd><dt>-R <nowiki>[</nowiki>user<nowiki>]</nowiki><nowiki>[</nowiki>:<nowiki>]</nowiki><nowiki>[</nowiki>group<nowiki>]</nowiki>, --owner <nowiki>[</nowiki>user<nowiki>]</nowiki><nowiki>[</nowiki>:<nowiki>]</nowiki><nowiki>[</nowiki>group<nowiki>]</nowiki></dt><dd>
Set the owner and/or group on files in the output.
If group is specified with no user
(for example,
-R '':wheel'')
then the group will be set but not the user.
If the user is specified with a trailing colon and no group
(for example,
-R ''root:'')
then the group will be set to the user's default group.
If the user is specified with no trailing colon, then
the user will be set but not the group.
In
-i
and
-p
modes, this option can only be used by the super-user.
(For compatibility, a period can be used in place of the colon.)
</dd><dt>-r</dt><dd>
(All modes.)
Rename files interactively.
For each file, a prompt is written to
''/dev/tty''
containing the name of the file and a line is read from
''/dev/tty''.
If the line read is blank, the file is skipped.
If the line contains a single period, the file is processed normally.
Otherwise, the line is taken to be the new name of the file.
</dd><dt>-t, --list</dt><dd>
(i mode only)
List the contents of the archive to stdout;
do not restore the contents to disk.
</dd><dt>-u, --unconditional</dt><dd>
(i and p modes)
Unconditionally overwrite existing files.
Ordinarily, an older file will not overwrite a newer file on disk.
</dd><dt>-V, --dot</dt><dd>
Print a dot to stderr for each file as it is processed.
Superseded by
-v.
</dd><dt>-v, --verbose</dt><dd>
Print the name of each file to stderr as it is processed.
With
-t,
provide a detailed listing of each file.
</dd><dt>--version</dt><dd>
Print the program version information and exit.
</dd><dt>-y</dt><dd>
(o mode only)
Compress the archive with bzip2-compatible compression before writing it.
In input mode, this option is ignored;
bzip2 compression is recognized automatically on input.
</dd><dt>-Z</dt><dd>
(o mode only)
Compress the archive with compress-compatible compression before writing it.
In input mode, this option is ignored;
compression is recognized automatically on input.
</dd><dt>-z</dt><dd>
(o mode only)
Compress the archive with gzip-compatible compression before writing it.
In input mode, this option is ignored;
gzip compression is recognized automatically on input.
</dd></dl>
== EXIT STATUS ==
The '''cpio''' utility exits 0 on success, and &gt;0 if an error occurs.
== ENVIRONMENT ==
The following environment variables affect the execution of
'''cpio''':
<dl>
<dt>'''LANG'''</dt><dd>
The locale to use.
See
[[environ(7)|http://www.freebsd.org/cgi/man.cgi?query=environ&sektion=7]]
for more information.
</dd><dt>'''TZ'''</dt><dd>
The timezone to use when displaying dates.
See
[[environ(7)|http://www.freebsd.org/cgi/man.cgi?query=environ&sektion=7]]
for more information.
</dd></dl>
== EXAMPLES ==
The
'''cpio'''
command is traditionally used to copy file hierarchies in conjunction
with the
[[find(1)|http://www.freebsd.org/cgi/man.cgi?query=find&sektion=1]]
command.
The first example here simply copies all files from
''src''
to
''dest'':
```text
find src | cpio -pmud dest
```
By carefully selecting options to the
[[find(1)|http://www.freebsd.org/cgi/man.cgi?query=find&sektion=1]]
command and combining it with other standard utilities,
it is possible to exercise very fine control over which files are copied.
This next example copies files from
''src''
to
''dest''
that are more than 2 days old and whose names match a particular pattern:
```text
find src -mtime +2 | grep foo[bar] | cpio -pdmu dest
```
This example copies files from
''src''
to
''dest''
that are more than 2 days old and which contain the word
"foobar":
```text
find src -mtime +2 | xargs grep -l foobar | cpio -pdmu dest
```
== COMPATIBILITY ==
The mode options i, o, and p and the options
a, B, c, d, f, l, m, r, t, u, and v comply with SUSv2.
The old POSIX.1 standard specified that only
-i,
-o,
and
-p
were interpreted as command-line options.
Each took a single argument of a list of modifier
characters.
For example, the standard syntax allows
-imu
but does not support
-miu
or
-i -m -u,
since
''m''
and
''u''
are only modifiers to
-i,
they are not command-line options in their own right.
The syntax supported by this implementation is backwards-compatible
with the standard.
For best compatibility, scripts should limit themselves to the
standard syntax.
== SEE ALSO ==
[[bzip2(1)|http://www.freebsd.org/cgi/man.cgi?query=bzip2&sektion=1]],
[[gzip(1)|http://www.freebsd.org/cgi/man.cgi?query=gzip&sektion=1]],
[[mt(1)|http://www.freebsd.org/cgi/man.cgi?query=mt&sektion=1]],
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]],
[[ManPageBsdtar1]],
[[ManPageibarchive3]],
[[ManPageCpio5]],
[[ManPageibarchiveormats5]],
[[ManPageTar5]]
== STANDARDS ==
There is no current POSIX standard for the cpio command; it appeared
in
<nowiki>ISO/IEC 9945-1:1996 (``POSIX.1'')</nowiki>
but was dropped from
<nowiki>IEEE Std 1003.1-2001 (``POSIX.1'')</nowiki>.
The cpio, ustar, and pax interchange file formats are defined by
<nowiki>IEEE Std 1003.1-2001 (``POSIX.1'')</nowiki>
for the pax command.
== HISTORY ==
The original
'''cpio'''
and
'''find'''
utilities were written by Dick Haight
while working in AT&T's Unix Support Group.
They first appeared in 1977 in PWB/UNIX 1.0, the
"Programmer's Work Bench"
system developed for use within AT&T.
They were first released outside of AT&T as part of System III Unix in 1981.
As a result,
'''cpio'''
actually predates
'''tar''',
even though it was not well-known outside of AT&T until some time later.
This is a complete re-implementation based on the
[[ManPageibarchive3]]
library.
== BUGS ==
The cpio archive format has several basic limitations:
It does not store user and group names, only numbers.
As a result, it cannot be reliably used to transfer
files between systems with dissimilar user and group numbering.
Older cpio formats limit the user and group numbers to
16 or 18 bits, which is insufficient for modern systems.
The cpio archive formats cannot support files over 4 gigabytes,
except for the
"odc"
variant, which can support files up to 8 gigabytes.

1339
dependencies/libarchive-3.4.2/doc/wiki/ManPageBsdtar1.wiki vendored Normal file
View file

File diff suppressed because it is too large Load diff

297
dependencies/libarchive-3.4.2/doc/wiki/ManPageCpio5.wiki vendored Normal file
View file

@ -0,0 +1,297 @@
CPIO(5) manual page
== NAME ==
'''cpio'''
- format of cpio archive files
== DESCRIPTION ==
The
'''cpio'''
archive format collects any number of files, directories, and other
file system objects (symbolic links, device nodes, etc.) into a single
stream of bytes.
=== General Format===
Each file system object in a
'''cpio'''
archive comprises a header record with basic numeric metadata
followed by the full pathname of the entry and the file data.
The header record stores a series of integer values that generally
follow the fields in
''struct'' stat.
(See
[[stat(2)|http://www.freebsd.org/cgi/man.cgi?query=stat&sektion=2]]
for details.)
The variants differ primarily in how they store those integers
(binary, octal, or hexadecimal).
The header is followed by the pathname of the
entry (the length of the pathname is stored in the header)
and any file data.
The end of the archive is indicated by a special record with
the pathname
"TRAILER!!!".
=== PWB format===
XXX Any documentation of the original PWB/UNIX 1.0 format? XXX
=== Old Binary Format===
The old binary
'''cpio'''
format stores numbers as 2-byte and 4-byte binary values.
Each entry begins with a header in the following format:
```text
struct header_old_cpio {
unsigned short c_magic;
unsigned short c_dev;
unsigned short c_ino;
unsigned short c_mode;
unsigned short c_uid;
unsigned short c_gid;
unsigned short c_nlink;
unsigned short c_rdev;
unsigned short c_mtime[2];
unsigned short c_namesize;
unsigned short c_filesize[2];
};
```
The
''unsigned'' short
fields here are 16-bit integer values; the
''unsigned'' int
fields are 32-bit integer values.
The fields are as follows
<dl>
<dt>''magic''</dt><dd>
The integer value octal 070707.
This value can be used to determine whether this archive is
written with little-endian or big-endian integers.
</dd><dt>''dev'', ''ino''</dt><dd>
The device and inode numbers from the disk.
These are used by programs that read
'''cpio'''
archives to determine when two entries refer to the same file.
Programs that synthesize
'''cpio'''
archives should be careful to set these to distinct values for each entry.
</dd><dt>''mode''</dt><dd>
The mode specifies both the regular permissions and the file type.
It consists of several bit fields as follows:
<dl>
<dt>0170000</dt><dd>
This masks the file type bits.
</dd><dt>0140000</dt><dd>
File type value for sockets.
</dd><dt>0120000</dt><dd>
File type value for symbolic links.
For symbolic links, the link body is stored as file data.
</dd><dt>0100000</dt><dd>
File type value for regular files.
</dd><dt>0060000</dt><dd>
File type value for block special devices.
</dd><dt>0040000</dt><dd>
File type value for directories.
</dd><dt>0020000</dt><dd>
File type value for character special devices.
</dd><dt>0010000</dt><dd>
File type value for named pipes or FIFOs.
</dd><dt>0004000</dt><dd>
SUID bit.
</dd><dt>0002000</dt><dd>
SGID bit.
</dd><dt>0001000</dt><dd>
Sticky bit.
On some systems, this modifies the behavior of executables and/or directories.
</dd><dt>0000777</dt><dd>
The lower 9 bits specify read/write/execute permissions
for world, group, and user following standard POSIX conventions.
</dd></dl>
</dd><dt>''uid'', ''gid''</dt><dd>
The numeric user id and group id of the owner.
</dd><dt>''nlink''</dt><dd>
The number of links to this file.
Directories always have a value of at least two here.
Note that hardlinked files include file data with every copy in the archive.
</dd><dt>''rdev''</dt><dd>
For block special and character special entries,
this field contains the associated device number.
For all other entry types, it should be set to zero by writers
and ignored by readers.
</dd><dt>''mtime''</dt><dd>
Modification time of the file, indicated as the number
of seconds since the start of the epoch,
00:00:00 UTC January 1, 1970.
The four-byte integer is stored with the most-significant 16 bits first
followed by the least-significant 16 bits.
Each of the two 16 bit values are stored in machine-native byte order.
</dd><dt>''namesize''</dt><dd>
The number of bytes in the pathname that follows the header.
This count includes the trailing NUL byte.
</dd><dt>''filesize''</dt><dd>
The size of the file.
Note that this archive format is limited to
four gigabyte file sizes.
See
''mtime''
above for a description of the storage of four-byte integers.
</dd></dl>
The pathname immediately follows the fixed header.
If the
'''namesize'''
is odd, an additional NUL byte is added after the pathname.
The file data is then appended, padded with NUL
bytes to an even length.
Hardlinked files are not given special treatment;
the full file contents are included with each copy of the
file.
=== Portable ASCII Format===
<nowiki>Version 2 of the Single UNIX Specification (``SUSv2'')</nowiki>
standardized an ASCII variant that is portable across all
platforms.
It is commonly known as the
"old character"
format or as the
"odc"
format.
It stores the same numeric fields as the old binary format, but
represents them as 6-character or 11-character octal values.
```text
struct cpio_odc_header {
char c_magic[6];
char c_dev[6];
char c_ino[6];
char c_mode[6];
char c_uid[6];
char c_gid[6];
char c_nlink[6];
char c_rdev[6];
char c_mtime[11];
char c_namesize[6];
char c_filesize[11];
};
```
The fields are identical to those in the old binary format.
The name and file body follow the fixed header.
Unlike the old binary format, there is no additional padding
after the pathname or file contents.
If the files being archived are themselves entirely ASCII, then
the resulting archive will be entirely ASCII, except for the
NUL byte that terminates the name field.
=== New ASCII Format===
The "new" ASCII format uses 8-byte hexadecimal fields for
all numbers and separates device numbers into separate fields
for major and minor numbers.
```text
struct cpio_newc_header {
char c_magic[6];
char c_ino[8];
char c_mode[8];
char c_uid[8];
char c_gid[8];
char c_nlink[8];
char c_mtime[8];
char c_filesize[8];
char c_devmajor[8];
char c_devminor[8];
char c_rdevmajor[8];
char c_rdevminor[8];
char c_namesize[8];
char c_check[8];
};
```
Except as specified below, the fields here match those specified
for the old binary format above.
<dl>
<dt>''magic''</dt><dd>
The string
"070701".
</dd><dt>''check''</dt><dd>
This field is always set to zero by writers and ignored by readers.
See the next section for more details.
</dd></dl>
The pathname is followed by NUL bytes so that the total size
of the fixed header plus pathname is a multiple of four.
Likewise, the file data is padded to a multiple of four bytes.
Note that this format supports only 4 gigabyte files (unlike the
older ASCII format, which supports 8 gigabyte files).
In this format, hardlinked files are handled by setting the
filesize to zero for each entry except the last one that
appears in the archive.
=== New CRC Format===
The CRC format is identical to the new ASCII format described
in the previous section except that the magic field is set
to
"070702"
and the
''check''
field is set to the sum of all bytes in the file data.
This sum is computed treating all bytes as unsigned values
and using unsigned arithmetic.
Only the least-significant 32 bits of the sum are stored.
=== HP variants===
The
'''cpio'''
implementation distributed with HPUX used XXXX but stored
device numbers differently XXX.
=== Other Extensions and Variants===
Sun Solaris uses additional file types to store extended file
data, including ACLs and extended attributes, as special
entries in cpio archives.
XXX Others? XXX
== SEE ALSO ==
[[ManPageBsdcpio1]],
[[ManPageTar5]]
== STANDARDS ==
The
'''cpio'''
utility is no longer a part of POSIX or the Single Unix Standard.
It last appeared in
<nowiki>Version 2 of the Single UNIX Specification (``SUSv2'')</nowiki>.
It has been supplanted in subsequent standards by
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]].
The portable ASCII format is currently part of the specification for the
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]]
utility.
== HISTORY ==
The original cpio utility was written by Dick Haight
while working in AT&T's Unix Support Group.
It appeared in 1977 as part of PWB/UNIX 1.0, the
"Programmer's Work Bench"
derived from
At v6
that was used internally at AT&T.
Both the old binary and old character formats were in use
by 1980, according to the System III source released
by SCO under their
"Ancient Unix"
license.
The character format was adopted as part of
<nowiki>IEEE Std 1003.1-1988 (``POSIX.1'')</nowiki>.
XXX when did "newc" appear? Who invented it? When did HP come out with their variant? When did Sun introduce ACLs and extended attributes? XXX
== BUGS ==
The
"CRC"
format is mis-named, as it uses a simple checksum and
not a cyclic redundancy check.
The old binary format is limited to 16 bits for user id,
group id, device, and inode numbers.
It is limited to 4 gigabyte file sizes.
The old ASCII format is limited to 18 bits for
the user id, group id, device, and inode numbers.
It is limited to 8 gigabyte file sizes.
The new ASCII format is limited to 4 gigabyte file sizes.
None of the cpio formats store user or group names,
which are essential when moving files between systems with
dissimilar user or group numbering.
Especially when writing older cpio variants, it may be necessary
to map actual device/inode values to synthesized values that
fit the available fields.
With very large filesystems, this may be necessary even for
the newer formats.

257
dependencies/libarchive-3.4.2/doc/wiki/ManPageLibarchive3.wiki vendored Normal file
View file

@ -0,0 +1,257 @@
LIBARCHIVE(3) manual page
== NAME ==
'''libarchive'''
- functions for reading and writing streaming archives
== OVERVIEW ==
The
'''libarchive'''
library provides a flexible interface for reading and writing
archives in various formats such as tar and cpio.
'''libarchive'''
also supports reading and writing archives compressed using
various compression filters such as gzip and bzip2.
The library is inherently stream-oriented; readers serially iterate through
the archive, writers serially add things to the archive.
In particular, note that there is currently no built-in support for
random access nor for in-place modification.
When reading an archive, the library automatically detects the
format and the compression.
The library currently has read support for:
<ul>
<li>
old-style tar archives,
</li><li>
most variants of the POSIX
"ustar"
format,
</li><li>
the POSIX
"pax interchange"
format,
</li><li>
GNU-format tar archives,
</li><li>
most common cpio archive formats,
</li><li>
ISO9660 CD images (including RockRidge and Joliet extensions),
</li><li>
Zip archives,
</li><li>
ar archives (including GNU/SysV and BSD extensions),
</li><li>
Microsoft CAB archives,
</li><li>
LHA archives,
</li><li>
mtree file tree descriptions,
</li><li>
RAR archives,
</li><li>
XAR archives.
</li></ul>
The library automatically detects archives compressed with
[[gzip(1)|http://www.freebsd.org/cgi/man.cgi?query=gzip&sektion=1]],
[[bzip2(1)|http://www.freebsd.org/cgi/man.cgi?query=bzip2&sektion=1]],
[[xz(1)|http://www.freebsd.org/cgi/man.cgi?query=xz&sektion=1]],
[[lzip(1)|http://www.freebsd.org/cgi/man.cgi?query=lzip&sektion=1]],
or
[[compress(1)|http://www.freebsd.org/cgi/man.cgi?query=compress&sektion=1]]
and decompresses them transparently.
It can similarly detect and decode archives processed with
[[uuencode(1)|http://www.freebsd.org/cgi/man.cgi?query=uuencode&sektion=1]]
or which have an
[[rpm(1)|http://www.freebsd.org/cgi/man.cgi?query=rpm&sektion=1]]
header.
When writing an archive, you can specify the compression
to be used and the format to use.
The library can write
<ul>
<li>
POSIX-standard
"ustar"
archives,
</li><li>
POSIX
"pax interchange format"
archives,
</li><li>
POSIX octet-oriented cpio archives,
</li><li>
Zip archive,
</li><li>
two different variants of shar archives,
</li><li>
ISO9660 CD images,
</li><li>
7-Zip archives,
</li><li>
ar archives,
</li><li>
mtree file tree descriptions,
</li><li>
XAR archives.
</li></ul>
Pax interchange format is an extension of the tar archive format that
eliminates essentially all of the limitations of historic tar formats
in a standard fashion that is supported
by POSIX-compliant
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]]
implementations on many systems as well as several newer implementations of
[[ManPageBsdtar1]].
Note that the default write format will suppress the pax extended
attributes for most entries; explicitly requesting pax format will
enable those attributes for all entries.
The read and write APIs are accessed through the
'''archive_read_XXX'''()
functions and the
'''archive_write_XXX'''()
functions, respectively, and either can be used independently
of the other.
The rest of this manual page provides an overview of the library
operation.
More detailed information can be found in the individual manual
pages for each API or utility function.
== READING AN ARCHIVE ==
See
[[ManPagerchiveead3]].
== WRITING AN ARCHIVE ==
See
[[ManPagerchiverite3]].
== WRITING ENTRIES TO DISK ==
The
[[ManPagerchiveriteisk3]]
API allows you to write
[[ManPagerchiventry3]]
objects to disk using the same API used by
[[ManPagerchiverite3]].
The
[[ManPagerchiveriteisk3]]
API is used internally by
'''archive_read_extract'''('';'')
using it directly can provide greater control over how entries
get written to disk.
This API also makes it possible to share code between
archive-to-archive copy and archive-to-disk extraction
operations.
== READING ENTRIES FROM DISK ==
The
[[ManPagerchiveeadisk3]]
supports for populating
[[ManPagerchiventry3]]
objects from information in the filesystem.
This includes the information accessible from the
[[stat(2)|http://www.freebsd.org/cgi/man.cgi?query=stat&sektion=2]]
system call as well as ACLs, extended attributes,
and other metadata.
The
[[ManPagerchiveeadisk3]]
API also supports iterating over directory trees,
which allows directories of files to be read using
an API compatible with
the
[[ManPagerchiveead3]]
API.
== DESCRIPTION ==
Detailed descriptions of each function are provided by the
corresponding manual pages.
All of the functions utilize an opaque
'''struct archive'''
datatype that provides access to the archive contents.
The
'''struct archive_entry'''
structure contains a complete description of a single archive
entry.
It uses an opaque interface that is fully documented in
[[ManPagerchiventry3]].
Users familiar with historic formats should be aware that the newer
variants have eliminated most restrictions on the length of textual fields.
Clients should not assume that filenames, link names, user names, or
group names are limited in length.
In particular, pax interchange format can easily accommodate pathnames
in arbitrary character sets that exceed
''PATH_MAX''.
== RETURN VALUES ==
Most functions return
'''ARCHIVE_OK'''
(zero) on success, non-zero on error.
The return value indicates the general severity of the error, ranging
from
'''ARCHIVE_WARN''',
which indicates a minor problem that should probably be reported
to the user, to
'''ARCHIVE_FATAL''',
which indicates a serious problem that will prevent any further
operations on this archive.
On error, the
'''archive_errno'''()
function can be used to retrieve a numeric error code (see
[[errno(2)|http://www.freebsd.org/cgi/man.cgi?query=errno&sektion=2]]).
The
'''archive_error_string'''()
returns a textual error message suitable for display.
'''archive_read_new'''()
and
'''archive_write_new'''()
return pointers to an allocated and initialized
'''struct archive'''
object.
'''archive_read_data'''()
and
'''archive_write_data'''()
return a count of the number of bytes actually read or written.
A value of zero indicates the end of the data for this entry.
A negative value indicates an error, in which case the
'''archive_errno'''()
and
'''archive_error_string'''()
functions can be used to obtain more information.
== ENVIRONMENT ==
There are character set conversions within the
[[ManPagerchiventry3]]
functions that are impacted by the currently-selected locale.
== SEE ALSO ==
[[ManPageBsdtar1]],
[[ManPagerchiventry3]],
[[ManPagerchiveead3]],
[[ManPagerchivetil3]],
[[ManPagerchiverite3]],
[[ManPageTar5]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The
'''libarchive'''
library was originally written by
Tim Kientzle &lt;kientzle@acm.org.&gt;
== BUGS ==
Some archive formats support information that is not supported by
'''struct archive_entry .'''
Such information cannot be fully archived or restored using this library.
This includes, for example, comments, character sets,
or the arbitrary key/value pairs that can appear in
pax interchange format archives.
Conversely, of course, not all of the information that can be
stored in an
'''struct archive_entry'''
is supported by all formats.
For example, cpio formats do not support nanosecond timestamps;
old tar formats do not support large device numbers.
The ISO9660 reader cannot yet read all ISO9660 images;
it should learn how to seek.
The AR writer requires the client program to use
two passes, unlike all other libarchive writers.

303
dependencies/libarchive-3.4.2/doc/wiki/ManPageLibarchiveChanges3.wiki vendored Normal file
View file

@ -0,0 +1,303 @@
LIBARCHIVE_CHANGES(3) manual page
== NAME ==
'''libarchive_changes'''
- changes in libarchive interface
== CHANGES IN LIBARCHIVE 3 ==
This page describes user-visible changes in libarchive3, and lists
public functions and other symbols changed, deprecated or removed
in libarchive3, along with their replacements if any.
=== Multiple Filters===
Libarchive2 permitted a single (input or output) filter active
on an archive.
Libarchive3 extends this into a variable-length stack.
Where
'''archive_write_set_compression_XXX'''()
would replace any existing filter,
'''archive_write_add_filter_XXX'''()
extends the write pipeline with another filter.
=== Character Set Handling===
Libarchive2 assumed that the local platform uses
'''Unicode'''
as the native
'''wchar_t'''
encoding, which is true on
'''Windows ,'''
modern
'''Linux ,'''
and a few other systems, but is certainly not universal.
As a result, pax format archives were written incorrectly on some
systems, since pax format requires
'''UTF-8'''
and libarchive 2 incorrectly
assumed that
'''wchar_t'''
strings can be easily converted to
'''UTF-8 .'''
Libarchive3 uses the standard iconv library to convert between character
sets and is introducing the notion of a
"default character set for the archive".
To support this,
'''archive_entry'''
objects can now be bound to a particular archive when they are created.
The automatic character set conversions performed by
'''archive_entry'''
objects when reading and writing filenames, usernames, and other strings
will now use an appropriate default character set:
If the
'''archive_entry'''
object is bound to an archive, it will use the
default character set for that archive.
The platform default character encoding (as returned by
'''nl_langinfo'''(''CHARSET'', '')'')
will be used if nothing else is specified.
Libarchive3 also introduces charset options to many of the archive
readers and writers to control the character set that will be used for
filenames written in those archives.
When possible, this will be set automatically based on information in
the archive itself.
Combining this with the notion of a default character set for the
archive should allow you to configure libarchive to read archives from
other platforms and have the filenames and other information
transparently converted to the character encoding suitable for your
application.
=== Prototype Changes===
These changes break binary compatibility; libarchive3 has a new shared
library version to reflect these changes.
The library now uses portable wide types such as
'''int64_t'''
instead of less-portable types such as
'''off_t ,'''
'''gid_t ,'''
'''uid_t ,'''
and
'''ino_t .'''
There are a few cases where these changes will affect your source code:
<ul>
<li>
In some cases, libarchive's wider types will introduce the possibility
of truncation: for example, on a system with a 16-bit
'''uid_t , you risk having uid'''
```text
65536
```
be truncated to uid
```text
0,
```
which can cause serious security problems.
</li><li>
Typedef function pointer types will be incompatible.
For example, if you define custom skip callbacks, you may have to use
code similar to the following if you want to support building against
libarchive2 and libarchive3:
```text
#if ARCHIVE_VERSION_NUMBER < 3000000
typedef off_t myoff_t;
#else
typedef int64_t myoff_t;
#endif
myoff_t
my_skip_function(struct archive *a, void *v, myoff_t o)
{
... implementation ...
}
```
</li></ul>
Affected functions:
<ul>
<li>
'''archive_entry_gid'''(),
'''archive_entry_set_gid'''()
</li><li>
'''archive_entry_uid'''(),
'''archive_entry_set_uid'''()
</li><li>
'''archive_entry_ino'''(),
'''archive_entry_set_ino'''()
</li><li>
'''archive_read_data_block'''(),
'''archive_write_data_block'''()
</li><li>
'''archive_read_disk_gname'''(),
'''archive_read_disk_uname'''()
</li><li>
'''archive_read_disk_set_gname_lookup'''(),
'''archive_read_disk_set_group_lookup'''(),
'''archive_read_disk_set_uname_lookup'''(),
'''archive_read_disk_set_user_lookup'''()
</li><li>
'''archive_skip_callback'''()
</li><li>
'''archive_read_extract_set_skip_file'''(),
'''archive_write_disk_set_skip_file'''(),
'''archive_write_set_skip_file'''()
</li><li>
'''archive_write_disk_set_group_lookup'''(),
'''archive_write_disk_set_user_lookup'''()
</li></ul>
Where these functions or their arguments took or returned
'''gid_t ,'''
'''ino_t ,'''
'''off_t ,'''
or
'''uid_t'''
they now take or return
'''int64_t'''
or equivalent.
=== Deprecated Symbols===
Symbols deprecated in libarchive3 will be removed in libarchive4.
These symbols, along with their replacements if any, are listed below:
<dl>
<dt>'''archive_position_compressed'''(), '''archive_position_uncompressed'''()</dt><dd>
'''archive_filter_bytes'''()
</dd><dt>'''archive_compression'''()</dt><dd>
'''archive_filter_code'''()
</dd><dt>'''archive_compression_name'''()</dt><dd>
'''archive_filter_name'''()
</dd><dt>'''archive_read_finish'''(), '''archive_write_finish'''()</dt><dd>
'''archive_read_free'''(),
'''archive_write_free'''()
</dd><dt>'''archive_read_open_file'''(), '''archive_write_open_file'''()</dt><dd>
'''archive_read_open_filename'''(),
'''archive_write_open_filename'''()
</dd><dt>'''archive_read_support_compression_all'''()</dt><dd>
'''archive_read_support_filter_all'''()
</dd><dt>'''archive_read_support_compression_bzip2'''()</dt><dd>
'''archive_read_support_filter_bzip2'''()
</dd><dt>'''archive_read_support_compression_compress'''()</dt><dd>
'''archive_read_support_filter_compress'''()
</dd><dt>'''archive_read_support_compression_gzip'''()</dt><dd>
'''archive_read_support_filter_gzip'''()
</dd><dt>'''archive_read_support_compression_lzip'''()</dt><dd>
'''archive_read_support_filter_lzip'''()
</dd><dt>'''archive_read_support_compression_lzma'''()</dt><dd>
'''archive_read_support_filter_lzma'''()
</dd><dt>'''archive_read_support_compression_none'''()</dt><dd>
'''archive_read_support_filter_none'''()
</dd><dt>'''archive_read_support_compression_program'''()</dt><dd>
'''archive_read_support_filter_program'''()
</dd><dt>'''archive_read_support_compression_program_signature'''()</dt><dd>
'''archive_read_support_filter_program_signature'''()
</dd><dt>'''archive_read_support_compression_rpm'''()</dt><dd>
'''archive_read_support_filter_rpm'''()
</dd><dt>'''archive_read_support_compression_uu'''()</dt><dd>
'''archive_read_support_filter_uu'''()
</dd><dt>'''archive_read_support_compression_xz'''()</dt><dd>
'''archive_read_support_filter_xz'''()
</dd><dt>'''archive_write_set_compression_bzip2'''()</dt><dd>
'''archive_write_add_filter_bzip2'''()
</dd><dt>'''archive_write_set_compression_compress'''()</dt><dd>
'''archive_write_add_filter_compress'''()
</dd><dt>'''archive_write_set_compression_gzip'''()</dt><dd>
'''archive_write_add_filter_gzip'''()
</dd><dt>'''archive_write_set_compression_lzip'''()</dt><dd>
'''archive_write_add_filter_lzip'''()
</dd><dt>'''archive_write_set_compression_lzma'''()</dt><dd>
'''archive_write_add_filter_lzma'''()
</dd><dt>'''archive_write_set_compression_none'''()</dt><dd>
'''archive_write_add_filter_none'''()
</dd><dt>'''archive_write_set_compression_program'''()</dt><dd>
'''archive_write_add_filter_program'''()
</dd><dt>'''archive_write_set_compression_filter'''()</dt><dd>
'''archive_write_add_filter_filter'''()
</dd></dl>
=== Removed Symbols===
These symbols, listed below along with their replacements if any,
were deprecated in libarchive2, and are not part of libarchive3.
<dl>
<dt>'''archive_api_feature'''()</dt><dd>
'''archive_version_number'''()
</dd><dt>'''archive_api_version'''()</dt><dd>
'''archive_version_number'''()
</dd><dt>'''archive_version'''()</dt><dd>
'''archive_version_string'''()
</dd><dt>'''archive_version_stamp'''()</dt><dd>
'''archive_version_number'''()
</dd><dt>'''archive_read_set_filter_options'''()</dt><dd>
'''archive_read_set_options'''()
or
'''archive_read_set_filter_option'''()
</dd><dt>'''archive_read_set_format_options'''()</dt><dd>
'''archive_read_set_options'''()
or
'''archive_read_set_format_option'''()
</dd><dt>'''archive_write_set_filter_options'''()</dt><dd>
'''archive_write_set_options'''()
or
'''archive_write_set_filter_option'''()
</dd><dt>'''archive_write_set_format_options'''()</dt><dd>
'''archive_write_set_options'''()
or
'''archive_write_set_format_option'''()
</dd><dt></dt><dd>
ARCHIVE_API_FEATURE
ARCHIVE_VERSION_NUMBER
</dd><dt></dt><dd>
ARCHIVE_API_VERSION
ARCHIVE_VERSION_NUMBER
</dd><dt></dt><dd>
ARCHIVE_VERSION_STAMP
ARCHIVE_VERSION_NUMBER
</dd><dt></dt><dd>
ARCHIVE_LIBRARY_VERSION
ARCHIVE_VERSION_STRING
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_NONE
ARCHIVE_FILTER_NONE
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_GZIP
ARCHIVE_FILTER_GZIP
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_BZIP2
ARCHIVE_FILTER_BZIP2
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_COMPRESS
ARCHIVE_FILTER_COMPRESS
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_PROGRAM
ARCHIVE_FILTER_PROGRAM
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_LZMA
ARCHIVE_FILTER_LZMA
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_XZ
ARCHIVE_FILTER_XZ
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_UU
ARCHIVE_FILTER_UU
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_RPM
ARCHIVE_FILTER_RPM
</dd><dt></dt><dd>
ARCHIVE_COMPRESSION_LZIP
ARCHIVE_FILTER_LZIP
</dd><dt></dt><dd>
ARCHIVE_BYTES_PER_RECORD
```text
512
```
</dd><dt></dt><dd>
ARCHIVE_DEFAULT_BYTES_PER_BLOCK
```text
10240
```
</dd></dl>
== SEE ALSO ==
[[ManPagerchiveead3]],
[[ManPagerchiveeadilter3]],
[[ManPagerchiveeadormat3]],
[[ManPagerchiveeadetptions3]],
[[ManPagerchivetil3]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteilter3]],
[[ManPagerchiveriteormat3]],
[[ManPagerchiveriteetptions3]],
[[ManPageibarchive3]]

437
dependencies/libarchive-3.4.2/doc/wiki/ManPageLibarchiveFormats5.wiki vendored Normal file
View file

@ -0,0 +1,437 @@
LIBARCHIVE-FORMATS(5) manual page
== NAME ==
'''libarchive-formats'''
- archive formats supported by the libarchive library
== DESCRIPTION ==
The
[[ManPageibarchive3]]
library reads and writes a variety of streaming archive formats.
Generally speaking, all of these archive formats consist of a series of
"entries".
Each entry stores a single file system object, such as a file, directory,
or symbolic link.
The following provides a brief description of each format supported
by libarchive, with some information about recognized extensions or
limitations of the current library support.
Note that just because a format is supported by libarchive does not
imply that a program that uses libarchive will support that format.
Applications that use libarchive specify which formats they wish
to support, though many programs do use libarchive convenience
functions to enable all supported formats.
=== Tar Formats===
The
[[ManPageibarchive3]]
library can read most tar archives.
It can write POSIX-standard
"ustar"
and
"pax interchange"
formats as well as v7 tar format and a subset of the legacy GNU tar format.
All tar formats store each entry in one or more 512-byte records.
The first record is used for file metadata, including filename,
timestamp, and mode information, and the file data is stored in
subsequent records.
Later variants have extended this by either appropriating undefined
areas of the header record, extending the header to multiple records,
or by storing special entries that modify the interpretation of
subsequent entries.
<dl>
<dt>'''gnutar'''</dt><dd>
The
[[ManPageibarchive3]]
library can read most GNU-format tar archives.
It currently supports the most popular GNU extensions, including
modern long filename and linkname support, as well as atime and ctime data.
The libarchive library does not support multi-volume
archives, nor the old GNU long filename format.
It can read GNU sparse file entries, including the new POSIX-based
formats.
The
[[ManPageibarchive3]]
library can write GNU tar format, including long filename
and linkname support, as well as atime and ctime data.
</dd><dt>'''pax'''</dt><dd>
The
[[ManPageibarchive3]]
library can read and write POSIX-compliant pax interchange format
archives.
Pax interchange format archives are an extension of the older ustar
format that adds a separate entry with additional attributes stored
as key/value pairs immediately before each regular entry.
The presence of these additional entries is the only difference between
pax interchange format and the older ustar format.
The extended attributes are of unlimited length and are stored
as UTF-8 Unicode strings.
Keywords defined in the standard are in all lowercase; vendors are allowed
to define custom keys by preceding them with the vendor name in all uppercase.
When writing pax archives, libarchive uses many of the SCHILY keys
defined by Joerg Schilling's
"star"
archiver and a few LIBARCHIVE keys.
The libarchive library can read most of the SCHILY keys
and most of the GNU keys introduced by GNU tar.
It silently ignores any keywords that it does not understand.
The pax interchange format converts filenames to Unicode
and stores them using the UTF-8 encoding.
Prior to libarchive 3.0, libarchive erroneously assumed
that the system wide-character routines natively supported
Unicode.
This caused it to mis-handle non-ASCII filenames on systems
that did not satisfy this assumption.
</dd><dt>'''restricted''' pax</dt><dd>
The libarchive library can also write pax archives in which it
attempts to suppress the extended attributes entry whenever
possible.
The result will be identical to a ustar archive unless the
extended attributes entry is required to store a long file
name, long linkname, extended ACL, file flags, or if any of the standard
ustar data (user name, group name, UID, GID, etc) cannot be fully
represented in the ustar header.
In all cases, the result can be dearchived by any program that
can read POSIX-compliant pax interchange format archives.
Programs that correctly read ustar format (see below) will also be
able to read this format; any extended attributes will be extracted as
separate files stored in
''PaxHeader''
directories.
</dd><dt>'''ustar'''</dt><dd>
The libarchive library can both read and write this format.
This format has the following limitations:
<ul>
<li>
Device major and minor numbers are limited to 21 bits.
Nodes with larger numbers will not be added to the archive.
</li><li>
Path names in the archive are limited to 255 bytes.
(Shorter if there is no / character in exactly the right place.)
</li><li>
Symbolic links and hard links are stored in the archive with
the name of the referenced file.
This name is limited to 100 bytes.
</li><li>
Extended attributes, file flags, and other extended
security information cannot be stored.
</li><li>
Archive entries are limited to 8 gigabytes in size.
</li></ul>
Note that the pax interchange format has none of these restrictions.
The ustar format is old and widely supported.
It is recommended when compatibility is the primary concern.
</dd><dt>'''v7'''</dt><dd>
The libarchive library can read and write the legacy v7 tar format.
This format has the following limitations:
<ul>
<li>
Only regular files, directories, and symbolic links can be archived.
Block and character device nodes, FIFOs, and sockets cannot be archived.
</li><li>
Path names in the archive are limited to 100 bytes.
</li><li>
Symbolic links and hard links are stored in the archive with
the name of the referenced file.
This name is limited to 100 bytes.
</li><li>
User and group information are stored as numeric IDs; there
is no provision for storing user or group names.
</li><li>
Extended attributes, file flags, and other extended
security information cannot be stored.
</li><li>
Archive entries are limited to 8 gigabytes in size.
</li></ul>
Generally, users should prefer the ustar format for portability
as the v7 tar format is both less useful and less portable.
</dd></dl>
The libarchive library also reads a variety of commonly-used extensions to
the basic tar format.
These extensions are recognized automatically whenever they appear.
<dl>
<dt>Numeric extensions.</dt><dd>
The POSIX standards require fixed-length numeric fields to be written with
some character position reserved for terminators.
Libarchive allows these fields to be written without terminator characters.
This extends the allowable range; in particular, ustar archives with this
extension can support entries up to 64 gigabytes in size.
Libarchive also recognizes base-256 values in most numeric fields.
This essentially removes all limitations on file size, modification time,
and device numbers.
</dd><dt>Solaris extensions</dt><dd>
Libarchive recognizes ACL and extended attribute records written
by Solaris tar.
</dd></dl>
The first tar program appeared in Seventh Edition Unix in 1979.
The first official standard for the tar file format was the
"ustar"
(Unix Standard Tar) format defined by POSIX in 1988.
POSIX.1-2001 extended the ustar format to create the
"pax interchange"
format.
=== Cpio Formats===
The libarchive library can read a number of common cpio variants and can write
"odc"
and
"newc"
format archives.
A cpio archive stores each entry as a fixed-size header followed
by a variable-length filename and variable-length data.
Unlike the tar format, the cpio format does only minimal padding
of the header or file data.
There are several cpio variants, which differ primarily in
how they store the initial header: some store the values as
octal or hexadecimal numbers in ASCII, others as binary values of
varying byte order and length.
<dl>
<dt>'''binary'''</dt><dd>
The libarchive library transparently reads both big-endian and little-endian
variants of the original binary cpio format.
This format used 32-bit binary values for file size and mtime,
and 16-bit binary values for the other fields.
</dd><dt>'''odc'''</dt><dd>
The libarchive library can both read and write this
POSIX-standard format, which is officially known as the
"cpio interchange format"
or the
"octet-oriented cpio archive format"
and sometimes unofficially referred to as the
"old character format".
This format stores the header contents as octal values in ASCII.
It is standard, portable, and immune from byte-order confusion.
File sizes and mtime are limited to 33 bits (8GB file size),
other fields are limited to 18 bits.
</dd><dt>'''SVR4/newc'''</dt><dd>
The libarchive library can read both CRC and non-CRC variants of
this format.
The SVR4 format uses eight-digit hexadecimal values for
all header fields.
This limits file size to 4GB, and also limits the mtime and
other fields to 32 bits.
The SVR4 format can optionally include a CRC of the file
contents, although libarchive does not currently verify this CRC.
</dd></dl>
Cpio first appeared in PWB/UNIX 1.0, which was released within
AT&T in 1977.
PWB/UNIX 1.0 formed the basis of System III Unix, released outside
of AT&T in 1981.
This makes cpio older than tar, although cpio was not included
in Version 7 AT&T Unix.
As a result, the tar command became much better known in universities
and research groups that used Version 7.
The combination of the
'''find'''
and
'''cpio'''
utilities provided very precise control over file selection.
Unfortunately, the format has many limitations that make it unsuitable
for widespread use.
Only the POSIX format permits files over 4GB, and its 18-bit
limit for most other fields makes it unsuitable for modern systems.
In addition, cpio formats only store numeric UID/GID values (not
usernames and group names), which can make it very difficult to correctly
transfer archives across systems with dissimilar user numbering.
=== Shar Formats===
A
"shell archive"
is a shell script that, when executed on a POSIX-compliant
system, will recreate a collection of file system objects.
The libarchive library can write two different kinds of shar archives:
<dl>
<dt>'''shar'''</dt><dd>
The traditional shar format uses a limited set of POSIX
commands, including
[[echo(1)|http://www.freebsd.org/cgi/man.cgi?query=echo&sektion=1]],
[[mkdir(1)|http://www.freebsd.org/cgi/man.cgi?query=mkdir&sektion=1]],
and
[[sed(1)|http://www.freebsd.org/cgi/man.cgi?query=sed&sektion=1]].
It is suitable for portably archiving small collections of plain text files.
However, it is not generally well-suited for large archives
(many implementations of
[[sh(1)|http://www.freebsd.org/cgi/man.cgi?query=sh&sektion=1]]
have limits on the size of a script) nor should it be used with non-text files.
</dd><dt>'''shardump'''</dt><dd>
This format is similar to shar but encodes files using
[[uuencode(1)|http://www.freebsd.org/cgi/man.cgi?query=uuencode&sektion=1]]
so that the result will be a plain text file regardless of the file contents.
It also includes additional shell commands that attempt to reproduce as
many file attributes as possible, including owner, mode, and flags.
The additional commands used to restore file attributes make
shardump archives less portable than plain shar archives.
</dd></dl>
=== ISO9660 format===
Libarchive can read and extract from files containing ISO9660-compliant
CDROM images.
In many cases, this can remove the need to burn a physical CDROM
just in order to read the files contained in an ISO9660 image.
It also avoids security and complexity issues that come with
virtual mounts and loopback devices.
Libarchive supports the most common Rockridge extensions and has partial
support for Joliet extensions.
If both extensions are present, the Joliet extensions will be
used and the Rockridge extensions will be ignored.
In particular, this can create problems with hardlinks and symlinks,
which are supported by Rockridge but not by Joliet.
Libarchive reads ISO9660 images using a streaming strategy.
This allows it to read compressed images directly
(decompressing on the fly) and allows it to read images
directly from network sockets, pipes, and other non-seekable
data sources.
This strategy works well for optimized ISO9660 images created
by many popular programs.
Such programs collect all directory information at the beginning
of the ISO9660 image so it can be read from a physical disk
with a minimum of seeking.
However, not all ISO9660 images can be read in this fashion.
Libarchive can also write ISO9660 images.
Such images are fully optimized with the directory information
preceding all file data.
This is done by storing all file data to a temporary file
while collecting directory information in memory.
When the image is finished, libarchive writes out the
directory structure followed by the file data.
The location used for the temporary file can be changed
by the usual environment variables.
=== Zip format===
Libarchive can read and write zip format archives that have
uncompressed entries and entries compressed with the
"deflate"
algorithm.
Other zip compression algorithms are not supported.
It can extract jar archives, archives that use Zip64 extensions and
self-extracting zip archives.
Libarchive can use either of two different strategies for
reading Zip archives:
a streaming strategy which is fast and can handle extremely
large archives, and a seeking strategy which can correctly
process self-extracting Zip archives and archives with
deleted members or other in-place modifications.
The streaming reader processes Zip archives as they are read.
It can read archives of arbitrary size from tape or
network sockets, and can decode Zip archives that have
been separately compressed or encoded.
However, self-extracting Zip archives and archives with
certain types of modifications cannot be correctly
handled.
Such archives require that the reader first process the
Central Directory, which is ordinarily located
at the end of a Zip archive and is thus inaccessible
to the streaming reader.
If the program using libarchive has enabled seek support, then
libarchive will use this to processes the central directory first.
In particular, the seeking reader must be used to
correctly handle self-extracting archives.
Such archives consist of a program followed by a regular
Zip archive.
The streaming reader cannot parse the initial program
portion, but the seeking reader starts by reading the
Central Directory from the end of the archive.
Similarly, Zip archives that have been modified in-place
can have deleted entries or other garbage data that
can only be accurately detected by first reading the
Central Directory.
=== Archive (library) file format===
The Unix archive format (commonly created by the
[[ar(1)|http://www.freebsd.org/cgi/man.cgi?query=ar&sektion=1]]
archiver) is a general-purpose format which is
used almost exclusively for object files to be
read by the link editor
[[ld(1)|http://www.freebsd.org/cgi/man.cgi?query=ld&sektion=1]].
The ar format has never been standardised.
There are two common variants:
the GNU format derived from SVR4,
and the BSD format, which first appeared in 4.4BSD.
The two differ primarily in their handling of filenames
longer than 15 characters:
the GNU/SVR4 variant writes a filename table at the beginning of the archive;
the BSD format stores each long filename in an extension
area adjacent to the entry.
Libarchive can read both extensions,
including archives that may include both types of long filenames.
Programs using libarchive can write GNU/SVR4 format
if they provide an entry called
''//''
containing a filename table to be written into the archive
before any of the entries.
Any entries whose names are not in the filename table
will be written using BSD-style long filenames.
This can cause problems for programs such as
GNU ld that do not support the BSD-style long filenames.
=== mtree===
Libarchive can read and write files in
[[ManPageMtree5]]
format.
This format is not a true archive format, but rather a textual description
of a file hierarchy in which each line specifies the name of a file and
provides specific metadata about that file.
Libarchive can read all of the keywords supported by both
the NetBSD and FreeBSD versions of
[[mtree(8)|http://www.freebsd.org/cgi/man.cgi?query=mtree&sektion=8]],
although many of the keywords cannot currently be stored in an
'''archive_entry'''
object.
When writing, libarchive supports use of the
[[ManPagerchiveriteetptions3]]
interface to specify which keywords should be included in the
output.
If libarchive was compiled with access to suitable
cryptographic libraries (such as the OpenSSL libraries),
it can compute hash entries such as
'''sha512'''
or
'''md5'''
from file data being written to the mtree writer.
When reading an mtree file, libarchive will locate the corresponding
files on disk using the
'''contents'''
keyword if present or the regular filename.
If it can locate and open the file on disk, it will use that
to fill in any metadata that is missing from the mtree file
and will read the file contents and return those to the program
using libarchive.
If it cannot locate and open the file on disk, libarchive
will return an error for any attempt to read the entry
body.
=== 7-Zip===
Libarchive can read and write 7-Zip format archives.
TODO: Need more information
=== CAB===
Libarchive can read Microsoft Cabinet (
"CAB )"
format archives.
TODO: Need more information.
=== LHA===
TODO: Information about libarchive's LHA support
=== RAR===
Libarchive has limited support for reading RAR format archives.
Currently, libarchive can read RARv3 format archives
which have been either created uncompressed, or compressed using
any of the compression methods supported by the RARv3 format.
Libarchive can also read self-extracting RAR archives.
=== Warc===
Libarchive can read and write
"web archives".
TODO: Need more information
=== XAR===
Libarchive can read and write the XAR format used by many Apple tools.
TODO: Need more information
== SEE ALSO ==
[[ar(1)|http://www.freebsd.org/cgi/man.cgi?query=ar&sektion=1]],
[[ManPageBsdcpio1]],
[[mkisofs(1)|http://www.freebsd.org/cgi/man.cgi?query=mkisofs&sektion=1]],
[[shar(1)|http://www.freebsd.org/cgi/man.cgi?query=shar&sektion=1]],
[[ManPageBsdtar1]],
[[zip(1)|http://www.freebsd.org/cgi/man.cgi?query=zip&sektion=1]],
[[zlib(3)|http://www.freebsd.org/cgi/man.cgi?query=zlib&sektion=3]],
[[ManPageCpio5]],
[[ManPageMtree5]],
[[ManPageTar5]]

336
dependencies/libarchive-3.4.2/doc/wiki/ManPageLibarchiveInternals3.wiki vendored Normal file
View file

@ -0,0 +1,336 @@
LIBARCHIVE_INTERNALS(3) manual page
== NAME ==
'''libarchive_internals'''
- description of libarchive internal interfaces
== OVERVIEW ==
The
'''libarchive'''
library provides a flexible interface for reading and writing
streaming archive files such as tar and cpio.
Internally, it follows a modular layered design that should
make it easy to add new archive and compression formats.
== GENERAL ARCHITECTURE ==
Externally, libarchive exposes most operations through an
opaque, object-style interface.
The
[[ManPagerchiventry3]]
objects store information about a single filesystem object.
The rest of the library provides facilities to write
[[ManPagerchiventry3]]
objects to archive files,
read them from archive files,
and write them to disk.
(There are plans to add a facility to read
[[ManPagerchiventry3]]
objects from disk as well.)
The read and write APIs each have four layers: a public API
layer, a format layer that understands the archive file format,
a compression layer, and an I/O layer.
The I/O layer is completely exposed to clients who can replace
it entirely with their own functions.
In order to provide as much consistency as possible for clients,
some public functions are virtualized.
Eventually, it should be possible for clients to open
an archive or disk writer, and then use a single set of
code to select and write entries, regardless of the target.
== READ ARCHITECTURE ==
From the outside, clients use the
[[ManPagerchiveead3]]
API to manipulate an
'''archive'''
object to read entries and bodies from an archive stream.
Internally, the
'''archive'''
object is cast to an
'''archive_read'''
object, which holds all read-specific data.
The API has four layers:
The lowest layer is the I/O layer.
This layer can be overridden by clients, but most clients use
the packaged I/O callbacks provided, for example, by
[[ManPagerchiveeadpenemory3]],
and
[[ManPagerchiveeadpend3]].
The compression layer calls the I/O layer to
read bytes and decompresses them for the format layer.
The format layer unpacks a stream of uncompressed bytes and
creates
'''archive_entry'''
objects from the incoming data.
The API layer tracks overall state
(for example, it prevents clients from reading data before reading a header)
and invokes the format and compression layer operations
through registered function pointers.
In particular, the API layer drives the format-detection process:
When opening the archive, it reads an initial block of data
and offers it to each registered compression handler.
The one with the highest bid is initialized with the first block.
Similarly, the format handlers are polled to see which handler
is the best for each archive.
(Prior to 2.4.0, the format bidders were invoked for each
entry, but this design hindered error recovery.)
=== I/O Layer and Client Callbacks===
The read API goes to some lengths to be nice to clients.
As a result, there are few restrictions on the behavior of
the client callbacks.
The client read callback is expected to provide a block
of data on each call.
A zero-length return does indicate end of file, but otherwise
blocks may be as small as one byte or as large as the entire file.
In particular, blocks may be of different sizes.
The client skip callback returns the number of bytes actually
skipped, which may be much smaller than the skip requested.
The only requirement is that the skip not be larger.
In particular, clients are allowed to return zero for any
skip that they don't want to handle.
The skip callback must never be invoked with a negative value.
Keep in mind that not all clients are reading from disk:
clients reading from networks may provide different-sized
blocks on every request and cannot skip at all;
advanced clients may use
[[mmap(2)|http://www.freebsd.org/cgi/man.cgi?query=mmap&sektion=2]]
to read the entire file into memory at once and return the
entire file to libarchive as a single block;
other clients may begin asynchronous I/O operations for the
next block on each request.
=== Decompresssion Layer===
The decompression layer not only handles decompression,
it also buffers data so that the format handlers see a
much nicer I/O model.
The decompression API is a two stage peek/consume model.
A read_ahead request specifies a minimum read amount;
the decompression layer must provide a pointer to at least
that much data.
If more data is immediately available, it should return more:
the format layer handles bulk data reads by asking for a minimum
of one byte and then copying as much data as is available.
A subsequent call to the
'''consume'''()
function advances the read pointer.
Note that data returned from a
'''read_ahead'''()
call is guaranteed to remain in place until
the next call to
'''read_ahead'''().
Intervening calls to
'''consume'''()
should not cause the data to move.
Skip requests must always be handled exactly.
Decompression handlers that cannot seek forward should
not register a skip handler;
the API layer fills in a generic skip handler that reads and discards data.
A decompression handler has a specific lifecycle:
<dl>
<dt>Registration/Configuration</dt><dd>
When the client invokes the public support function,
the decompression handler invokes the internal
'''__archive_read_register_compression'''()
function to provide bid and initialization functions.
This function returns
'''NULL'''
on error or else a pointer to a
'''struct''' decompressor_t.
This structure contains a
''void'' * config
slot that can be used for storing any customization information.
</dd><dt>Bid</dt><dd>
The bid function is invoked with a pointer and size of a block of data.
The decompressor can access its config data
through the
''decompressor''
element of the
'''archive_read'''
object.
The bid function is otherwise stateless.
In particular, it must not perform any I/O operations.
The value returned by the bid function indicates its suitability
for handling this data stream.
A bid of zero will ensure that this decompressor is never invoked.
Return zero if magic number checks fail.
Otherwise, your initial implementation should return the number of bits
actually checked.
For example, if you verify two full bytes and three bits of another
byte, bid 19.
Note that the initial block may be very short;
be careful to only inspect the data you are given.
(The current decompressors require two bytes for correct bidding.)
</dd><dt>Initialize</dt><dd>
The winning bidder will have its init function called.
This function should initialize the remaining slots of the
''struct'' decompressor_t
object pointed to by the
''decompressor''
element of the
''archive_read''
object.
In particular, it should allocate any working data it needs
in the
''data''
slot of that structure.
The init function is called with the block of data that
was used for tasting.
At this point, the decompressor is responsible for all I/O
requests to the client callbacks.
The decompressor is free to read more data as and when
necessary.
</dd><dt>Satisfy I/O requests</dt><dd>
The format handler will invoke the
''read_ahead'',
''consume'',
and
''skip''
functions as needed.
</dd><dt>Finish</dt><dd>
The finish method is called only once when the archive is closed.
It should release anything stored in the
''data''
and
''config''
slots of the
''decompressor''
object.
It should not invoke the client close callback.
</dd></dl>
=== Format Layer===
The read formats have a similar lifecycle to the decompression handlers:
<dl>
<dt>Registration</dt><dd>
Allocate your private data and initialize your pointers.
</dd><dt>Bid</dt><dd>
Formats bid by invoking the
'''read_ahead'''()
decompression method but not calling the
'''consume'''()
method.
This allows each bidder to look ahead in the input stream.
Bidders should not look further ahead than necessary, as long
look aheads put pressure on the decompression layer to buffer
lots of data.
Most formats only require a few hundred bytes of look ahead;
look aheads of a few kilobytes are reasonable.
(The ISO9660 reader sometimes looks ahead by 48k, which
should be considered an upper limit.)
</dd><dt>Read header</dt><dd>
The header read is usually the most complex part of any format.
There are a few strategies worth mentioning:
For formats such as tar or cpio, reading and parsing the header is
straightforward since headers alternate with data.
For formats that store all header data at the beginning of the file,
the first header read request may have to read all headers into
memory and store that data, sorted by the location of the file
data.
Subsequent header read requests will skip forward to the
beginning of the file data and return the corresponding header.
</dd><dt>Read Data</dt><dd>
The read data interface supports sparse files; this requires that
each call return a block of data specifying the file offset and
size.
This may require you to carefully track the location so that you
can return accurate file offsets for each read.
Remember that the decompressor will return as much data as it has.
Generally, you will want to request one byte,
examine the return value to see how much data is available, and
possibly trim that to the amount you can use.
You should invoke consume for each block just before you return it.
</dd><dt>Skip All Data</dt><dd>
The skip data call should skip over all file data and trailing padding.
This is called automatically by the API layer just before each
header read.
It is also called in response to the client calling the public
'''data_skip'''()
function.
</dd><dt>Cleanup</dt><dd>
On cleanup, the format should release all of its allocated memory.
</dd></dl>
=== API Layer===
XXX to do XXX
== WRITE ARCHITECTURE ==
The write API has a similar set of four layers:
an API layer, a format layer, a compression layer, and an I/O layer.
The registration here is much simpler because only
one format and one compression can be registered at a time.
=== I/O Layer and Client Callbacks===
XXX To be written XXX
=== Compression Layer===
XXX To be written XXX
=== Format Layer===
XXX To be written XXX
=== API Layer===
XXX To be written XXX
== WRITE_DISK ARCHITECTURE ==
The write_disk API is intended to look just like the write API
to clients.
Since it does not handle multiple formats or compression, it
is not layered internally.
== GENERAL SERVICES ==
The
'''archive_read''',
'''archive_write''',
and
'''archive_write_disk'''
objects all contain an initial
'''archive'''
object which provides common support for a set of standard services.
(Recall that ANSI/ISO C90 guarantees that you can cast freely between
a pointer to a structure and a pointer to the first element of that
structure.)
The
'''archive'''
object has a magic value that indicates which API this object
is associated with,
slots for storing error information,
and function pointers for virtualized API functions.
== MISCELLANEOUS NOTES ==
Connecting existing archiving libraries into libarchive is generally
quite difficult.
In particular, many existing libraries strongly assume that you
are reading from a file; they seek forwards and backwards as necessary
to locate various pieces of information.
In contrast, libarchive never seeks backwards in its input, which
sometimes requires very different approaches.
For example, libarchive's ISO9660 support operates very differently
from most ISO9660 readers.
The libarchive support utilizes a work-queue design that
keeps a list of known entries sorted by their location in the input.
Whenever libarchive's ISO9660 implementation is asked for the next
header, checks this list to find the next item on the disk.
Directories are parsed when they are encountered and new
items are added to the list.
This design relies heavily on the ISO9660 image being optimized so that
directories always occur earlier on the disk than the files they
describe.
Depending on the specific format, such approaches may not be possible.
The ZIP format specification, for example, allows archivers to store
key information only at the end of the file.
In theory, it is possible to create ZIP archives that cannot
be read without seeking.
Fortunately, such archives are very rare, and libarchive can read
most ZIP archives, though it cannot always extract as much information
as a dedicated ZIP program.
== SEE ALSO ==
[[ManPagerchiventry3]],
[[ManPagerchiveead3]],
[[ManPagerchiverite3]],
[[ManPagerchiveriteisk3]],
[[ManPageibarchive3]]
== HISTORY ==
The
'''libarchive'''
library first appeared in
FreeBSD 5.3.
== AUTHORS ==
The
'''libarchive'''
library was written by
Tim Kientzle &lt;kientzle@acm.org.&gt;

292
dependencies/libarchive-3.4.2/doc/wiki/ManPageMtree5.wiki vendored Normal file
View file

@ -0,0 +1,292 @@
MTREE(5) manual page
== NAME ==
'''mtree'''
- format of mtree dir hierarchy files
== DESCRIPTION ==
The
'''mtree'''
format is a textual format that describes a collection of filesystem objects.
Such files are typically used to create or verify directory hierarchies.
=== General Format===
An
'''mtree'''
file consists of a series of lines, each providing information
about a single filesystem object.
Leading whitespace is always ignored.
When encoding file or pathnames, any backslash character or
character outside of the 95 printable ASCII characters must be
encoded as a backslash followed by three
octal digits.
When reading mtree files, any appearance of a backslash
followed by three octal digits should be converted into the
corresponding character.
Each line is interpreted independently as one of the following types:
<dl>
<dt>Blank</dt><dd>
Blank lines are ignored.
</dd><dt>Comment</dt><dd>
Lines beginning with
'''#'''
are ignored.
</dd><dt>Special</dt><dd>
Lines beginning with
'''/'''
are special commands that influence
the interpretation of later lines.
</dd><dt>Relative</dt><dd>
If the first whitespace-delimited word has no
'''/'''
characters,
it is the name of a file in the current directory.
Any relative entry that describes a directory changes the
current directory.
</dd><dt>dot-dot</dt><dd>
As a special case, a relative entry with the filename
''..''
changes the current directory to the parent directory.
Options on dot-dot entries are always ignored.
</dd><dt>Full</dt><dd>
If the first whitespace-delimited word has a
'''/'''
character after
the first character, it is the pathname of a file relative to the
starting directory.
There can be multiple full entries describing the same file.
</dd></dl>
Some tools that process
'''mtree'''
files may require that multiple lines describing the same file
occur consecutively.
It is not permitted for the same file to be mentioned using
both a relative and a full file specification.
=== Special commands===
Two special commands are currently defined:
<dl>
<dt>'''/set'''</dt><dd>
This command defines default values for one or more keywords.
It is followed on the same line by one or more whitespace-separated
keyword definitions.
These definitions apply to all following files that do not specify
a value for that keyword.
</dd><dt>'''/unset'''</dt><dd>
This command removes any default value set by a previous
'''/set'''
command.
It is followed on the same line by one or more keywords
separated by whitespace.
</dd></dl>
=== Keywords===
After the filename, a full or relative entry consists of zero
or more whitespace-separated keyword definitions.
Each such definition consists of a key from the following
list immediately followed by an '=' sign
and a value.
Software programs reading mtree files should warn about
unrecognized keywords.
Currently supported keywords are as follows:
<dl>
<dt>'''cksum'''</dt><dd>
The checksum of the file using the default algorithm specified by
the
[[cksum(1)|http://www.freebsd.org/cgi/man.cgi?query=cksum&sektion=1]]
utility.
</dd><dt>'''device'''</dt><dd>
The device number for
.B block
or
.B char
file types.
The value must be one of the following forms:
<dl>
<dt>''format'',''major'',''minor''Bo,''subunit'' Bc</dt><dd>
A device with
''major'', minor
and optional
''subunit''
fields.
Their meaning is specified by the operating's system
''format''.
See below for valid formats.
</dd><dt>''number''</dt><dd>
Opaque number (as stored on the file system).
</dd></dl>
The following values for
''format''
are recognized:
.B native ,
.B 386bsd ,
.B 4bsd ,
.B bsdos ,
.B freebsd ,
.B hpux ,
.B isc ,
.B linux ,
.B netbsd ,
.B osf1 ,
.B sco ,
.B solaris ,
.B sunos ,
.B svr3 ,
.B svr4 ,
and
.B ultrix .
See
[[mknod(8)|http://www.freebsd.org/cgi/man.cgi?query=mknod&sektion=8]]
for more details.
</dd><dt>'''contents'''</dt><dd>
The full pathname of a file that holds the contents of this file.
</dd><dt>'''flags'''</dt><dd>
The file flags as a symbolic name.
See
[[chflags(1)|http://www.freebsd.org/cgi/man.cgi?query=chflags&sektion=1]]
for information on these names.
If no flags are to be set the string
"none"
may be used to override the current default.
</dd><dt>'''gid'''</dt><dd>
The file group as a numeric value.
</dd><dt>'''gname'''</dt><dd>
The file group as a symbolic name.
</dd><dt>'''ignore'''</dt><dd>
Ignore any file hierarchy below this file.
</dd><dt>'''inode'''</dt><dd>
The inode number.
</dd><dt>'''link'''</dt><dd>
The target of the symbolic link when type=link.
</dd><dt>'''md5'''</dt><dd>
The MD5 message digest of the file.
</dd><dt>'''md5digest'''</dt><dd>
A synonym for
'''md5'''.
</dd><dt>'''mode'''</dt><dd>
The current file's permissions as a numeric (octal) or symbolic
value.
</dd><dt>'''nlink'''</dt><dd>
The number of hard links the file is expected to have.
</dd><dt>'''nochange'''</dt><dd>
Make sure this file or directory exists but otherwise ignore all attributes.
</dd><dt>'''optional'''</dt><dd>
The file is optional; do not complain about the file if it is not in
the file hierarchy.
</dd><dt>'''resdevice'''</dt><dd>
The
"resident"
device number of the file, e.g. the ID of the device that
contains the file.
Its format is the same as the one for
'''device'''.
</dd><dt>'''ripemd160digest'''</dt><dd>
The
'''RIPEMD160'''
message digest of the file.
</dd><dt>'''rmd160'''</dt><dd>
A synonym for
'''ripemd160digest'''.
</dd><dt>'''rmd160digest'''</dt><dd>
A synonym for
'''ripemd160digest'''.
</dd><dt>'''sha1'''</dt><dd>
The
'''FIPS'''
160-1
("Tn SHA-1")
message digest of the file.
</dd><dt>'''sha1digest'''</dt><dd>
A synonym for
'''sha1'''.
</dd><dt>'''sha256'''</dt><dd>
The
'''FIPS'''
180-2
("Tn SHA-256")
message digest of the file.
</dd><dt>'''sha256digest'''</dt><dd>
A synonym for
'''sha256'''.
</dd><dt>'''sha384'''</dt><dd>
The
'''FIPS'''
180-2
("Tn SHA-384")
message digest of the file.
</dd><dt>'''sha384digest'''</dt><dd>
A synonym for
'''sha384'''.
</dd><dt>'''sha512'''</dt><dd>
The
'''FIPS'''
180-2
("Tn SHA-512")
message digest of the file.
</dd><dt>'''sha512digest'''</dt><dd>
A synonym for
'''sha512'''.
</dd><dt>'''size'''</dt><dd>
The size, in bytes, of the file.
</dd><dt>'''time'''</dt><dd>
The last modification time of the file.
</dd><dt>'''type'''</dt><dd>
The type of the file; may be set to any one of the following:
<dl>
<dt>'''block'''</dt><dd>
block special device
</dd><dt>'''char'''</dt><dd>
character special device
</dd><dt>'''dir'''</dt><dd>
directory
</dd><dt>'''fifo'''</dt><dd>
fifo
</dd><dt>'''file'''</dt><dd>
regular file
</dd><dt>'''link'''</dt><dd>
symbolic link
</dd><dt>'''socket'''</dt><dd>
socket
</dd></dl>
</dd><dt>'''uid'''</dt><dd>
The file owner as a numeric value.
</dd><dt>'''uname'''</dt><dd>
The file owner as a symbolic name.
</dd></dl>
== SEE ALSO ==
[[cksum(1)|http://www.freebsd.org/cgi/man.cgi?query=cksum&sektion=1]],
[[find(1)|http://www.freebsd.org/cgi/man.cgi?query=find&sektion=1]],
[[mtree(8)|http://www.freebsd.org/cgi/man.cgi?query=mtree&sektion=8]]
== HISTORY ==
The
'''mtree'''
utility appeared in
BSD 4.3 Reno.
The
'''MD5'''
digest capability was added in
FreeBSD 2.1,
in response to the widespread use of programs which can spoof
[[cksum(1)|http://www.freebsd.org/cgi/man.cgi?query=cksum&sektion=1]].
The
'''SHA-1'''
and
'''RIPEMD160'''
digests were added in
FreeBSD 4.0,
as new attacks have demonstrated weaknesses in
'''MD5 .'''
The
'''SHA-256'''
digest was added in
FreeBSD 6.0.
Support for file flags was added in
FreeBSD 4.0,
and mostly comes from
NetBSD.
The
"full"
entry format was added by
NetBSD.

922
dependencies/libarchive-3.4.2/doc/wiki/ManPageTar5.wiki vendored Normal file
View file

@ -0,0 +1,922 @@
TAR(5) manual page
== NAME ==
'''tar'''
- format of tape archive files
== DESCRIPTION ==
The
'''tar'''
archive format collects any number of files, directories, and other
file system objects (symbolic links, device nodes, etc.) into a single
stream of bytes.
The format was originally designed to be used with
tape drives that operate with fixed-size blocks, but is widely used as
a general packaging mechanism.
=== General Format===
A
'''tar'''
archive consists of a series of 512-byte records.
Each file system object requires a header record which stores basic metadata
(pathname, owner, permissions, etc.) and zero or more records containing any
file data.
The end of the archive is indicated by two records consisting
entirely of zero bytes.
For compatibility with tape drives that use fixed block sizes,
programs that read or write tar files always read or write a fixed
number of records with each I/O operation.
These
"blocks"
are always a multiple of the record size.
The maximum block size supported by early
implementations was 10240 bytes or 20 records.
This is still the default for most implementations
although block sizes of 1MiB (2048 records) or larger are
commonly used with modern high-speed tape drives.
(Note: the terms
"block"
and
"record"
here are not entirely standard; this document follows the
convention established by John Gilmore in documenting
'''pdtar'''.)
=== Old-Style Archive Format===
The original tar archive format has been extended many times to
include additional information that various implementors found
necessary.
This section describes the variant implemented by the tar command
included in
At v7,
which seems to be the earliest widely-used version of the tar program.
The header record for an old-style
'''tar'''
archive consists of the following:
```text
struct header_old_tar {
char name[100];
char mode[8];
char uid[8];
char gid[8];
char size[12];
char mtime[12];
char checksum[8];
char linkflag[1];
char linkname[100];
char pad[255];
};
```
All unused bytes in the header record are filled with nulls.
<dl>
<dt>''name''</dt><dd>
Pathname, stored as a null-terminated string.
Early tar implementations only stored regular files (including
hardlinks to those files).
One common early convention used a trailing "/" character to indicate
a directory name, allowing directory permissions and owner information
to be archived and restored.
</dd><dt>''mode''</dt><dd>
File mode, stored as an octal number in ASCII.
</dd><dt>''uid'', ''gid''</dt><dd>
User id and group id of owner, as octal numbers in ASCII.
</dd><dt>''size''</dt><dd>
Size of file, as octal number in ASCII.
For regular files only, this indicates the amount of data
that follows the header.
In particular, this field was ignored by early tar implementations
when extracting hardlinks.
Modern writers should always store a zero length for hardlink entries.
</dd><dt>''mtime''</dt><dd>
Modification time of file, as an octal number in ASCII.
This indicates the number of seconds since the start of the epoch,
00:00:00 UTC January 1, 1970.
Note that negative values should be avoided
here, as they are handled inconsistently.
</dd><dt>''checksum''</dt><dd>
Header checksum, stored as an octal number in ASCII.
To compute the checksum, set the checksum field to all spaces,
then sum all bytes in the header using unsigned arithmetic.
This field should be stored as six octal digits followed by a null and a space
character.
Note that many early implementations of tar used signed arithmetic
for the checksum field, which can cause interoperability problems
when transferring archives between systems.
Modern robust readers compute the checksum both ways and accept the
header if either computation matches.
</dd><dt>''linkflag'', ''linkname''</dt><dd>
In order to preserve hardlinks and conserve tape, a file
with multiple links is only written to the archive the first
time it is encountered.
The next time it is encountered, the
''linkflag''
is set to an ASCII
Sq 1
and the
''linkname''
field holds the first name under which this file appears.
(Note that regular files have a null value in the
''linkflag''
field.)
</dd></dl>
Early tar implementations varied in how they terminated these fields.
The tar command in
At v7
used the following conventions (this is also documented in early BSD manpages):
the pathname must be null-terminated;
the mode, uid, and gid fields must end in a space and a null byte;
the size and mtime fields must end in a space;
the checksum is terminated by a null and a space.
Early implementations filled the numeric fields with leading spaces.
This seems to have been common practice until the
<nowiki>IEEE Std 1003.1-1988 (``POSIX.1'')</nowiki>
standard was released.
For best portability, modern implementations should fill the numeric
fields with leading zeros.
=== Pre-POSIX Archives===
An early draft of
<nowiki>IEEE Std 1003.1-1988 (``POSIX.1'')</nowiki>
served as the basis for John Gilmore's
'''pdtar'''
program and many system implementations from the late 1980s
and early 1990s.
These archives generally follow the POSIX ustar
format described below with the following variations:
<ul>
<li>
The magic value consists of the five characters
"ustar"
followed by a space.
The version field contains a space character followed by a null.
</li><li>
The numeric fields are generally filled with leading spaces
(not leading zeros as recommended in the final standard).
</li><li>
The prefix field is often not used, limiting pathnames to
the 100 characters of old-style archives.
</li></ul>
=== POSIX ustar Archives===
<nowiki>IEEE Std 1003.1-1988 (``POSIX.1'')</nowiki>
defined a standard tar file format to be read and written
by compliant implementations of
[[ManPageBsdtar1]].
This format is often called the
"ustar"
format, after the magic value used
in the header.
(The name is an acronym for
"Unix Standard TAR".)
It extends the historic format with new fields:
```text
struct header_posix_ustar {
char name[100];
char mode[8];
char uid[8];
char gid[8];
char size[12];
char mtime[12];
char checksum[8];
char typeflag[1];
char linkname[100];
char magic[6];
char version[2];
char uname[32];
char gname[32];
char devmajor[8];
char devminor[8];
char prefix[155];
char pad[12];
};
```
<dl>
<dt>''typeflag''</dt><dd>
Type of entry.
POSIX extended the earlier
''linkflag''
field with several new type values:
<dl>
<dt>"0"</dt><dd>
Regular file.
NUL should be treated as a synonym, for compatibility purposes.
</dd><dt>"1"</dt><dd>
Hard link.
</dd><dt>"2"</dt><dd>
Symbolic link.
</dd><dt>"3"</dt><dd>
Character device node.
</dd><dt>"4"</dt><dd>
Block device node.
</dd><dt>"5"</dt><dd>
Directory.
</dd><dt>"6"</dt><dd>
FIFO node.
</dd><dt>"7"</dt><dd>
Reserved.
</dd><dt>Other</dt><dd>
A POSIX-compliant implementation must treat any unrecognized typeflag value
as a regular file.
In particular, writers should ensure that all entries
have a valid filename so that they can be restored by readers that do not
support the corresponding extension.
Uppercase letters "A" through "Z" are reserved for custom extensions.
Note that sockets and whiteout entries are not archivable.
</dd></dl>
It is worth noting that the
''size''
field, in particular, has different meanings depending on the type.
For regular files, of course, it indicates the amount of data
following the header.
For directories, it may be used to indicate the total size of all
files in the directory, for use by operating systems that pre-allocate
directory space.
For all other types, it should be set to zero by writers and ignored
by readers.
</dd><dt>''magic''</dt><dd>
Contains the magic value
"ustar"
followed by a NUL byte to indicate that this is a POSIX standard archive.
Full compliance requires the uname and gname fields be properly set.
</dd><dt>''version''</dt><dd>
Version.
This should be
"00"
(two copies of the ASCII digit zero) for POSIX standard archives.
</dd><dt>''uname'', ''gname''</dt><dd>
User and group names, as null-terminated ASCII strings.
These should be used in preference to the uid/gid values
when they are set and the corresponding names exist on
the system.
</dd><dt>''devmajor'', ''devminor''</dt><dd>
Major and minor numbers for character device or block device entry.
</dd><dt>''name'', ''prefix''</dt><dd>
If the pathname is too long to fit in the 100 bytes provided by the standard
format, it can be split at any
''/''
character with the first portion going into the prefix field.
If the prefix field is not empty, the reader will prepend
the prefix value and a
''/''
character to the regular name field to obtain the full pathname.
The standard does not require a trailing
''/''
character on directory names, though most implementations still
include this for compatibility reasons.
</dd></dl>
Note that all unused bytes must be set to
NUL.
Field termination is specified slightly differently by POSIX
than by previous implementations.
The
''magic'',
''uname'',
and
''gname''
fields must have a trailing
NUL.
The
''pathname'',
''linkname'',
and
''prefix''
fields must have a trailing
NUL
unless they fill the entire field.
(In particular, it is possible to store a 256-character pathname if it
happens to have a
''/''
as the 156th character.)
POSIX requires numeric fields to be zero-padded in the front, and requires
them to be terminated with either space or
NUL
characters.
Currently, most tar implementations comply with the ustar
format, occasionally extending it by adding new fields to the
blank area at the end of the header record.
=== Numeric Extensions===
There have been several attempts to extend the range of sizes
or times supported by modifying how numbers are stored in the
header.
One obvious extension to increase the size of files is to
eliminate the terminating characters from the various
numeric fields.
For example, the standard only allows the size field to contain
11 octal digits, reserving the twelfth byte for a trailing
NUL character.
Allowing 12 octal digits allows file sizes up to 64 GB.
Another extension, utilized by GNU tar, star, and other newer
'''tar'''
implementations, permits binary numbers in the standard numeric fields.
This is flagged by setting the high bit of the first byte.
The remainder of the field is treated as a signed twos-complement
value.
This permits 95-bit values for the length and time fields
and 63-bit values for the uid, gid, and device numbers.
In particular, this provides a consistent way to handle
negative time values.
GNU tar supports this extension for the
length, mtime, ctime, and atime fields.
Joerg Schilling's star program and the libarchive library support
this extension for all numeric fields.
Note that this extension is largely obsoleted by the extended
attribute record provided by the pax interchange format.
Another early GNU extension allowed base-64 values rather than octal.
This extension was short-lived and is no longer supported by any
implementation.
=== Pax Interchange Format===
There are many attributes that cannot be portably stored in a
POSIX ustar archive.
<nowiki>IEEE Std 1003.1-2001 (``POSIX.1'')</nowiki>
defined a
"pax interchange format"
that uses two new types of entries to hold text-formatted
metadata that applies to following entries.
Note that a pax interchange format archive is a ustar archive in every
respect.
The new data is stored in ustar-compatible archive entries that use the
"x"
or
"g"
typeflag.
In particular, older implementations that do not fully support these
extensions will extract the metadata into regular files, where the
metadata can be examined as necessary.
An entry in a pax interchange format archive consists of one or
two standard ustar entries, each with its own header and data.
The first optional entry stores the extended attributes
for the following entry.
This optional first entry has an "x" typeflag and a size field that
indicates the total size of the extended attributes.
The extended attributes themselves are stored as a series of text-format
lines encoded in the portable UTF-8 encoding.
Each line consists of a decimal number, a space, a key string, an equals
sign, a value string, and a new line.
The decimal number indicates the length of the entire line, including the
initial length field and the trailing newline.
An example of such a field is:
```text
25 ctime=1084839148.1212\n
```
Keys in all lowercase are standard keys.
Vendors can add their own keys by prefixing them with an all uppercase
vendor name and a period.
Note that, unlike the historic header, numeric values are stored using
decimal, not octal.
A description of some common keys follows:
<dl>
<dt>'''atime''', '''ctime''', '''mtime'''</dt><dd>
File access, inode change, and modification times.
These fields can be negative or include a decimal point and a fractional value.
</dd><dt>'''hdrcharset'''</dt><dd>
The character set used by the pax extension values.
By default, all textual values in the pax extended attributes
are assumed to be in UTF-8, including pathnames, user names,
and group names.
In some cases, it is not possible to translate local
conventions into UTF-8.
If this key is present and the value is the six-character ASCII string
"BINARY",
then all textual values are assumed to be in a platform-dependent
multi-byte encoding.
Note that there are only two valid values for this key:
"BINARY"
or
"ISO-IR\ 10646\ 2000\ UTF-8".
No other values are permitted by the standard, and
the latter value should generally not be used as it is the
default when this key is not specified.
In particular, this flag should not be used as a general
mechanism to allow filenames to be stored in arbitrary
encodings.
</dd><dt>'''uname''', '''uid''', '''gname''', '''gid'''</dt><dd>
User name, group name, and numeric UID and GID values.
The user name and group name stored here are encoded in UTF8
and can thus include non-ASCII characters.
The UID and GID fields can be of arbitrary length.
</dd><dt>'''linkpath'''</dt><dd>
The full path of the linked-to file.
Note that this is encoded in UTF8 and can thus include non-ASCII characters.
</dd><dt>'''path'''</dt><dd>
The full pathname of the entry.
Note that this is encoded in UTF8 and can thus include non-ASCII characters.
</dd><dt>'''realtime.*''', '''security.*'''</dt><dd>
These keys are reserved and may be used for future standardization.
</dd><dt>'''size'''</dt><dd>
The size of the file.
Note that there is no length limit on this field, allowing conforming
archives to store files much larger than the historic 8GB limit.
</dd><dt>'''SCHILY.*'''</dt><dd>
Vendor-specific attributes used by Joerg Schilling's
'''star'''
implementation.
</dd><dt>'''SCHILY.acl.access''', '''SCHILY.acl.default''', '''SCHILY.acl.ace'''</dt><dd>
Stores the access, default and NFSv4 ACLs as textual strings in a format
that is an extension of the format specified by POSIX.1e draft 17.
In particular, each user or group access specification can include
an additional colon-separated field with the numeric UID or GID.
This allows ACLs to be restored on systems that may not have complete
user or group information available (such as when NIS/YP or LDAP services
are temporarily unavailable).
</dd><dt>'''SCHILY.devminor''', '''SCHILY.devmajor'''</dt><dd>
The full minor and major numbers for device nodes.
</dd><dt>'''SCHILY.fflags'''</dt><dd>
The file flags.
</dd><dt>'''SCHILY.realsize'''</dt><dd>
The full size of the file on disk.
XXX explain? XXX
</dd><dt>'''SCHILY.dev''', '''SCHILY.ino''', '''SCHILY.nlinks'''</dt><dd>
The device number, inode number, and link count for the entry.
In particular, note that a pax interchange format archive using Joerg
Schilling's
'''SCHILY.*'''
extensions can store all of the data from
''struct'' stat.
</dd><dt>'''LIBARCHIVE.*'''</dt><dd>
Vendor-specific attributes used by the
'''libarchive'''
library and programs that use it.
</dd><dt>'''LIBARCHIVE.creationtime'''</dt><dd>
The time when the file was created.
(This should not be confused with the POSIX
"ctime"
attribute, which refers to the time when the file
metadata was last changed.)
</dd><dt>'''LIBARCHIVE.xattr'''.''namespace''.''key''</dt><dd>
Libarchive stores POSIX.1e-style extended attributes using
keys of this form.
The
''key''
value is URL-encoded:
All non-ASCII characters and the two special characters
"="
and
"%"
are encoded as
"%"
followed by two uppercase hexadecimal digits.
The value of this key is the extended attribute value
encoded in base 64.
XXX Detail the base-64 format here XXX
</dd><dt>'''VENDOR.*'''</dt><dd>
XXX document other vendor-specific extensions XXX
</dd></dl>
Any values stored in an extended attribute override the corresponding
values in the regular tar header.
Note that compliant readers should ignore the regular fields when they
are overridden.
This is important, as existing archivers are known to store non-compliant
values in the standard header fields in this situation.
There are no limits on length for any of these fields.
In particular, numeric fields can be arbitrarily large.
All text fields are encoded in UTF8.
Compliant writers should store only portable 7-bit ASCII characters in
the standard ustar header and use extended
attributes whenever a text value contains non-ASCII characters.
In addition to the
'''x'''
entry described above, the pax interchange format
also supports a
'''g'''
entry.
The
'''g'''
entry is identical in format, but specifies attributes that serve as
defaults for all subsequent archive entries.
The
'''g'''
entry is not widely used.
Besides the new
'''x'''
and
'''g'''
entries, the pax interchange format has a few other minor variations
from the earlier ustar format.
The most troubling one is that hardlinks are permitted to have
data following them.
This allows readers to restore any hardlink to a file without
having to rewind the archive to find an earlier entry.
However, it creates complications for robust readers, as it is no longer
clear whether or not they should ignore the size field for hardlink entries.
=== GNU Tar Archives===
The GNU tar program started with a pre-POSIX format similar to that
described earlier and has extended it using several different mechanisms:
It added new fields to the empty space in the header (some of which was later
used by POSIX for conflicting purposes);
it allowed the header to be continued over multiple records;
and it defined new entries that modify following entries
(similar in principle to the
'''x'''
entry described above, but each GNU special entry is single-purpose,
unlike the general-purpose
'''x'''
entry).
As a result, GNU tar archives are not POSIX compatible, although
more lenient POSIX-compliant readers can successfully extract most
GNU tar archives.
```text
struct header_gnu_tar {
char name[100];
char mode[8];
char uid[8];
char gid[8];
char size[12];
char mtime[12];
char checksum[8];
char typeflag[1];
char linkname[100];
char magic[6];
char version[2];
char uname[32];
char gname[32];
char devmajor[8];
char devminor[8];
char atime[12];
char ctime[12];
char offset[12];
char longnames[4];
char unused[1];
struct {
char offset[12];
char numbytes[12];
} sparse[4];
char isextended[1];
char realsize[12];
char pad[17];
};
```
<dl>
<dt>''typeflag''</dt><dd>
GNU tar uses the following special entry types, in addition to
those defined by POSIX:
<dl>
<dt>7</dt><dd>
GNU tar treats type "7" records identically to type "0" records,
except on one obscure RTOS where they are used to indicate the
pre-allocation of a contiguous file on disk.
</dd><dt>D</dt><dd>
This indicates a directory entry.
Unlike the POSIX-standard "5"
typeflag, the header is followed by data records listing the names
of files in this directory.
Each name is preceded by an ASCII "Y"
if the file is stored in this archive or "N" if the file is not
stored in this archive.
Each name is terminated with a null, and
an extra null marks the end of the name list.
The purpose of this
entry is to support incremental backups; a program restoring from
such an archive may wish to delete files on disk that did not exist
in the directory when the archive was made.
Note that the "D" typeflag specifically violates POSIX, which requires
that unrecognized typeflags be restored as normal files.
In this case, restoring the "D" entry as a file could interfere
with subsequent creation of the like-named directory.
</dd><dt>K</dt><dd>
The data for this entry is a long linkname for the following regular entry.
</dd><dt>L</dt><dd>
The data for this entry is a long pathname for the following regular entry.
</dd><dt>M</dt><dd>
This is a continuation of the last file on the previous volume.
GNU multi-volume archives guarantee that each volume begins with a valid
entry header.
To ensure this, a file may be split, with part stored at the end of one volume,
and part stored at the beginning of the next volume.
The "M" typeflag indicates that this entry continues an existing file.
Such entries can only occur as the first or second entry
in an archive (the latter only if the first entry is a volume label).
The
''size''
field specifies the size of this entry.
The
''offset''
field at bytes 369-380 specifies the offset where this file fragment
begins.
The
''realsize''
field specifies the total size of the file (which must equal
''size''
plus
''offset'').
When extracting, GNU tar checks that the header file name is the one it is
expecting, that the header offset is in the correct sequence, and that
the sum of offset and size is equal to realsize.
</dd><dt>N</dt><dd>
Type "N" records are no longer generated by GNU tar.
They contained a
list of files to be renamed or symlinked after extraction; this was
originally used to support long names.
The contents of this record
are a text description of the operations to be done, in the form
"Rename %s to %s\n"
or
"Symlink %s to %s\n ;"
in either case, both
filenames are escaped using K&R C syntax.
Due to security concerns, "N" records are now generally ignored
when reading archives.
</dd><dt>S</dt><dd>
This is a
"sparse"
regular file.
Sparse files are stored as a series of fragments.
The header contains a list of fragment offset/length pairs.
If more than four such entries are required, the header is
extended as necessary with
"extra"
header extensions (an older format that is no longer used), or
"sparse"
extensions.
</dd><dt>V</dt><dd>
The
''name''
field should be interpreted as a tape/volume header name.
This entry should generally be ignored on extraction.
</dd></dl>
</dd><dt>''magic''</dt><dd>
The magic field holds the five characters
"ustar"
followed by a space.
Note that POSIX ustar archives have a trailing null.
</dd><dt>''version''</dt><dd>
The version field holds a space character followed by a null.
Note that POSIX ustar archives use two copies of the ASCII digit
"0".
</dd><dt>''atime'', ''ctime''</dt><dd>
The time the file was last accessed and the time of
last change of file information, stored in octal as with
''mtime''.
</dd><dt>''longnames''</dt><dd>
This field is apparently no longer used.
</dd><dt>Sparse ''offset'' / ''numbytes''</dt><dd>
Each such structure specifies a single fragment of a sparse
file.
The two fields store values as octal numbers.
The fragments are each padded to a multiple of 512 bytes
in the archive.
On extraction, the list of fragments is collected from the
header (including any extension headers), and the data
is then read and written to the file at appropriate offsets.
</dd><dt>''isextended''</dt><dd>
If this is set to non-zero, the header will be followed by additional
"sparse header"
records.
Each such record contains information about as many as 21 additional
sparse blocks as shown here:
```text
struct gnu_sparse_header {
struct {
char offset[12];
char numbytes[12];
} sparse[21];
char isextended[1];
char padding[7];
};
```
</dd><dt>''realsize''</dt><dd>
A binary representation of the file's complete size, with a much larger range
than the POSIX file size.
In particular, with
'''M'''
type files, the current entry is only a portion of the file.
In that case, the POSIX size field will indicate the size of this
entry; the
''realsize''
field will indicate the total size of the file.
</dd></dl>
=== GNU tar pax archives===
GNU tar 1.14 (XXX check this XXX) and later will write
pax interchange format archives when you specify the
--posix
flag.
This format follows the pax interchange format closely,
using some
'''SCHILY'''
tags and introducing new keywords to store sparse file information.
There have been three iterations of the sparse file support, referred to
as
"0.0",
"0.1",
and
"1.0".
<dl>
<dt>'''GNU.sparse.numblocks''', '''GNU.sparse.offset''', '''GNU.sparse.numbytes''', '''GNU.sparse.size'''</dt><dd>
The
"0.0"
format used an initial
'''GNU.sparse.numblocks'''
attribute to indicate the number of blocks in the file, a pair of
'''GNU.sparse.offset'''
and
'''GNU.sparse.numbytes'''
to indicate the offset and size of each block,
and a single
'''GNU.sparse.size'''
to indicate the full size of the file.
This is not the same as the size in the tar header because the
latter value does not include the size of any holes.
This format required that the order of attributes be preserved and
relied on readers accepting multiple appearances of the same attribute
names, which is not officially permitted by the standards.
</dd><dt>'''GNU.sparse.map'''</dt><dd>
The
"0.1"
format used a single attribute that stored a comma-separated
list of decimal numbers.
Each pair of numbers indicated the offset and size, respectively,
of a block of data.
This does not work well if the archive is extracted by an archiver
that does not recognize this extension, since many pax implementations
simply discard unrecognized attributes.
</dd><dt>'''GNU.sparse.major''', '''GNU.sparse.minor''', '''GNU.sparse.name''', '''GNU.sparse.realsize'''</dt><dd>
The
"1.0"
format stores the sparse block map in one or more 512-byte blocks
prepended to the file data in the entry body.
The pax attributes indicate the existence of this map
(via the
'''GNU.sparse.major'''
and
'''GNU.sparse.minor'''
fields)
and the full size of the file.
The
'''GNU.sparse.name'''
holds the true name of the file.
To avoid confusion, the name stored in the regular tar header
is a modified name so that extraction errors will be apparent
to users.
</dd></dl>
=== Solaris Tar===
XXX More Details Needed XXX
Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an
"extended"
format that is fundamentally similar to pax interchange format,
with the following differences:
<ul>
<li>
Extended attributes are stored in an entry whose type is
'''X''',
not
'''x''',
as used by pax interchange format.
The detailed format of this entry appears to be the same
as detailed above for the
'''x'''
entry.
</li><li>
An additional
'''A'''
header is used to store an ACL for the following regular entry.
The body of this entry contains a seven-digit octal number
followed by a zero byte, followed by the
textual ACL description.
The octal value is the number of ACL entries
plus a constant that indicates the ACL type: 01000000
for POSIX.1e ACLs and 03000000 for NFSv4 ACLs.
</li></ul>
=== AIX Tar===
XXX More details needed XXX
AIX Tar uses a ustar-formatted header with the type
'''A'''
for storing coded ACL information.
Unlike the Solaris format, AIX tar writes this header after the
regular file body to which it applies.
The pathname in this header is either
'''NFS4'''
or
'''AIXC'''
to indicate the type of ACL stored.
The actual ACL is stored in platform-specific binary format.
=== Mac OS X Tar===
The tar distributed with Apple's Mac OS X stores most regular files
as two separate files in the tar archive.
The two files have the same name except that the first
one has
"._"
prepended to the last path element.
This special file stores an AppleDouble-encoded
binary blob with additional metadata about the second file,
including ACL, extended attributes, and resources.
To recreate the original file on disk, each
separate file can be extracted and the Mac OS X
'''copyfile'''()
function can be used to unpack the separate
metadata file and apply it to th regular file.
Conversely, the same function provides a
"pack"
option to encode the extended metadata from
a file into a separate file whose contents
can then be put into a tar archive.
Note that the Apple extended attributes interact
badly with long filenames.
Since each file is stored with the full name,
a separate set of extensions needs to be included
in the archive for each one, doubling the overhead
required for files with long names.
=== Summary of tar type codes===
The following list is a condensed summary of the type codes
used in tar header records generated by different tar implementations.
More details about specific implementations can be found above:
<dl>
<dt>NUL</dt><dd>
Early tar programs stored a zero byte for regular files.
</dd><dt>'''0'''</dt><dd>
POSIX standard type code for a regular file.
</dd><dt>'''1'''</dt><dd>
POSIX standard type code for a hard link description.
</dd><dt>'''2'''</dt><dd>
POSIX standard type code for a symbolic link description.
</dd><dt>'''3'''</dt><dd>
POSIX standard type code for a character device node.
</dd><dt>'''4'''</dt><dd>
POSIX standard type code for a block device node.
</dd><dt>'''5'''</dt><dd>
POSIX standard type code for a directory.
</dd><dt>'''6'''</dt><dd>
POSIX standard type code for a FIFO.
</dd><dt>'''7'''</dt><dd>
POSIX reserved.
</dd><dt>'''7'''</dt><dd>
GNU tar used for pre-allocated files on some systems.
</dd><dt>'''A'''</dt><dd>
Solaris tar ACL description stored prior to a regular file header.
</dd><dt>'''A'''</dt><dd>
AIX tar ACL description stored after the file body.
</dd><dt>'''D'''</dt><dd>
GNU tar directory dump.
</dd><dt>'''K'''</dt><dd>
GNU tar long linkname for the following header.
</dd><dt>'''L'''</dt><dd>
GNU tar long pathname for the following header.
</dd><dt>'''M'''</dt><dd>
GNU tar multivolume marker, indicating the file is a continuation of a file from the previous volume.
</dd><dt>'''N'''</dt><dd>
GNU tar long filename support.
Deprecated.
</dd><dt>'''S'''</dt><dd>
GNU tar sparse regular file.
</dd><dt>'''V'''</dt><dd>
GNU tar tape/volume header name.
</dd><dt>'''X'''</dt><dd>
Solaris tar general-purpose extension header.
</dd><dt>'''g'''</dt><dd>
POSIX pax interchange format global extensions.
</dd><dt>'''x'''</dt><dd>
POSIX pax interchange format per-file extensions.
</dd></dl>
== SEE ALSO ==
[[ar(1)|http://www.freebsd.org/cgi/man.cgi?query=ar&sektion=1]],
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]],
[[ManPageBsdtar1]]
== STANDARDS ==
The
'''tar'''
utility is no longer a part of POSIX or the Single Unix Standard.
It last appeared in
<nowiki>Version 2 of the Single UNIX Specification (``SUSv2'')</nowiki>.
It has been supplanted in subsequent standards by
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]].
The ustar format is currently part of the specification for the
[[pax(1)|http://www.freebsd.org/cgi/man.cgi?query=pax&sektion=1]]
utility.
The pax interchange file format is new with
<nowiki>IEEE Std 1003.1-2001 (``POSIX.1'')</nowiki>.
== HISTORY ==
A
'''tar'''
command appeared in Seventh Edition Unix, which was released in January, 1979.
It replaced the
'''tp'''
program from Fourth Edition Unix which in turn replaced the
'''tap'''
program from First Edition Unix.
John Gilmore's
'''pdtar'''
public-domain implementation (circa 1987) was highly influential
and formed the basis of
'''GNU''' tar
(circa 1988).
Joerg Shilling's
'''star'''
archiver is another open-source (CDDL) archiver (originally developed
circa 1985) which features complete support for pax interchange
format.
This documentation was written as part of the
'''libarchive'''
and
'''bsdtar'''
project by
Tim Kientzle &lt;kientzle@FreeBSD.org.&gt;