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/text/.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/text/Makefile vendored Normal file
View file

@ -0,0 +1,133 @@
default: all
archive_entry.3.txt: ../../libarchive/archive_entry.3
nroff -mdoc ../../libarchive/archive_entry.3 | col -b > archive_entry.3.txt
archive_entry_acl.3.txt: ../../libarchive/archive_entry_acl.3
nroff -mdoc ../../libarchive/archive_entry_acl.3 | col -b > archive_entry_acl.3.txt
archive_entry_linkify.3.txt: ../../libarchive/archive_entry_linkify.3
nroff -mdoc ../../libarchive/archive_entry_linkify.3 | col -b > archive_entry_linkify.3.txt
archive_entry_misc.3.txt: ../../libarchive/archive_entry_misc.3
nroff -mdoc ../../libarchive/archive_entry_misc.3 | col -b > archive_entry_misc.3.txt
archive_entry_paths.3.txt: ../../libarchive/archive_entry_paths.3
nroff -mdoc ../../libarchive/archive_entry_paths.3 | col -b > archive_entry_paths.3.txt
archive_entry_perms.3.txt: ../../libarchive/archive_entry_perms.3
nroff -mdoc ../../libarchive/archive_entry_perms.3 | col -b > archive_entry_perms.3.txt
archive_entry_stat.3.txt: ../../libarchive/archive_entry_stat.3
nroff -mdoc ../../libarchive/archive_entry_stat.3 | col -b > archive_entry_stat.3.txt
archive_entry_time.3.txt: ../../libarchive/archive_entry_time.3
nroff -mdoc ../../libarchive/archive_entry_time.3 | col -b > archive_entry_time.3.txt
archive_read.3.txt: ../../libarchive/archive_read.3
nroff -mdoc ../../libarchive/archive_read.3 | col -b > archive_read.3.txt
archive_read_add_passphrase.3.txt: ../../libarchive/archive_read_add_passphrase.3
nroff -mdoc ../../libarchive/archive_read_add_passphrase.3 | col -b > archive_read_add_passphrase.3.txt
archive_read_data.3.txt: ../../libarchive/archive_read_data.3
nroff -mdoc ../../libarchive/archive_read_data.3 | col -b > archive_read_data.3.txt
archive_read_disk.3.txt: ../../libarchive/archive_read_disk.3
nroff -mdoc ../../libarchive/archive_read_disk.3 | col -b > archive_read_disk.3.txt
archive_read_extract.3.txt: ../../libarchive/archive_read_extract.3
nroff -mdoc ../../libarchive/archive_read_extract.3 | col -b > archive_read_extract.3.txt
archive_read_filter.3.txt: ../../libarchive/archive_read_filter.3
nroff -mdoc ../../libarchive/archive_read_filter.3 | col -b > archive_read_filter.3.txt
archive_read_format.3.txt: ../../libarchive/archive_read_format.3
nroff -mdoc ../../libarchive/archive_read_format.3 | col -b > archive_read_format.3.txt
archive_read_free.3.txt: ../../libarchive/archive_read_free.3
nroff -mdoc ../../libarchive/archive_read_free.3 | col -b > archive_read_free.3.txt
archive_read_header.3.txt: ../../libarchive/archive_read_header.3
nroff -mdoc ../../libarchive/archive_read_header.3 | col -b > archive_read_header.3.txt
archive_read_new.3.txt: ../../libarchive/archive_read_new.3
nroff -mdoc ../../libarchive/archive_read_new.3 | col -b > archive_read_new.3.txt
archive_read_open.3.txt: ../../libarchive/archive_read_open.3
nroff -mdoc ../../libarchive/archive_read_open.3 | col -b > archive_read_open.3.txt
archive_read_set_options.3.txt: ../../libarchive/archive_read_set_options.3
nroff -mdoc ../../libarchive/archive_read_set_options.3 | col -b > archive_read_set_options.3.txt
archive_util.3.txt: ../../libarchive/archive_util.3
nroff -mdoc ../../libarchive/archive_util.3 | col -b > archive_util.3.txt
archive_write.3.txt: ../../libarchive/archive_write.3
nroff -mdoc ../../libarchive/archive_write.3 | col -b > archive_write.3.txt
archive_write_blocksize.3.txt: ../../libarchive/archive_write_blocksize.3
nroff -mdoc ../../libarchive/archive_write_blocksize.3 | col -b > archive_write_blocksize.3.txt
archive_write_data.3.txt: ../../libarchive/archive_write_data.3
nroff -mdoc ../../libarchive/archive_write_data.3 | col -b > archive_write_data.3.txt
archive_write_disk.3.txt: ../../libarchive/archive_write_disk.3
nroff -mdoc ../../libarchive/archive_write_disk.3 | col -b > archive_write_disk.3.txt
archive_write_filter.3.txt: ../../libarchive/archive_write_filter.3
nroff -mdoc ../../libarchive/archive_write_filter.3 | col -b > archive_write_filter.3.txt
archive_write_finish_entry.3.txt: ../../libarchive/archive_write_finish_entry.3
nroff -mdoc ../../libarchive/archive_write_finish_entry.3 | col -b > archive_write_finish_entry.3.txt
archive_write_format.3.txt: ../../libarchive/archive_write_format.3
nroff -mdoc ../../libarchive/archive_write_format.3 | col -b > archive_write_format.3.txt
archive_write_free.3.txt: ../../libarchive/archive_write_free.3
nroff -mdoc ../../libarchive/archive_write_free.3 | col -b > archive_write_free.3.txt
archive_write_header.3.txt: ../../libarchive/archive_write_header.3
nroff -mdoc ../../libarchive/archive_write_header.3 | col -b > archive_write_header.3.txt
archive_write_new.3.txt: ../../libarchive/archive_write_new.3
nroff -mdoc ../../libarchive/archive_write_new.3 | col -b > archive_write_new.3.txt
archive_write_open.3.txt: ../../libarchive/archive_write_open.3
nroff -mdoc ../../libarchive/archive_write_open.3 | col -b > archive_write_open.3.txt
archive_write_set_options.3.txt: ../../libarchive/archive_write_set_options.3
nroff -mdoc ../../libarchive/archive_write_set_options.3 | col -b > archive_write_set_options.3.txt
archive_write_set_passphrase.3.txt: ../../libarchive/archive_write_set_passphrase.3
nroff -mdoc ../../libarchive/archive_write_set_passphrase.3 | col -b > archive_write_set_passphrase.3.txt
cpio.5.txt: ../../libarchive/cpio.5
nroff -mdoc ../../libarchive/cpio.5 | col -b > cpio.5.txt
libarchive-formats.5.txt: ../../libarchive/libarchive-formats.5
nroff -mdoc ../../libarchive/libarchive-formats.5 | col -b > libarchive-formats.5.txt
libarchive.3.txt: ../../libarchive/libarchive.3
nroff -mdoc ../../libarchive/libarchive.3 | col -b > libarchive.3.txt
libarchive_changes.3.txt: ../../libarchive/libarchive_changes.3
nroff -mdoc ../../libarchive/libarchive_changes.3 | col -b > libarchive_changes.3.txt
libarchive_internals.3.txt: ../../libarchive/libarchive_internals.3
nroff -mdoc ../../libarchive/libarchive_internals.3 | col -b > libarchive_internals.3.txt
mtree.5.txt: ../../libarchive/mtree.5
nroff -mdoc ../../libarchive/mtree.5 | col -b > mtree.5.txt
tar.5.txt: ../../libarchive/tar.5
nroff -mdoc ../../libarchive/tar.5 | col -b > tar.5.txt
bsdtar.1.txt: ../../tar/bsdtar.1
nroff -mdoc ../../tar/bsdtar.1 | col -b > bsdtar.1.txt
bsdcpio.1.txt: ../../cpio/bsdcpio.1
nroff -mdoc ../../cpio/bsdcpio.1 | col -b > bsdcpio.1.txt
all: archive_entry.3.txt archive_entry_acl.3.txt archive_entry_linkify.3.txt archive_entry_misc.3.txt archive_entry_paths.3.txt archive_entry_perms.3.txt archive_entry_stat.3.txt archive_entry_time.3.txt archive_read.3.txt archive_read_add_passphrase.3.txt archive_read_data.3.txt archive_read_disk.3.txt archive_read_extract.3.txt archive_read_filter.3.txt archive_read_format.3.txt archive_read_free.3.txt archive_read_header.3.txt archive_read_new.3.txt archive_read_open.3.txt archive_read_set_options.3.txt archive_util.3.txt archive_write.3.txt archive_write_blocksize.3.txt archive_write_data.3.txt archive_write_disk.3.txt archive_write_filter.3.txt archive_write_finish_entry.3.txt archive_write_format.3.txt archive_write_free.3.txt archive_write_header.3.txt archive_write_new.3.txt archive_write_open.3.txt archive_write_set_options.3.txt archive_write_set_passphrase.3.txt cpio.5.txt libarchive-formats.5.txt libarchive.3.txt libarchive_changes.3.txt libarchive_internals.3.txt mtree.5.txt tar.5.txt bsdtar.1.txt bsdcpio.1.txt

92
dependencies/libarchive-3.4.2/doc/text/archive_entry.3.txt vendored Normal file
View file

@ -0,0 +1,92 @@
ARCHIVE_ENTRY(3) BSD Library Functions Manual ARCHIVE_ENTRY(3)
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
#include <archive_entry.h>
struct archive_entry *
archive_entry_clear(struct archive_entry *);
struct archive_entry *
archive_entry_clone(struct archive_entry *);
void
archive_entry_free(struct archive_entry *);
struct archive_entry *
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 libarchive(3) 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:
archive_entry_clear()
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.
archive_entry_clone()
A deep copy operation; all text fields are duplicated.
archive_entry_free()
Releases the struct archive_entry object.
archive_entry_new()
Allocate and return a blank struct archive_entry object.
Function groups
Due to high number of functions, the accessor functions can be found in
man pages grouped by the purpose.
archive_entry_acl(3) Access Control List manipulation
archive_entry_paths(3) Path name manipulation
archive_entry_perms(3) User, group and mode manipulation
archive_entry_stat(3) Functions not in the other groups and copying
to/from struct stat.
archive_entry_time(3) Time field manipulation
Most of the functions set or read entries in an object. Such functions
have one of the following forms:
archive_entry_set_XXXX()
Stores the provided data in the object. In particular, for
strings, the pointer is stored, not the referenced string.
archive_entry_copy_XXXX()
As above, except that the referenced data is copied into the
object.
archive_entry_XXXX()
Returns the specified data. In the case of strings, a const-
qualified pointer to the string is returned.
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 dis-
carded in favor of the new data.
SEE ALSO
archive_entry_acl(3), archive_entry_paths(3), archive_entry_perms(3),
archive_entry_time(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
BSD February 2, 2012 BSD

291
dependencies/libarchive-3.4.2/doc/text/archive_entry_acl.3.txt vendored Normal file
View file

@ -0,0 +1,291 @@
ARCHIVE_ENTRY_ACL(3) BSD Library Functions Manual ARCHIVE_ENTRY_ACL(3)
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
#include <archive_entry.h>
void
archive_entry_acl_add_entry(struct archive_entry *a, int type,
int permset, int tag, int qualifier, const char *name);
void
archive_entry_acl_add_entry_w(struct archive_entry *a, int type,
int permset, int tag, int qualifier, const wchar_t *name);
void
archive_entry_acl_clear(struct archive_entry *a);
int
archive_entry_acl_count(struct archive_entry *a, int type);
int
archive_entry_acl_from_text(struct archive_entry *a, const char *text,
int type);
int
archive_entry_acl_from_text_w(struct archive_entry *a,
const wchar_t *text, int type);
int
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);
int
archive_entry_acl_reset(struct archive_entry *a, int type);
char *
archive_entry_acl_to_text(struct archive_entry *a, ssize_t *len_p,
int flags);
wchar_t *
archive_entry_acl_to_text_w(struct archive_entry *a, ssize_t *len_p,
int flags);
int
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 permset are:
ARCHIVE_ENTRY_ACL_READ (r)
ARCHIVE_ENTRY_ACL_WRITE (w)
ARCHIVE_ENTRY_ACL_EXECUTE (x)
The permissions correspond to the normal Unix permissions.
The tag specifies the principal to which the permission applies. Valid
values are:
ARCHIVE_ENTRY_ACL_USER The user specified by the name field.
ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file.
ARCHIVE_ENTRY_ACL_GROUP The group specified by the name field.
ARCHIVE_ENTRY_ACL_GROUP_OBJ The group which owns the file.
ARCHIVE_ENTRY_ACL_MASK The maximum permissions to be obtained
via group permissions.
ARCHIVE_ENTRY_ACL_OTHER Any principal who is not the file
owner or a member of the owning group.
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 spec-
ifies the permissions required for access to the file itself. Directo-
ries have an additional ACL (ARCHIVE_ENTRY_ACL_TYPE_DEFAULT), which con-
trols 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:
ARCHIVE_ENTRY_ACL_TYPE_ALLOW Allow principal to perform actions
requiring given permissions.
ARCHIVE_ENTRY_ACL_TYPE_DENY Prevent principal from performing
actions requiring given permissions.
ARCHIVE_ENTRY_ACL_TYPE_AUDIT Log access attempts by principal which
require given permissions.
ARCHIVE_ENTRY_ACL_TYPE_ALARM Trigger a system alarm on access
attempts by principal which require
given permissions.
The tag specifies the principal to which the permission applies. Valid
values are:
ARCHIVE_ENTRY_ACL_USER The user specified by the name field.
ARCHIVE_ENTRY_ACL_USER_OBJ The owner of the file.
ARCHIVE_ENTRY_ACL_GROUP The group specified by the name field.
ARCHIVE_ENTRY_ACL_GROUP_OBJ The group which owns the file.
ARCHIVE_ENTRY_ACL_EVERYONE Any principal who is not the file
owner or a member of the owning group.
Entries with the ARCHIVE_ENTRY_ACL_USER or ARCHIVE_ENTRY_ACL_GROUP tag
store the user and group name in the name string and optionally the user
or group ID in the qualifier integer.
NFSv4 ACE permissions and flags are stored in the same permset 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:
ARCHIVE_ENTRY_ACL_READ_DATA (r)
Read data (file).
ARCHIVE_ENTRY_ACL_LIST_DIRECTORY (r)
List entries (directory).
ARCHIVE_ENTRY_ACL_WRITE_DATA (w)
Write data (file).
ARCHIVE_ENTRY_ACL_ADD_FILE (w)
Create files (directory).
ARCHIVE_ENTRY_ACL_EXECUTE (x)
Execute file or change into a directory.
ARCHIVE_ENTRY_ACL_APPEND_DATA (p)
Append data (file).
ARCHIVE_ENTRY_ACL_ADD_SUBDIRECTORY (p)
Create subdirectories (directory).
ARCHIVE_ENTRY_ACL_DELETE_CHILD (D)
Remove files and subdirectories inside a directory.
ARCHIVE_ENTRY_ACL_DELETE (d)
Remove file or directory.
ARCHIVE_ENTRY_ACL_READ_ATTRIBUTES (a)
Read file or directory attributes.
ARCHIVE_ENTRY_ACL_WRITE_ATTRIBUTES (A)
Write file or directory attributes.
ARCHIVE_ENTRY_ACL_READ_NAMED_ATTRS (R)
Read named file or directory attributes.
ARCHIVE_ENTRY_ACL_WRITE_NAMED_ATTRS (W)
Write named file or directory attributes.
ARCHIVE_ENTRY_ACL_READ_ACL (c)
Read file or directory ACL.
ARCHIVE_ENTRY_ACL_WRITE_ACL (C)
Write file or directory ACL.
ARCHIVE_ENTRY_ACL_WRITE_OWNER (o)
Change owner of a file or directory.
ARCHIVE_ENTRY_ACL_SYNCHRONIZE (s)
Use synchronous I/O.
The following NFSv4 ACL inheritance flags are supported:
ARCHIVE_ENTRY_ACL_ENTRY_FILE_INHERIT (f)
Inherit parent directory ACE to files.
ARCHIVE_ENTRY_ACL_ENTRY_DIRECTORY_INHERIT (d)
Inherit parent directory ACE to subdirectories.
ARCHIVE_ENTRY_ACL_ENTRY_INHERIT_ONLY (i)
Only inherit, do not apply the permission on the directory
itself.
ARCHIVE_ENTRY_ACL_ENTRY_NO_PROPAGATE_INHERIT (n)
Do not propagate inherit flags. Only first-level entries
inherit ACLs.
ARCHIVE_ENTRY_ACL_ENTRY_SUCCESSFUL_ACCESS (S)
Trigger alarm or audit on successful access.
ARCHIVE_ENTRY_ACL_ENTRY_FAILED_ACCESS (F)
Trigger alarm or audit on failed access.
ARCHIVE_ENTRY_ACL_ENTRY_INHERITED (I)
Mark that ACE was inherited.
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 enumera-
tion pointer.
archive_entry_acl_count() counts the ACL entries that have the given type
mask. type can be the bitwise-or of
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
for POSIX.1e ACLs and
ARCHIVE_ENTRY_ACL_TYPE_ALLOW
ARCHIVE_ENTRY_ACL_TYPE_DENY
ARCHIVE_ENTRY_ACL_TYPE_AUDIT
ARCHIVE_ENTRY_ACL_TYPE_ALARM
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 type
may take one of the following values:
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
ARCHIVE_ENTRY_ACL_TYPE_NFS4
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 type is
ARCHIVE_ENTRY_ACL_TYPE_NFS4. Invalid entries, non-parseable ACL entries
and entries beginning with the '#' 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 indi-
cated 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
archive_entry_mode(3) or set using chmod(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 sepa-
rated by newline. If the pointer len_p is not NULL, then the function
shall return the length of the string (not including the NULL terminator)
in the location pointed to by len_p. The flag argument is a bitwise-or.
The following flags are effective only on POSIX.1e ACL:
ARCHIVE_ENTRY_ACL_TYPE_ACCESS
Output access ACLs.
ARCHIVE_ENTRY_ACL_TYPE_DEFAULT
Output POSIX.1e default ACLs.
ARCHIVE_ENTRY_ACL_STYLE_MARK_DEFAULT
Prefix each default ACL entry with the word ``default:''.
ARCHIVE_ENTRY_ACL_STYLE_SOLARIS
The mask and other ACLs don not contain a double colon.
The following flags are effecive only on NFSv4 ACL:
ARCHIVE_ENTRY_ACL_STYLE_COMPACT
Do not output minus characters for unset permissions and
flags in NFSv4 ACL permission and flag fields.
The following flags are effective on both POSIX.1e and NFSv4 ACL:
ARCHIVE_ENTRY_ACL_STYLE_EXTRA_ID
Add an additional colon-separated field containing the user
or group id.
ARCHIVE_ENTRY_ACL_STYLE_SEPARATOR_COMMA
Separate ACL entries with comma instead of newline.
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 spec-
ified, 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 num-
ber 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
archive_entry(3), libarchive(3)
BSD February 15, 2017 BSD

113
dependencies/libarchive-3.4.2/doc/text/archive_entry_linkify.3.txt vendored Normal file
View file

@ -0,0 +1,113 @@
ARCHIVE_ENTRY_LINKIFY(3) BSD Library Functions Manual ARCHIVE_ENTRY_LINKIFY(3)
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
#include <archive_entry.h>
struct archive_entry_linkresolver *
archive_entry_linkresolver_new(void);
void
archive_entry_linkresolver_set_strategy(struct archive_entry_linkresolver *resolver,
int format);
void
archive_entry_linkresolver_free(struct archive_entry_linkresolver *resolver);
void
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:
1. Ignore hardlinks and store the body for each reference (old cpio,
zip).
2. Store the body the first time an inode is seen (ustar, pax).
3. Store the body the last time an inode is seen (new cpio).
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 refer-
ences 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 opti-
mal hardlink strategy for the given format. The format code can be
obtained from archive_format(3). 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:
1. For the simple archive formats *entry is left unmodified and *sparse
is set to NULL.
2. 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.
3. 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 arbi-
trary deferred entry and the entry itself is removed from the inter-
nal 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.
The general usage is therefore:
1. For each new archive entry, call archive_entry_linkify().
2. Keep in mind that the entries returned may have a size of 0 now.
3. If *entry is not NULL, archive it.
4. If *sparse is not NULL, archive it.
5. 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.
RETURN VALUES
archive_entry_linkresolver_new() returns NULL on malloc(3) failures.
SEE ALSO
archive_entry(3)
BSD February 2, 2012 BSD

36
dependencies/libarchive-3.4.2/doc/text/archive_entry_misc.3.txt vendored Normal file
View file

@ -0,0 +1,36 @@
ARCHIVE_ENTRY_MISC(3) BSD Library Functions Manual ARCHIVE_ENTRY_MISC(3)
NAME
archive_entry_symlink_type, archive_entry_set_symlink_type -- miscella-
neous functions for manipulating properties of archive_entry
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive_entry.h>
int
archive_entry_symlink_type(struct archive_entry *a);
void
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. Micro-
soft Windows).
Supported values are:
AE_SYMLINK_TYPE_UNDEFINED Symbolic link target type is not defined
(default on unix systems)
AE_SYMLINK_TYPE_FILE Symbolic link points to a file
AE_SYMLINK_TYPE_DIRECTORY Symbolic link points to a directory
SEE ALSO
archive_entry(3), archive_entry_paths(3), archive_entry_stat(3),
libarchive(3)
BSD April 15, 2019 BSD

136
dependencies/libarchive-3.4.2/doc/text/archive_entry_paths.3.txt vendored Normal file
View file

@ -0,0 +1,136 @@
ARCHIVE_ENTRY_PATHS(3) BSD Library Functions Manual ARCHIVE_ENTRY_PATHS(3)
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 -- func-
tions for manipulating path names in archive entry descriptions
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive_entry.h>
const char *
archive_entry_hardlink(struct archive_entry *a);
const wchar_t *
archive_entry_hardlink_w(struct archive_entry *a);
void
archive_entry_set_hardlink(struct archive_entry *a, const char *path);
void
archive_entry_copy_hardlink(struct archive_entry *a, const char *path);
void
archive_entry_copy_hardlink_w(struct archive_entry *a, const, wchar_t,
*path");
int
archive_entry_update_hardlink_utf8(struct archive_entry *a,
const char *path);
void
archive_entry_set_link(struct archive_entry *a, const char *path);
void
archive_entry_copy_link(struct archive_entry *a, const char *path);
void
archive_entry_copy_link_w(struct archive_entry *a, const wchar_t *path);
int
archive_entry_update_link_utf8(struct archive_entry *a,
const char *path);
const char *
archive_entry_pathname(struct archive_entry *a);
const wchar_t *
archive_entry_pathname_w(struct archive_entry *a);
void
archive_entry_set_pathname(struct archive_entry *a, const char *path);
void
archive_entry_copy_pathname(struct archive_entry *a, const char *path);
void
archive_entry_copy_pathname_w(struct archive_entry *a,
const wchar_t *path);
int
archive_entry_update_pathname_utf8(struct archive_entry *a,
const char *path);
const char *
archive_entry_sourcepath(struct archive_entry *a);
void
archive_entry_copy_sourcepath(struct archive_entry *a, const char *path);
const char *
archive_entry_symlink(struct archive_entry *a);
const wchar_t *
archive_entry_symlink_w(struct archive_entry *a);
void
archive_entry_set_symlink(struct archive_entry *a, const char *path);
void
archive_entry_copy_symlink(struct archive_entry *a, const char *path);
void
archive_entry_copy_symlink_w(struct archive_entry *a,
const wchar_t *path);
int
archive_entry_update_symlink_utf8(struct archive_entry *a,
const char *path);
DESCRIPTION
Path names supported by archive_entry(3):
hardlink Destination of the hardlink.
link Update only. For a symlink, update the destination. Other-
wise, make the entry a hardlink and alter the destination for
that.
pathname Path in the archive
sourcepath Path on the disk for use by archive_read_disk(3).
symlink Destination of the symbolic link.
Path names can be provided in one of three different ways:
char * Multibyte strings in the current locale.
wchar_t * Wide character strings in the current locale. The accessor
functions are named XXX_w().
UTF-8 Unicode strings encoded as UTF-8. These are convenience func-
tions to update both the multibyte and wide character strings
at the same time.
The sourcepath is a pure filesystem concept and never stored in an ar-
chive 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
archive_entry(3), libarchive(3)
BSD February 2, 2012 BSD

169
dependencies/libarchive-3.4.2/doc/text/archive_entry_perms.3.txt vendored Normal file
View file

@ -0,0 +1,169 @@
ARCHIVE_ENTRY_PERMS(3) BSD Library Functions Manual ARCHIVE_ENTRY_PERMS(3)
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 -- func-
tions for manipulating ownership and permissions in archive entry
descriptions
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive_entry.h>
gid_t
archive_entry_gid(struct archive_entry *a);
void
archive_entry_set_gid(struct archive_entry *a, gid_t gid);
uid_t
archive_entry_uid(struct archive_entry *a);
void
archive_entry_set_uid(struct archive_entry *a, uid_t uid);
mode_t
archive_entry_perm(struct archive_entry *a);
void
archive_entry_set_perm(struct archive_entry *a, mode_t mode);
const char *
archive_entry_strmode(struct archive_entry *a);
const char *
archive_entry_gname(struct archive_entry *a);
const wchar_t *
archive_entry_gname_w(struct archive_entry *a);
void
archive_entry_set_gname(struct archive_entry *a, const char *a);
void
archive_entry_copy_gname(struct archive_entry *a, const char *name);
void
archive_entry_copy_gname_w(struct archive_entry *a, const wchar_t *name);
int
archive_entry_update_gname_utf8(struct archive_entry *a,
const char *name);
const char *
archive_entry_uname(struct archive_entry *a);
const wchar_t *
archive_entry_uname_w(struct archive_entry *a);
void
archive_entry_set_uname(struct archive_entry *a, const char *name);
void
archive_entry_copy_uname(struct archive_entry *a, const char *name);
void
archive_entry_copy_uname_w(struct archive_entry *a, const wchar_t *name);
int
archive_entry_update_uname_utf8(struct archive_entry *a,
const char *name);
void
archive_entry_fflags(struct archive_entry *a, unsigned long *set_bits,
unsigned long *clear_bits);
const char *
archive_entry_fflags_text(struct archive_entry *a);
void
archive_entry_set_fflags(struct archive_entry *a, unsigned long set_bits,
unsigned long clear_bits);
const char *
archive_entry_copy_fflags_text(struct archive_entry *a,
const char *text);
const wchar_t *
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).
User and group name
User and group names can be provided in one of three different ways:
char * Multibyte strings in the current locale.
wchar_t * Wide character strings in the current locale. The accessor
functions are named XXX_w().
UTF-8 Unicode strings encoded as UTF-8. These are convenience func-
tions to update both the multibyte and wide character strings
at the same time.
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 recon-
structed 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), 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 -- including names that follow
an unrecognized name -- will be evaluated, and the bitmaps will be set to
reflect every name that is recognized. (In particular, this differs from
strtofflags(3), which stops parsing at the first unrecognized name.)
SEE ALSO
archive_entry(3), archive_entry_acl(3), archive_read_disk(3),
archive_write_disk(3), libarchive(3)
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 ar-
chives and get truncated.
BSD February 2, 2012 BSD

190
dependencies/libarchive-3.4.2/doc/text/archive_entry_stat.3.txt vendored Normal file
View file

@ -0,0 +1,190 @@
ARCHIVE_ENTRY_STAT(3) BSD Library Functions Manual ARCHIVE_ENTRY_STAT(3)
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 func-
tions for manipulating archive entry descriptions
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive_entry.h>
const struct stat *
archive_entry_stat(struct archive_entry *a);
void
archive_entry_copy_stat(struct archive_entry *a, const struct stat *sb);
mode_t
archive_entry_filetype(struct archive_entry *a);
void
archive_entry_set_filetype(struct archive_entry *a, unsigned int type);
mode_t
archive_entry_mode(struct archive_entry *a);
void
archive_entry_set_mode(struct archive_entry *a, mode_t mode);
int64_t
archive_entry_size(struct archive_entry *a);
int
archive_entry_size_is_set(struct archive_entry *a);
void
archive_entry_set_size(struct archive_entry *a, int64_t size);
void
archive_entry_unset_size(struct archive_entry *a);
dev_t
archive_entry_dev(struct archive_entry *a);
void
archive_entry_set_dev(struct archive_entry *a, dev_t dev);
int
archive_entry_dev_is_set(struct archive_entry *a);
dev_t
archive_entry_devmajor(struct archive_entry *a);
void
archive_entry_set_devmajor(struct archive_entry *a, dev_t major);
dev_t
archive_entry_devminor(struct archive_entry *a);
void
archive_entry_set_devminor(struct archive_entry *a, dev_t minor);
ino_t
archive_entry_ino(struct archive_entry *a);
void
archive_entry_set_ino(struct archive_entry *a, unsigned long ino);
int
archive_entry_ino_is_set(struct archive_entry *a);
int64_t
archive_entry_ino64(struct archive_entry *a);
void
archive_entry_set_ino64(struct archive_entry *a, int64_t ino);
unsigned int
archive_entry_nlink(struct archive_entry *a);
void
archive_entry_set_nlink(struct archive_entry *a, unsigned int count);
dev_t
archive_entry_rdev(struct archive_entry *a);
dev_t
archive_entry_rdevmajor(struct archive_entry *a);
dev_t
archive_entry_rdevminor(struct archive_entry *a);
void
archive_entry_set_rdev(struct archive_entry *a, dev_t dev);
void
archive_entry_set_rdevmajor(struct archive_entry *a, dev_t major);
void
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). 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 informa-
tion 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:
AE_IFREG Regular file
AE_IFLNK Symbolic link
AE_IFSOCK Socket
AE_IFCHR Character device
AE_IFBLK Block device
AE_IFDIR Directory
AE_IFIFO Named pipe (fifo)
Not all file types are supported by all platforms. The constants used by
stat(2) may have different numeric values from the corresponding con-
stants 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
archive_entry_linkify(3) 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 num-
ber 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), archive_entry_acl(3), archive_entry_perms(3),
archive_entry_time(3), libarchive(3)
BSD February 2, 2012 BSD

110
dependencies/libarchive-3.4.2/doc/text/archive_entry_time.3.txt vendored Normal file
View file

@ -0,0 +1,110 @@
ARCHIVE_ENTRY_TIME(3) BSD Library Functions Manual ARCHIVE_ENTRY_TIME(3)
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
#include <archive_entry.h>
time_t
archive_entry_atime(struct archive_entry *a);
long
archive_entry_atime_nsec(struct archive_entry *a);
int
archive_entry_atime_is_set(struct archive_entry *a);
void
archive_entry_set_atime(struct archive_entry *a, time_t sec,
long nanosec);
void
archive_entry_unset_atime(struct archive_entry *a);
time_t
archive_entry_birthtime(struct archive_entry *a);
long
archive_entry_birthtime_nsec(struct archive_entry *a);
int
archive_entry_birthtime_is_set(struct archive_entry *a);
void
archive_entry_set_birthtime(struct archive_entry *a, time_t sec,
long nanosec);
void
archive_entry_unset_birthtime(struct archive_entry *a);
time_t
archive_entry_ctime(struct archive_entry *a);
long
archive_entry_ctime_nsec(struct archive_entry *a);
int
archive_entry_ctime_is_set(struct archive_entry *a);
void
archive_entry_set_ctime(struct archive_entry *a, time_t sec,
long nanosec);
void
archive_entry_unset_ctime(struct archive_entry *a);
time_t
archive_entry_mtime(struct archive_entry *a);
long
archive_entry_mtime_nsec(struct archive_entry *a);
int
archive_entry_mtime_is_set(struct archive_entry *a);
void
archive_entry_set_mtime(struct archive_entry *a, time_t sec,
long nanosec);
void
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).
libarchive(3) 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 nanosec-
ond field of 0.
SEE ALSO
archive_entry(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
BSD February 2, 2012 BSD

156
dependencies/libarchive-3.4.2/doc/text/archive_read.3.txt vendored Normal file
View file

@ -0,0 +1,156 @@
ARCHIVE_READ(3) BSD Library Functions Manual ARCHIVE_READ(3)
NAME
archive_read -- functions for reading streaming archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
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 archive_read_new(3).
To read an archive, you must first obtain an initialized struct archive
object from archive_read_new().
Enable filters and formats
See archive_read_filter(3) and archive_read_format(3).
You can then modify this object for the desired operations with the vari-
ous 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 compres-
sion 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 archive_read_set_options(3).
Open archive
See archive_read_open(3).
Once you have prepared the struct archive object, you call
archive_read_open() to actually open the archive and prepare it for read-
ing. 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 archive_read_header(3), archive_read_data(3) and
archive_read_extract(3).
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 infor-
mation 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) system call) to
read this data from the archive, or archive_read_data_block() which pro-
vides 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 archive_read_free(3).
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),
read(2), and close(2) system calls.
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\n",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
tar(1), archive_read_data(3), archive_read_extract(3),
archive_read_filter(3), archive_read_format(3), archive_read_header(3),
archive_read_new(3), archive_read_open(3), archive_read_set_options(3),
archive_util(3), libarchive(3), tar(5)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
BUGS
Many traditional archiver programs treat empty files as valid empty ar-
chives. For example, many implementations of tar(1) allow you to append
entries to an empty file. Of course, it is impossible to determine the
format of an empty file by inspecting the contents, so this library
treats empty files as having a special ``empty'' format.
BSD February 2, 2012 BSD

35
dependencies/libarchive-3.4.2/doc/text/archive_read_add_passphrase.3.txt vendored Normal file
View file

@ -0,0 +1,35 @@
ARCHIVE_READ_ADD_PASS... BSD Library Functions Manual ARCHIVE_READ_ADD_PASS...
NAME
archive_read_add_passphrase, archive_read_set_passphrase_callback --
functions for reading encrypted archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
archive_read_add_passphrase(struct archive *, const char *passphrase);
int
archive_read_set_passphrase_callback(struct archive *, void *client_data,
archive_passphrase_callback *);
DESCRIPTION
archive_read_add_passphrase()
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.
archive_read_set_passphrase_callback()
Register a callback function that will be invoked to get a
passphrase for decryption after trying all the passphrases regis-
tered by the archive_read_add_passphrase() function failed.
SEE ALSO
tar(1), archive_read(3), archive_read_set_options(3), libarchive(3)
BSD September 14, 2014 BSD

73
dependencies/libarchive-3.4.2/doc/text/archive_read_data.3.txt vendored Normal file
View file

@ -0,0 +1,73 @@
ARCHIVE_READ_DATA(3) BSD Library Functions Manual ARCHIVE_READ_DATA(3)
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
#include <archive.h>
la_ssize_t
archive_read_data(struct archive *, void *buff, size_t len);
int
archive_read_data_block(struct archive *, const void **buff, size_t *len,
off_t *offset);
int
archive_read_data_skip(struct archive *);
int
archive_read_data_into_fd(struct archive *, int fd);
DESCRIPTION
archive_read_data()
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 con-
tinuous stream of data.
archive_read_data_block()
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 guaran-
tees 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.
archive_read_data_skip()
A convenience function that repeatedly calls
archive_read_data_block() to skip all of the data for this ar-
chive entry. Note that this function is invoked automatically by
archive_read_next_header2() if the previous entry was not com-
pletely consumed.
archive_read_data_into_fd()
A convenience function that repeatedly calls
archive_read_data_block() to copy the entire entry to the pro-
vided file descriptor.
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 opera-
tion 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
tar(1), archive_read(3), archive_read_extract(3), archive_read_filter(3),
archive_read_format(3), archive_read_header(3), archive_read_open(3),
archive_read_set_options(3), archive_util(3), libarchive(3), tar(5)
BSD February 2, 2012 BSD

233
dependencies/libarchive-3.4.2/doc/text/archive_read_disk.3.txt vendored Normal file
View file

@ -0,0 +1,233 @@
ARCHIVE_READ_DISK(3) BSD Library Functions Manual ARCHIVE_READ_DISK(3)
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
#include <archive.h>
struct archive *
archive_read_disk_new(void);
int
archive_read_disk_set_behavior(struct archive *, int);
int
archive_read_disk_set_symlink_logical(struct archive *);
int
archive_read_disk_set_symlink_physical(struct archive *);
int
archive_read_disk_set_symlink_hybrid(struct archive *);
const char *
archive_read_disk_gname(struct archive *, gid_t);
const char *
archive_read_disk_uname(struct archive *, uid_t);
int
archive_read_disk_set_gname_lookup(struct archive *, void *,
const char *(*lookup)(void *, gid_t), void (*cleanup)(void *));
int
archive_read_disk_set_uname_lookup(struct archive *, void *,
const char *(*lookup)(void *, uid_t), void (*cleanup)(void *));
int
archive_read_disk_set_standard_lookup(struct archive *);
int
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.
archive_read_disk_new()
Allocates and initializes a struct archive object suitable for
reading object information from disk.
archive_read_disk_set_behavior()
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:
ARCHIVE_READDISK_HONOR_NODUMP
Skip files and directories with the nodump file attribute
(file flag) set. By default, the nodump file attribute
is ignored.
ARCHIVE_READDISK_MAC_COPYFILE
Mac OS X specific. Read metadata (ACLs and extended
attributes) with copyfile(3). By default, metadata is
read using copyfile(3).
ARCHIVE_READDISK_NO_ACL
Do not read Access Control Lists. By default, ACLs are
read from disk.
ARCHIVE_READDISK_NO_FFLAGS
Do not read file attributes (file flags). By default,
file attributes are read from disk. See chattr(1)
(Linux) or chflags(1) (FreeBSD, Mac OS X) for more infor-
mation on file attributes.
ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
Do not traverse mount points. By default, mount points
are traversed.
ARCHIVE_READDISK_NO_XATTR
Do not read extended file attributes (xattrs). By
default, extended file attributes are read from disk.
See xattr(7) (Linux), xattr(2) (Mac OS X), or
getextattr(8) (FreeBSD) for more information on extended
file attributes.
ARCHIVE_READDISK_RESTORE_ATIME
Restore access time of traversed files. By default,
access time of traversed files is not restored.
archive_read_disk_set_symlink_logical(),
archive_read_disk_set_symlink_physical(),
archive_read_disk_set_symlink_hybrid()
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.
archive_read_disk_gname(), archive_read_disk_uname()
Returns a user or group name given a gid or uid value. By
default, these always return a NULL string.
archive_read_disk_set_gname_lookup(),
archive_read_disk_set_uname_lookup()
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.
archive_read_disk_set_standard_lookup()
This convenience function installs a standard set of user and
group name lookup functions. These functions use getpwuid(3) and
getgrgid(3) to convert ids to names, defaulting to NULL if the
names cannot be looked up. These functions also implement a sim-
ple memory cache to reduce the number of calls to getpwuid(3) and
getgrgid(3).
archive_read_disk_entry_from_file()
Populates a struct archive_entry object with information about a
particular file. The archive_entry object must have already been
created with archive_entry_new(3) 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 plat-
forms 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, direc-
tory 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.
More information about the struct archive object and the overall design
of the library can be found in the libarchive(3) 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.
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 impossi-
ble.
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 rea-
son. 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
tar(1), archive_read(3), archive_util(3), archive_write(3),
archive_write_disk(3), libarchive(3)
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
<kientzle@FreeBSD.org>.
BUGS
The ``standard'' user name and group name lookup functions are not the
defaults because getgrgid(3) and getpwuid(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 informa-
tion 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 archive_read(3) API. When
such methods are implemented, the ``hybrid'' symbolic link mode will make
sense.
BSD April 3, 2017 BSD

74
dependencies/libarchive-3.4.2/doc/text/archive_read_extract.3.txt vendored Normal file
View file

@ -0,0 +1,74 @@
ARCHIVE_READ_EXTRACT(3) BSD Library Functions Manual ARCHIVE_READ_EXTRACT(3)
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
#include <archive.h>
int
archive_read_extract(struct archive *, struct archive_entry *,
int flags);
int
archive_read_extract2(struct archive *src, struct archive_entry *,
struct archive *dest);
void
archive_read_extract_set_progress_callback(struct archive *,
void (*func)(void *), void *user_data);
DESCRIPTION
archive_read_extract(), archive_read_extract_set_skip_file()
A convenience function that wraps the corresponding
archive_write_disk(3) interfaces. The first call to
archive_read_extract() creates a restore object using
archive_write_disk_new(3) and
archive_write_disk_set_standard_lookup(3), then transparently
invokes archive_write_disk_set_options(3),
archive_write_header(3), archive_write_data(3), and
archive_write_finish_entry(3) to create the entry on disk and
copy data into it. The flags argument is passed unmodified to
archive_write_disk_set_options(3).
archive_read_extract2()
This is another version of archive_read_extract() that allows you
to provide your own restore object. In particular, this allows
you to override the standard lookup functions using
archive_write_disk_set_group_lookup(3), and
archive_write_disk_set_user_lookup(3). Note that
archive_read_extract2() does not accept a flags argument; you
should use archive_write_disk_set_options() to set the restore
options yourself.
archive_read_extract_set_progress_callback()
Sets a pointer to a user-defined callback that can be used for
updating progress displays during extraction. The progress func-
tion 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.
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 opera-
tion 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
tar(1), archive_read(3), archive_read_data(3), archive_read_filter(3),
archive_read_format(3), archive_read_open(3),
archive_read_set_options(3), archive_util(3), libarchive(3), tar(5)
BSD February 2, 2012 BSD

115
dependencies/libarchive-3.4.2/doc/text/archive_read_filter.3.txt vendored Normal file
View file

@ -0,0 +1,115 @@
ARCHIVE_READ_FILTER(3) BSD Library Functions Manual ARCHIVE_READ_FILTER(3)
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
#include <archive.h>
int
archive_read_support_filter_all(struct archive *);
int
archive_read_support_filter_bzip2(struct archive *);
int
archive_read_support_filter_compress(struct archive *);
int
archive_read_support_filter_grzip(struct archive *);
int
archive_read_support_filter_gzip(struct archive *);
int
archive_read_support_filter_lrzip(struct archive *);
int
archive_read_support_filter_lz4(struct archive *);
int
archive_read_support_filter_lzma(struct archive *);
int
archive_read_support_filter_lzop(struct archive *);
int
archive_read_support_filter_none(struct archive *);
int
archive_read_support_filter_rpm(struct archive *);
int
archive_read_support_filter_uu(struct archive *);
int
archive_read_support_filter_xz(struct archive *);
int
archive_read_support_filter_zstd(struct archive *);
int
archive_read_support_filter_program(struct archive *, const char *cmd);
int
archive_read_support_filter_program_signature(struct archive *,
const char *cmd, const void *signature, size_t signature_length);
DESCRIPTION
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(),
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.
archive_read_support_filter_all()
Enables all available decompression filters.
archive_read_support_filter_program()
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 con-
junction with any other decompression option.
archive_read_support_filter_program_signature()
This feeds data through the specified external program but only
if the initial bytes of the data match the specified signature
value.
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
archive_read(3), archive_read_data(3), archive_read_format(3),
archive_read_format(3), libarchive(3)
BSD August 14, 2014 BSD

129
dependencies/libarchive-3.4.2/doc/text/archive_read_format.3.txt vendored Normal file
View file

@ -0,0 +1,129 @@
ARCHIVE_READ_FORMAT(3) BSD Library Functions Manual ARCHIVE_READ_FORMAT(3)
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 ar-
chives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
archive_read_support_format_7zip(struct archive *);
int
archive_read_support_format_all(struct archive *);
int
archive_read_support_format_ar(struct archive *);
int
archive_read_support_format_by_code(struct archive *, int);
int
archive_read_support_format_cab(struct archive *);
int
archive_read_support_format_cpio(struct archive *);
int
archive_read_support_format_empty(struct archive *);
int
archive_read_support_format_iso9660(struct archive *);
int
archive_read_support_format_lha(struct archive *);
int
archive_read_support_format_mtree(struct archive *);
int
archive_read_support_format_rar(struct archive *);
int
archive_read_support_format_raw(struct archive *);
int
archive_read_support_format_tar(struct archive *);
int
archive_read_support_format_xar(struct archive *);
int
archive_read_support_format_zip(struct archive *);
DESCRIPTION
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()
Enables support---including auto-detection code---for the speci-
fied 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.
archive_read_support_format_all()
Enables support for all available formats except the ``raw'' for-
mat (see below).
archive_read_support_format_by_code()
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 executa-
bles, 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.
archive_read_support_format_empty()
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.
archive_read_support_format_raw()
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.
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
tar(1), archive_read_data(3), archive_read_filter(3),
archive_read_set_options(3), archive_util(3), libarchive(3), tar(5)
BUGS
Many traditional archiver programs treat empty files as valid empty ar-
chives. For example, many implementations of tar(1) allow you to append
entries to an empty file. Of course, it is impossible to determine the
format of an empty file by inspecting the contents, so this library
treats empty files as having a special ``empty'' format.
Using the ``raw'' handler together with any other handler will often work
but can produce surprising results.
BSD February 2, 2012 BSD

52
dependencies/libarchive-3.4.2/doc/text/archive_read_free.3.txt vendored Normal file
View file

@ -0,0 +1,52 @@
ARCHIVE_READ_FREE(3) BSD Library Functions Manual ARCHIVE_READ_FREE(3)
NAME
archive_read_close, archive_read_finish, archive_read_free -- functions
for reading streaming archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
archive_read_close(struct archive *);
int
archive_read_finish(struct archive *);
int
archive_read_free(struct archive *);
DESCRIPTION
archive_read_close()
Complete the archive and invoke the close callback.
archive_read_finish()
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 con-
tinue 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.
archive_read_free()
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.
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
archive_read_data(3), archive_read_filter(3), archive_read_format(3),
archive_read_new(3), archive_read_open(3), archive_read_set_options(3),
archive_util(3), libarchive(3)
BSD February 2, 2012 BSD

45
dependencies/libarchive-3.4.2/doc/text/archive_read_header.3.txt vendored Normal file
View file

@ -0,0 +1,45 @@
ARCHIVE_READ_HEADER(3) BSD Library Functions Manual ARCHIVE_READ_HEADER(3)
NAME
archive_read_next_header, archive_read_next_header2 -- functions for
reading streaming archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
archive_read_next_header(struct archive *, struct archive_entry **);
int
archive_read_next_header2(struct archive *, struct archive_entry *);
DESCRIPTION
archive_read_next_header()
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.
archive_read_next_header2()
Read the header for the next entry and populate the provided
struct archive_entry.
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 opera-
tion 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
tar(1), archive_read(3), archive_read_data(3), archive_read_extract(3),
archive_read_filter(3), archive_read_format(3), archive_read_open(3),
archive_read_set_options(3), archive_util(3), libarchive(3), tar(5)
BSD February 2, 2012 BSD

27
dependencies/libarchive-3.4.2/doc/text/archive_read_new.3.txt vendored Normal file
View file

@ -0,0 +1,27 @@
ARCHIVE_READ_NEW(3) BSD Library Functions Manual ARCHIVE_READ_NEW(3)
NAME
archive_read_new -- functions for reading streaming archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
struct archive *
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 libarchive(3).
SEE ALSO
tar(1), archive_read_data(3), archive_read_filter(3),
archive_read_format(3), archive_read_set_options(3), archive_util(3),
libarchive(3), tar(5)
BSD February 2, 2012 BSD

130
dependencies/libarchive-3.4.2/doc/text/archive_read_open.3.txt vendored Normal file
View file

@ -0,0 +1,130 @@
ARCHIVE_READ_OPEN(3) BSD Library Functions Manual ARCHIVE_READ_OPEN(3)
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
#include <archive.h>
int
archive_read_open(struct archive *, void *client_data,
archive_open_callback *, archive_read_callback *,
archive_close_callback *);
int
archive_read_open2(struct archive *, void *client_data,
archive_open_callback *, archive_read_callback *,
archive_skip_callback *, archive_close_callback *);
int
archive_read_open_FILE(struct archive *, FILE *file);
int
archive_read_open_fd(struct archive *, int fd, size_t block_size);
int
archive_read_open_filename(struct archive *, const char *filename,
size_t block_size);
int
archive_read_open_memory(struct archive *, const void *buff,
size_t size);
DESCRIPTION
archive_read_open()
The same as archive_read_open2(), except that the skip callback
is assumed to be NULL.
archive_read_open2()
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.
archive_read_open_FILE()
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.
archive_read_open_fd()
Like archive_read_open(), except that it accepts a file descrip-
tor 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.
archive_read_open_file()
This is a deprecated synonym for archive_read_open_filename().
archive_read_open_filename()
Like archive_read_open(), except that it accepts a simple file-
name and a block size. A NULL filename represents standard
input. This function is safe for use with tape drives or other
blocked devices.
archive_read_open_memory()
Like archive_read_open(), except that it accepts a pointer and
size of a block of memory containing the archive data.
A complete description of the struct archive and struct archive_entry
objects can be found in the overview manual page for libarchive(3).
CLIENT CALLBACKS
The callback functions must match the following prototypes:
typedef la_ssize_t archive_read_callback(struct archive *,
void *client_data, const void **buffer)
typedef la_int64_t archive_skip_callback(struct archive *,
void *client_data, off_t request)
typedef int archive_open_callback(struct archive *, void
*client_data)
typedef int archive_close_callback(struct archive *, void
*client_data)
The open callback is invoked by archive_open(). It should return
ARCHIVE_OK if the underlying file or data source is successfully opened.
If the open fails, it should call archive_set_error() to register an
error code and message and return ARCHIVE_FATAL.
The read callback is invoked whenever the library requires raw bytes from
the archive. The read callback should read data into a buffer, set the
const void **buffer argument to point to the available data, and return a
count of the number of bytes available. The library will invoke the read
callback again only after it has consumed this data. The library imposes
no constraints on the size of the data blocks returned. On end-of-file,
the read callback should return zero. On error, the read callback should
invoke archive_set_error() to register an error code and message and
return -1.
The skip callback is invoked when the library wants to ignore a block of
data. The return value is the number of bytes actually skipped, which
may differ from the request. If the callback cannot skip data, it should
return zero. If the skip callback is not provided (the function pointer
is NULL ), the library will invoke the read function instead and simply
discard the result. A skip callback can provide significant performance
gains when reading uncompressed archives from slow disk drives or other
media that can skip quickly.
The close callback is invoked by archive_close when the archive process-
ing 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
tar(1), archive_read(3), archive_read_data(3), archive_read_filter(3),
archive_read_format(3), archive_read_set_options(3), archive_util(3),
libarchive(3), tar(5)
BSD February 2, 2012 BSD

133
dependencies/libarchive-3.4.2/doc/text/archive_read_set_options.3.txt vendored Normal file
View file

@ -0,0 +1,133 @@
ARCHIVE_READ_OPTIONS(3) BSD Library Functions Manual ARCHIVE_READ_OPTIONS(3)
NAME
archive_read_set_filter_option, archive_read_set_format_option,
archive_read_set_option, archive_read_set_options -- functions control-
ling options for reading archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
int
archive_read_set_filter_option(struct archive *, const char *module,
const char *option, const char *value);
int
archive_read_set_format_option(struct archive *, const char *module,
const char *option, const char *value);
int
archive_read_set_option(struct archive *, const char *module,
const char *option, const char *value);
int
archive_read_set_options(struct archive *, const char *options);
DESCRIPTION
These functions provide a way for libarchive clients to configure spe-
cific read modules.
archive_read_set_filter_option(), archive_read_set_format_option()
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 noth-
ing 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.
archive_read_set_option()
Calls archive_read_set_format_option(), then
archive_read_set_filter_option(). If either function returns
ARCHIVE_FATAL, ARCHIVE_FATAL will be returned immediately. Oth-
erwise, greater of the two values will be returned.
archive_read_set_options()
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:
option=value
The option/value pair will be provided to every module.
Modules that do not accept an option with this name will
ignore it.
option The option will be provided to every module with a value
of ``1''.
!option
The option will be provided to every module with a NULL
value.
module:option=value, module:option, module:!option
As above, but the corresponding option and value will be
provided only to modules whose name matches module.
OPTIONS
Format cab
hdrcharset
The value is used as a character set name that will be
used when translating file names.
Format cpio
hdrcharset
The value is used as a character set name that will be
used when translating file names.
Format iso9660
joliet Support Joliet extensions. Defaults to enabled, use
!joliet to disable.
rockridge
Support RockRidge extensions. Defaults to enabled, use
!rockridge to disable.
Format lha
hdrcharset
The value is used as a character set name that will be
used when translating file names.
Format mtree
checkfs
Allow reading information missing from the mtree from the
file system. Disabled by default.
Format rar
hdrcharset
The value is used as a character set name that will be
used when translating file names.
Format tar
compat-2x
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 cor-
rectly.
hdrcharset
The value is used as a character set name that will be
used when translating file names.
mac-ext
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 plat-
forms. Use !mac-ext to disable.
read_concatenated_archives
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 con-
catenated archive would be read.
ERRORS
Detailed error codes and textual descriptions are available from the
archive_errno() and archive_error_string() functions.
SEE ALSO
tar(1), archive_read(3), archive_write_set_options(3), libarchive(3)
BSD January 31, 2020 BSD

150
dependencies/libarchive-3.4.2/doc/text/archive_util.3.txt vendored Normal file
View file

@ -0,0 +1,150 @@
ARCHIVE_UTIL(3) BSD Library Functions Manual ARCHIVE_UTIL(3)
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
#include <archive.h>
void
archive_clear_error(struct archive *);
int
archive_compression(struct archive *);
const char *
archive_compression_name(struct archive *);
void
archive_copy_error(struct archive *, struct archive *);
int
archive_errno(struct archive *);
const char *
archive_error_string(struct archive *);
int
archive_file_count(struct archive *);
int
archive_filter_code(struct archive *, int);
int
archive_filter_count(struct archive *, int);
const char *
archive_filter_name(struct archive *, int);
int
archive_format(struct archive *);
const char *
archive_format_name(struct archive *);
int64_t
archive_position(struct archive *, int);
void
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 libarchive(3) library.
archive_clear_error()
Clears any error information left over from a previous call. Not
generally used in client code.
archive_compression()
Synonym for archive_filter_code(a, 0).
archive_compression_name()
Synonym for archive_filter_name(a, 0).
archive_copy_error()
Copies error information from one archive to another.
archive_errno()
Returns a numeric error code (see errno(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.
archive_error_string()
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).
archive_file_count()
Returns a count of the number of files processed by this archive
object. The count is incremented by calls to
archive_write_header(3) or archive_read_next_header(3).
archive_filter_code()
Returns a numeric code identifying the indicated filter. See
archive_filter_count() for details of the numbering.
archive_filter_count()
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 result-
ing 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-num-
bered 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.
archive_filter_name()
Returns a textual name identifying the indicated filter. See
archive_filter_count() for details of the numbering.
archive_format()
Returns a numeric code indicating the format of the current ar-
chive 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.
archive_format_name()
A textual description of the format of the current entry.
archive_position()
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 writ-
ten to the archive. See archive_filter_count() for details of
the numbering here.
archive_set_error()
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-spe-
cific 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.
SEE ALSO
archive_read(3), archive_write(3), libarchive(3), printf(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
BSD February 2, 2012 BSD

192
dependencies/libarchive-3.4.2/doc/text/archive_write.3.txt vendored Normal file
View file

@ -0,0 +1,192 @@
ARCHIVE_WRITE(3) BSD Library Functions Manual ARCHIVE_WRITE(3)
NAME
archive_write -- functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
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 archive_write_new(3).
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 archive_write_filter(3), archive_write_format(3) and
archive_write_blocksize(3).
You can then modify this object for the desired operations with the vari-
ous 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 archive_write_set_options(3).
Open archive
See archive_write_open(3).
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 archive_write_header(3) and archive_write_data(3).
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 archive_write_free(3).
After all entries have been written, use the archive_write_free() func-
tion 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), write(2), and close(2) system calls.
#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
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5),
tar(5)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
BUGS
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 ven-
dor-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.
BSD February 2, 2012 BSD

74
dependencies/libarchive-3.4.2/doc/text/archive_write_blocksize.3.txt vendored Normal file
View file

@ -0,0 +1,74 @@
ARCHIVE_WRITE_BLOCKSI... BSD Library Functions Manual ARCHIVE_WRITE_BLOCKSI...
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
#include <archive.h>
int
archive_write_get_bytes_per_block(struct archive *);
int
archive_write_set_bytes_per_block(struct archive *, int bytes_per_block);
int
archive_write_get_bytes_in_last_block(struct archive *);
int
archive_write_set_bytes_in_last_block(struct archive *, int);
DESCRIPTION
archive_write_set_bytes_per_block()
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.
archive_write_get_bytes_per_block()
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.
archive_write_set_bytes_in_last_block()
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 com-
pression. 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.
archive_write_get_bytes_in_last_block()
Retrieve the currently-set value for last block size. A value of
-1 here indicates that the library should use default values.
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 (-1 indicates the default block size), or ARCHIVE_FATAL.
ERRORS
Detailed error codes and textual descriptions are available from the
archive_errno() and archive_error_string() functions.
SEE ALSO
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5),
tar(5)
BSD February 2, 2012 BSD

52
dependencies/libarchive-3.4.2/doc/text/archive_write_data.3.txt vendored Normal file
View file

@ -0,0 +1,52 @@
ARCHIVE_WRITE_DATA(3) BSD Library Functions Manual ARCHIVE_WRITE_DATA(3)
NAME
archive_write_data, archive_write_data_block -- functions for creating
archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
la_ssize_t
archive_write_data(struct archive *, const void *, size_t);
la_ssize_t
archive_write_data_block(struct archive *, const void *, size_t size,
int64_t offset);
DESCRIPTION
archive_write_data()
Write data corresponding to the header just written.
archive_write_data_block()
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 writ-
ten or -1 on error. (Note: This is currently not supported for
archive_write handles, only for archive_write_disk handles.
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
tar(1), archive_write_finish_entry(3), archive_write_set_options(3),
libarchive(3), cpio(5), mtree(5), tar(5)
BSD February 28, 2017 BSD

239
dependencies/libarchive-3.4.2/doc/text/archive_write_disk.3.txt vendored Normal file
View file

@ -0,0 +1,239 @@
ARCHIVE_WRITE_DISK(3) BSD Library Functions Manual ARCHIVE_WRITE_DISK(3)
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
#include <archive.h>
struct archive *
archive_write_disk_new(void);
int
archive_write_disk_set_options(struct archive *, int flags);
int
archive_write_disk_set_skip_file(struct archive *, dev_t, ino_t);
int
archive_write_disk_set_group_lookup(struct archive *, void *,
gid_t (*)(void *, const char *gname, gid_t gid),
void (*cleanup)(void *));
int
archive_write_disk_set_standard_lookup(struct archive *);
int
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 ar-
chive, then write those objects to a struct archive object created using
the archive_write_disk() family functions. This interface is deliber-
ately very similar to the archive_write() interface used to write objects
to a streaming archive.
archive_write_disk_new()
Allocates and initializes a struct archive object suitable for
writing objects to disk.
archive_write_disk_set_skip_file()
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.
archive_write_disk_set_options()
The options field consists of a bitwise OR of one or more of the
following values:
ARCHIVE_EXTRACT_ACL
Attempt to restore Access Control Lists. By default,
extended ACLs are ignored.
ARCHIVE_EXTRACT_CLEAR_NOCHANGE_FFLAGS
Before removing a file system object prior to replacing
it, clear platform-specific file flags which might pre-
vent its removal.
ARCHIVE_EXTRACT_FFLAGS
Attempt to restore file attributes (file flags). By
default, file attributes are ignored. See chattr(1)
(Linux) or chflags(1) (FreeBSD, Mac OS X) for more infor-
mation on file attributes.
ARCHIVE_EXTRACT_MAC_METADATA
Mac OS X specific. Restore metadata using copyfile(3).
By default, copyfile(3) metadata is ignored.
ARCHIVE_EXTRACT_NO_OVERWRITE
Existing files on disk will not be overwritten. By
default, existing regular files are truncated and over-
written; existing directories will have their permissions
updated; other pre-existing objects are unlinked and
recreated from scratch.
ARCHIVE_EXTRACT_OWNER
The user and group IDs should be set on the restored
file. By default, the user and group IDs are not
restored.
ARCHIVE_EXTRACT_PERM
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 speci-
fied, 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.
ARCHIVE_EXTRACT_SAFE_WRITES
Extract files atomically, by first creating a unique tem-
porary file and then renaming it to its required destina-
tion name. This avoids a race where an application might
see a partial file (or no file) during extraction.
ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
Refuse to extract an absolute path. The default is to
not refuse such paths.
ARCHIVE_EXTRACT_SECURE_NODOTDOT
Refuse to extract a path that contains a .. element any-
where within it. The default is to not refuse such
paths. Note that paths ending in .. always cause an
error, regardless of this flag.
ARCHIVE_EXTRACT_SECURE_SYMLINKS
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 ar-
chives that (deliberately or otherwise) extract files
outside of the current directory. The default is not to
perform this check. If
ARCHIVE_EXTRACT_SPARSE
Scan data for blocks of NUL bytes and try to recreate
them with holes. This results in sparse files, indepen-
dent 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.
ARCHIVE_EXTRACT_TIME
The timestamps (mtime, ctime, and atime) should be
restored. By default, they are ignored. Note that
restoring of atime is not currently supported.
ARCHIVE_EXTRACT_UNLINK
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.
ARCHIVE_EXTRACT_XATTR
Attempt to restore extended file attributes. By default,
they are ignored. See xattr(7) (Linux), xattr(2) (Mac OS
X), or getextattr(8) (FreeBSD) for more information on
extended file attributes.
archive_write_disk_set_group_lookup(),
archive_write_disk_set_user_lookup()
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 func-
tion 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.
archive_write_disk_set_standard_lookup()
This convenience function installs a standard set of user and
group lookup functions. These functions use getpwnam(3) and
getgrnam(3) to convert names to ids, defaulting to the ids if the
names cannot be looked up. These functions also implement a sim-
ple memory cache to reduce the number of calls to getpwnam(3) and
getgrnam(3).
More information about the struct archive object and the overall design
of the library can be found in the libarchive(3) overview. Many of these
functions are also documented under archive_write(3).
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 impossi-
ble.
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 -1 on error.
ERRORS
Detailed error codes and textual descriptions are available from the
archive_errno() and archive_error_string() functions.
SEE ALSO
tar(1), archive_read(3), archive_write(3), libarchive(3)
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 <kientzle@acm.org>.
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 cor-
rectly handle borderline cases such as a non-writable directory contain-
ing files, but can cause unexpected results. In particular, directory
permissions are not fully restored until the archive is closed. If you
use chdir(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 per-
missions 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) and getpwnam(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.
BSD January 19, 2020 BSD

101
dependencies/libarchive-3.4.2/doc/text/archive_write_filter.3.txt vendored Normal file
View file

@ -0,0 +1,101 @@
ARCHIVE_WRITE_FILTER(3) BSD Library Functions Manual ARCHIVE_WRITE_FILTER(3)
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
#include <archive.h>
int
archive_write_add_filter_b64encode(struct archive *);
int
archive_write_add_filter_bzip2(struct archive *);
int
archive_write_add_filter_compress(struct archive *);
int
archive_write_add_filter_grzip(struct archive *);
int
archive_write_add_filter_gzip(struct archive *);
int
archive_write_add_filter_lrzip(struct archive *);
int
archive_write_add_filter_lz4(struct archive *);
int
archive_write_add_filter_lzip(struct archive *);
int
archive_write_add_filter_lzma(struct archive *);
int
archive_write_add_filter_lzop(struct archive *);
int
archive_write_add_filter_none(struct archive *);
int
archive_write_add_filter_program(struct archive *, const char * cmd);
int
archive_write_add_filter_uuencode(struct archive *);
int
archive_write_add_filter_xz(struct archive *);
int
archive_write_add_filter_zstd(struct archive *);
DESCRIPTION
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(),
The resulting archive will be compressed as specified. Note that
the compressed output is always properly blocked.
archive_write_add_filter_b64encode(),
archive_write_add_filter_uuencode(),
The output will be encoded as specified. The encoded output is
always properly blocked.
archive_write_add_filter_none()
This is never necessary. It is provided only for backwards com-
patibility.
archive_write_add_filter_program()
The archive will be fed into the specified compression program.
The output of that program is blocked and written to the client
write callbacks.
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
tar(1), archive_write(3), archive_write_format(3),
archive_write_set_options(3), libarchive(3), cpio(5), mtree(5), tar(5)
BSD August 14, 2014 BSD

37
dependencies/libarchive-3.4.2/doc/text/archive_write_finish_entry.3.txt vendored Normal file
View file

@ -0,0 +1,37 @@
ARCHIVE_WRITE_FINISH_... BSD Library Functions Manual ARCHIVE_WRITE_FINISH_...
NAME
archive_write_finish_entry -- functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
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 condi-
tions that do not prevent further operations, and ARCHIVE_FATAL for seri-
ous 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
tar(1), archive_write_data(3), archive_write_set_options(3),
libarchive(3), cpio(5), mtree(5), tar(5)
BSD February 28, 2017 BSD

146
dependencies/libarchive-3.4.2/doc/text/archive_write_format.3.txt vendored Normal file
View file

@ -0,0 +1,146 @@
ARCHIVE_WRITE_FORMAT(3) BSD Library Functions Manual ARCHIVE_WRITE_FORMAT(3)
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
#include <archive.h>
int
archive_write_set_format(struct archive *, int code);
int
archive_write_set_format_7zip(struct archive *);
int
archive_write_set_format_ar(struct archive *);
int
archive_write_set_format_ar_bsd(struct archive *);
int
archive_write_set_format_ar_svr4(struct archive *);
int
archive_write_set_format_by_name(struct archive *, const char *name);
int
archive_write_set_format_cpio(struct archive *);
int
archive_write_set_format_cpio_newc(struct archive *);
int
archive_write_set_format_filter_by_ext(struct archive *,
const char *filename);
int
archive_write_set_format_filter_by_ext_def(struct archive *,
const char *filename, const char *def_ext);
int
archive_write_set_format_gnutar(struct archive *);
int
archive_write_set_format_iso9660(struct archive *);
int
archive_write_set_format_mtree(struct archive *);
int
archive_write_set_format_pax(struct archive *);
int
archive_write_set_format_pax_restricted(struct archive *);
int
archive_write_set_format_raw(struct archive *);
int
archive_write_set_format_shar(struct archive *);
int
archive_write_set_format_shar_dump(struct archive *);
int
archive_write_set_format_ustar(struct archive *);
int
archive_write_set_format_v7tar(struct archive *);
int
archive_write_set_format_warc(struct archive *);
int
archive_write_set_format_xar(struct archive *);
int
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.
archive_write_set_format()
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.
archive_write_set_format_by_name()
Sets the corresponding format based on the common name.
archive_write_set_format_filter_by_ext(),
archive_write_set_format_filter_by_ext_def()
Sets both filters and format based on the output filename. Sup-
ported extensions: .7z, .zip, .jar, .cpio, .iso, .a, .ar, .tar,
.tgz, .tar.gz, .tar.bz2, .tar.xz
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()
Set the format as specified. More details on the formats sup-
ported by libarchive can be found in the libarchive-formats(5)
manual page.
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
tar(1), archive_write(3), archive_write_set_options(3), libarchive(3),
cpio(5), libarchive-formats(5), mtree(5), tar(5)
BSD February 14, 2013 BSD

58
dependencies/libarchive-3.4.2/doc/text/archive_write_free.3.txt vendored Normal file
View file

@ -0,0 +1,58 @@
ARCHIVE_WRITE_FREE(3) BSD Library Functions Manual ARCHIVE_WRITE_FREE(3)
NAME
archive_write_fail, archive_write_close, archive_write_finish,
archive_write_free -- functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
archive_write_fail(struct archive *);
int
archive_write_close(struct archive *);
int
archive_write_finish(struct archive *);
int
archive_write_free(struct archive *);
DESCRIPTION
archive_write_fail()
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 mal-
formed in this case;
archive_write_close()
Complete the archive and invoke the close callback.
archive_write_finish()
This is a deprecated synonym for archive_write_free().
archive_write_free()
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.
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
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5),
tar(5)
BSD February 2, 2012 BSD

35
dependencies/libarchive-3.4.2/doc/text/archive_write_header.3.txt vendored Normal file
View file

@ -0,0 +1,35 @@
ARCHIVE_WRITE_HEADER(3) BSD Library Functions Manual ARCHIVE_WRITE_HEADER(3)
NAME
archive_write_header -- functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
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 archive_entry(3) for information on creat-
ing 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 opera-
tions, and ARCHIVE_FATAL for serious errors that make remaining opera-
tions impossible.
ERRORS
Detailed error codes and textual descriptions are available from the
archive_errno() and archive_error_string() functions.
SEE ALSO
tar(1), archive_write_set_options(3), libarchive(3), cpio(5), mtree(5),
tar(5)
BSD February 2, 2012 BSD

26
dependencies/libarchive-3.4.2/doc/text/archive_write_new.3.txt vendored Normal file
View file

@ -0,0 +1,26 @@
ARCHIVE_WRITE_NEW(3) BSD Library Functions Manual ARCHIVE_WRITE_NEW(3)
NAME
archive_write_new -- functions for creating archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
struct archive *
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 libarchive(3).
SEE ALSO
tar(1), archive_write(3), archive_write_set_options(3), libarchive(3),
cpio(5), mtree(5), tar(5)
BSD February 2, 2012 BSD

135
dependencies/libarchive-3.4.2/doc/text/archive_write_open.3.txt vendored Normal file
View file

@ -0,0 +1,135 @@
ARCHIVE_WRITE_OPEN(3) BSD Library Functions Manual ARCHIVE_WRITE_OPEN(3)
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
#include <archive.h>
int
archive_write_open(struct archive *, void *client_data,
archive_open_callback *, archive_write_callback *,
archive_close_callback *);
int
archive_write_open_fd(struct archive *, int fd);
int
archive_write_open_FILE(struct archive *, FILE *file);
int
archive_write_open_filename(struct archive *, const char *filename);
int
archive_write_open_memory(struct archive *, void *buffer,
size_t bufferSize, size_t *outUsed);
DESCRIPTION
archive_write_open()
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 ar-
chive. This does not alter the default archive padding.
archive_write_open_fd()
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.
archive_write_open_FILE()
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.
archive_write_open_file()
A deprecated synonym for archive_write_open_filename().
archive_write_open_filename()
A convenience form of archive_write_open() that accepts a file-
name. A NULL argument indicates that the output should be writ-
ten 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.
archive_write_open_memory()
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 allo-
cated until after the archive is closed. This function will dis-
able padding unless you have specifically set the block size.
More information about the struct archive object and the overall design
of the library can be found in the libarchive(3) overview.
Note that the convenience forms above vary in how they block the output.
See archive_write_blocksize(3) 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 func-
tions that will be invoked to write data to the resulting archive. These
functions are registered by calling archive_write_open():
typedef int archive_open_callback(struct archive *, void
*client_data)
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.
typedef la_ssize_t archive_write_callback(struct archive *,
void *client_data, const void *buffer, size_t length)
The write callback is invoked whenever the library needs to write raw
bytes to the archive. For correct blocking, each call to the write call-
back function should translate into a single write(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.
typedef int archive_close_callback(struct archive *, void
*client_data)
The close callback is invoked by archive_close when the archive process-
ing 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
tar(1), archive_write(3), archive_write_blocksize(3),
archive_write_filter(3), archive_write_format(3), archive_write_new(3),
archive_write_set_options(3), libarchive(3), cpio(5), mtree(5), tar(5)
BSD February 2, 2012 BSD

484
dependencies/libarchive-3.4.2/doc/text/archive_write_set_options.3.txt vendored Normal file
View file

@ -0,0 +1,484 @@
ARCHIVE_WRITE_OPTIONS(3) BSD Library Functions Manual ARCHIVE_WRITE_OPTIONS(3)
NAME
archive_write_set_filter_option, archive_write_set_format_option,
archive_write_set_option, archive_write_set_options -- functions control-
ling options for writing archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
int
archive_write_set_filter_option(struct archive *, const char *module,
const char *option, const char *value);
int
archive_write_set_format_option(struct archive *, const char *module,
const char *option, const char *value);
int
archive_write_set_option(struct archive *, const char *module,
const char *option, const char *value);
int
archive_write_set_options(struct archive *, const char *options);
DESCRIPTION
These functions provide a way for libarchive clients to configure spe-
cific write modules.
archive_write_set_filter_option(), archive_write_set_format_option()
Specifies an option that will be passed to the currently-regis-
tered filters (including decompression filters) or format read-
ers.
If option and value are both NULL, these functions will do noth-
ing 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.
archive_write_set_option()
Calls archive_write_set_format_option(), then
archive_write_set_filter_option(). If either function returns
ARCHIVE_FATAL, ARCHIVE_FATAL will be returned immediately. Oth-
erwise, the greater of the two values will be returned.
archive_write_set_options()
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:
option=value
The option/value pair will be provided to every module.
Modules that do not accept an option with this name will
ignore it.
option The option will be provided to every module with a value
of ``1''.
!option
The option will be provided to every module with a NULL
value.
module:option=value, module:option, module:!option
As above, but the corresponding option and value will be
provided only to modules whose name matches module.
OPTIONS
Filter b64encode
mode The value is interpreted as octal digits specifying the
file mode.
name The value specifies the file name.
Filter bzip2
compression-level
The value is interpreted as a decimal integer specifying
the bzip2 compression level. Supported values are from 1
to 9.
Filter gzip
compression-level
The value is interpreted as a decimal integer specifying
the gzip compression level. Supported values are from 0
to 9.
timestamp
Store timestamp. This is enabled by default.
Filter lrzip
compression=type
Use type as compression method. Supported values are
``bzip2'', ``gzipi'', ``lzo'' (ultra fast), and ``zpaq''
(best, extremely slow).
compression-level
The value is interpreted as a decimal integer specifying
the lrzip compression level. Supported values are from 1
to 9.
Filter lz4
compression-level
The value is interpreted as a decimal integer specifying
the lz4 compression level. Supported values are from 0 to
9.
stream-checksum
Enable stream checksum. This is enabled by default.
block-checksum
Enable block checksum. This is disabled by default.
block-size
The value is interpreted as a decimal integer specifying
the lz4 compression block size. Supported values are from
4 to 7 (default).
block-dependence
Use the previous block of the block being compressed for
a compression dictionary to improve compression ratio.
This is disabled by default.
Filter lzop
compression-level
The value is interpreted as a decimal integer specifying
the lzop compression level. Supported values are from 1
to 9.
Filter uuencode
mode The value is interpreted as octal digits specifying the
file mode.
name The value specifies the file name.
Filter xz
compression-level
The value is interpreted as a decimal integer specifying
the compression level. Supported values are from 0 to 9.
threads
The value is interpreted as a decimal integer specifying
the number of threads for multi-threaded lzma compres-
sion. If supported, the default value is read from
lzma_cputhreads().
Filter zstd
compression-level
The value is interpreted as a decimal integer specifying
the compression level. Supported values are from 1 to 22.
Format 7zip
compression
The value is one of ``store'', ``deflate'', ``bzip2'',
``lzma1'', ``lzma2'' or ``ppmd'' to indicate how the fol-
lowing entries should be compressed. Note that this set-
ting is ignored for directories, symbolic links, and
other special entries.
compression-level
The value is interpreted as a decimal integer specifying
the compression level. Values between 0 and 9 are sup-
ported. The interpretation of the compression level
depends on the chosen compression method.
Format cpio
hdrcharset
The value is used as a character set name that will be
used when translating file names.
Format gnutar
hdrcharset
The value is used as a character set name that will be
used when translating file, group and user names.
Format iso9660 - volume metadata
These options are used to set standard ISO9660 metadata.
abstract-file=filename
The file with the specified name will be identified in
the ISO9660 metadata as holding the abstract for this
volume. Default: none.
application-id=filename
The file with the specified name will be identified in
the ISO9660 metadata as holding the application identi-
fier for this volume. Default: none.
biblio-file=filename
The file with the specified name will be identified in
the ISO9660 metadata as holding the bibliography for this
volume. Default: none.
copyright-file=filename
The file with the specified name will be identified in
the ISO9660 metadata as holding the copyright for this
volume. Default: none.
publisher=filename
The file with the specified name will be identified in
the ISO9660 metadata as holding the publisher information
for this volume. Default: none.
volume-id=string
The specified string will be used as the Volume Identi-
fier in the ISO9660 metadata. It is limited to 32 bytes.
Default: none.
Format iso9660 - boot support
These options are used to make an ISO9660 image that can be
directly booted on various systems.
boot=filename
The file matching this name will be used as the El Torito
boot image file.
boot-catalog=name
The name that will be used for the El Torito boot cata-
log. Default: boot.catalog
boot-info-table
The boot image file provided by the boot=filename option
will be edited with appropriate boot information in bytes
8 through 64. Default: disabled
boot-load-seg=hexadecimal-number
The load segment for a no-emulation boot image.
boot-load-size=decimal-number
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.
boot-type=value
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.
Format iso9660 - filename and size extensions
Various extensions to the base ISO9660 format.
allow-ldots
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 exten-
sion area. Default: disabled.
allow-lowercase
If enabled, allows filenames to contain lowercase charac-
ters. If disabled, filenames will be forced to upper-
case. This does not impact names stored in the Rockridge
or Joliet extension area. Default: disabled.
allow-multidot
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: dis-
abled.
allow-period
If enabled, allows filenames to contain trailing period
characters, in violation of the ISO9660 specification.
If disabled, trailing periods will be converted to under-
score characters. This does not impact names stored in
the Rockridge or Joliet extension area. Default: dis-
abled.
allow-pvd-lowercase
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.
allow-sharp-tilde
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 under-
score characters. Default: disabled.
allow-vernum
If enabled, version numbers will be included with files.
If disabled, version numbers will be suppressed, in vio-
lation of the ISO9660 standard. This does not impact
names stored in the Rockridge or Joliet extension area.
Default: enabled.
iso-level
This enables support for file size and file name exten-
sions in the core ISO9660 area. The name extensions
specified here do not affect the names stored in the
Rockridge or Joliet extension areas.
iso-level=1
The most compliant form of ISO9660 image. File-
names are limited to 8.3 uppercase format, direc-
tory names are limited to 8 uppercase characters,
files are limited to 4 GiB, the complete ISO9660
image cannot exceed 4 GiB.
iso-level=2
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.
iso-level=3
As with iso-level=2, except that files may exceed
4 GiB.
iso-level=4
As with iso-level=3, except that filenames may be
up to 193 characters and may include arbitrary
8-bit characters.
joliet Microsoft's Joliet extensions store a completely separate
set of directory information about each file. In partic-
ular, this information includes Unicode filenames of up
to 255 characters. Default: enabled.
limit-depth
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.
limit-dirs
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
pad If enabled, 300 kiB of zero bytes will be appended to the
end of the archive. Default: enabled
relaxed-filenames
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: dis-
abled.
rockridge
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 sup-
port symbolic links and other POSIX file types. Default:
enabled.
Format iso9660 - zisofs support
The zisofs extensions permit each file to be independently com-
pressed 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.
compression-level=number
The compression level used by the deflate compressor.
Ranges from 0 (least effort) to 9 (most effort).
Default: 6
zisofs Synonym for zisofs=direct.
zisofs=direct
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 actu-
ally save any space. In particular, files under 2k will
never be compressed. Note that boot image files are
never compressed.
zisofs=indirect
Recognizes files that have already been compressed with
the mkzftree utility and sets up the necessary file meta-
data so that readers will correctly identify these as
zisofs-compressed files.
zisofs-exclude=filename
Specifies a filename that should not be compressed when
using zisofs=direct. This option can be provided multi-
ple times to suppress compression on many files.
Format mtree
cksum, device, flags, gid, gname, indent, link, md5, mode, nlink,
rmd160, sha1, sha256, sha384, sha512, size, time, uid,
uname
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''.
all Enables all of the above keywords.
use-set
Enables generation of /set lines that specify default
values for the following files and/or directories.
indent XXX needs explanation XXX
Format newc
hdrcharset
The value is used as a character set name that will be
used when translating file names.
Format pax
hdrcharset
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.
xattrheader
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.
Format ustar
hdrcharset
The value is used as a character set name that will be
used when translating file, group and user names.
Format v7tar
hdrcharset
The value is used as a character set name that will be
used when translating file, group and user names.
Format warc
omit-warcinfo
Set to ``true'' to disable output of the warcinfo record.
Format xar
checksum=type
Use type as file checksum method. Supported values are
``none'', ``md5'', and ``sha1'' (default).
compression=type
Use type as compression method. Supported values are
``none'', ``bzip2'', ``gzip'' (default), ``lzma'' and
``xz''.
compression_level
The value is a decimal integer from 1 to 9 specifying the
compression level.
toc-checksum=type
Use type as table of contents checksum method. Supported
values are ``none'', ``md5'' and ``sha1'' (default).
Format zip
compression
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.
compression-level
The value is interpreted as a decimal integer specifying
the compression level. Values between 0 and 9 are sup-
ported. A compression level of 0 switches the compres-
sion method to ``store'', other values will enable
``deflate'' compression with the given level.
encryption
Enable encryption using traditional zip encryption.
encryption=type
Use type as encryption type. Supported values are
``zipcrypt'' (traditional zip encryption), ``aes128''
(WinZip AES-128 encryption) and ``aes256'' (WinZip
AES-256 encryption).
experimental
This boolean option enables or disables experimental Zip
features that may not be compatible with other Zip imple-
mentations.
fakecrc32
This boolean option disables CRC calculations. All CRC
fields are set to zero. It should not be used except for
testing purposes.
hdrcharset
The value is used as a character set name that will be
used when translating file names.
zip64 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 selec-
tively enables these extensions only as needed. In par-
ticular, 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 oth-
erwise require them. This is primarily useful for test-
ing.
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.
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 boot-
ing, and that the gzip compressor should use the maximum compression
level.
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
tar(1), archive_read_set_options(3), archive_write(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The options support for libarchive was originally implemented by
Michihiro NAKAJIMA.
BUGS
BSD January 31, 2020 BSD

35
dependencies/libarchive-3.4.2/doc/text/archive_write_set_passphrase.3.txt vendored Normal file
View file

@ -0,0 +1,35 @@
ARCHIVE_WRITE_SET_PAS... BSD Library Functions Manual ARCHIVE_WRITE_SET_PAS...
NAME
archive_write_set_passphrase, archive_write_set_passphrase_callback --
functions for writing encrypted archives
LIBRARY
Streaming Archive Library (libarchive, -larchive)
SYNOPSIS
#include <archive.h>
int
archive_write_set_passphrase(struct archive *, const char *passphrase);
int
archive_write_set_passphrase_callback(struct archive *,
void *client_data, archive_passphrase_callback *);
DESCRIPTION
archive_write_set_passphrase()
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.
archive_write_set_passphrase_callback()
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.
SEE ALSO
tar(1), archive_write(3), archive_write_set_options(3), libarchive(3)
BSD September 21, 2014 BSD

284
dependencies/libarchive-3.4.2/doc/text/bsdcpio.1.txt vendored Normal file
View file

@ -0,0 +1,284 @@
CPIO(1) BSD General Commands Manual CPIO(1)
NAME
cpio -- copy files to and from archives
SYNOPSIS
cpio -i [options] [pattern ...] [< archive]
cpio -o [options] < name-list [> archive]
cpio -p [options] dest-dir < 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:
-i Input. Read an archive from standard input (unless overridden)
and extract the contents to disk or (if the -t option is speci-
fied) list the contents to standard output. If one or more file
patterns are specified, only files matching one of the patterns
will be extracted.
-o Output. Read a list of filenames from standard input and produce
a new archive on standard output (unless overridden) containing
the specified items.
-p Pass-through. Read a list of filenames from standard input and
copy the files to the specified directory.
OPTIONS
Unless specifically stated otherwise, options are applicable in all oper-
ating modes.
-0, --null
Read filenames separated by NUL characters instead of newlines.
This is necessary if any of the filenames being read might con-
tain newlines.
-A (o mode only) Append to the specified archive. (Not yet imple-
mented.)
-a (o and p modes) Reset access times on files after they are read.
-B (o mode only) Block output to records of 5120 bytes.
-C size
(o mode only) Block output to records of size bytes.
-c (o mode only) Use the old POSIX portable character format.
Equivalent to --format odc.
-d, --make-directories
(i and p modes) Create directories as necessary.
-E file
(i mode only) Read list of file name patterns from file to list
and extract.
-F file, --file file
Read archive from or write archive to file.
-f pattern
(i mode only) Ignore files that match pattern.
-H format, --format format
(o mode only) Produce the output archive in the specified format.
Supported formats include:
cpio Synonym for odc.
newc The SVR4 portable cpio format.
odc The old POSIX.1 portable octet-oriented cpio format.
pax The POSIX.1 pax format, an extension of the ustar for-
mat.
ustar The POSIX.1 tar format.
The default format is odc. See libarchive-formats(5) for more
complete information about the formats currently supported by the
underlying libarchive(3) library.
-h, --help
Print usage information.
-I file
Read archive from file.
-i, --extract
Input mode. See above for description.
--insecure
(i and p mode only) Disable security checks during extraction or
copying. This allows extraction via symbolic links, absolute
paths, and path names containing '..' in the name.
-J, --xz
(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.
-j Synonym for -y.
-L (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.
-l, --link
(p mode only) Create links from the target directory to the orig-
inal files, instead of copying.
--lrzip
(o mode only) Compress the resulting archive with lrzip(1). In
input mode, this option is ignored.
--lz4 (o mode only) Compress the archive with lz4-compatible compres-
sion before writing it. In input mode, this option is ignored;
lz4 compression is recognized automatically on input.
--zstd (o mode only) Compress the archive with zstd-compatible compres-
sion before writing it. In input mode, this option is ignored;
zstd compression is recognized automatically on input.
--lzma (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.
--lzop (o mode only) Compress the resulting archive with lzop(1). In
input mode, this option is ignored.
--passphrase passphrase
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.
-m, --preserve-modification-time
(i and p modes) Set file modification time on created files to
match those in the source.
-n, --numeric-uid-gid
(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.
--no-preserve-owner
(i mode only) Do not attempt to restore file ownership. This is
the default when run by non-root users.
-O file
Write archive to file.
-o, --create
Output mode. See above for description.
-p, --pass-through
Pass-through mode. See above for description.
--preserve-owner
(i mode only) Restore file ownership. This is the default when
run by the root user.
--quiet
Suppress unnecessary messages.
-R [user][:][group], --owner [user][:][group]
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.)
-r (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.
-t, --list
(i mode only) List the contents of the archive to stdout; do not
restore the contents to disk.
-u, --unconditional
(i and p modes) Unconditionally overwrite existing files. Ordi-
narily, an older file will not overwrite a newer file on disk.
-V, --dot
Print a dot to stderr for each file as it is processed. Super-
seded by -v.
-v, --verbose
Print the name of each file to stderr as it is processed. With
-t, provide a detailed listing of each file.
--version
Print the program version information and exit.
-y (o mode only) Compress the archive with bzip2-compatible compres-
sion before writing it. In input mode, this option is ignored;
bzip2 compression is recognized automatically on input.
-Z (o mode only) Compress the archive with compress-compatible com-
pression before writing it. In input mode, this option is
ignored; compression is recognized automatically on input.
-z (o mode only) Compress the archive with gzip-compatible compres-
sion before writing it. In input mode, this option is ignored;
gzip compression is recognized automatically on input.
EXIT STATUS
The cpio utility exits 0 on success, and >0 if an error occurs.
ENVIRONMENT
The following environment variables affect the execution of cpio:
LANG The locale to use. See environ(7) for more information.
TZ The timezone to use when displaying dates. See environ(7) for
more information.
EXAMPLES
The cpio command is traditionally used to copy file hierarchies in con-
junction with the find(1) command. The first example here simply copies
all files from src to dest:
find src | cpio -pmud dest
By carefully selecting options to the find(1) command and combining it
with other standard utilities, it is possible to exercise very fine con-
trol 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 partic-
ular pattern:
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'':
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 inter-
preted 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 stan-
dard. For best compatibility, scripts should limit themselves to the
standard syntax.
SEE ALSO
bzip2(1), gzip(1), mt(1), pax(1), tar(1), libarchive(3), cpio(5),
libarchive-formats(5), tar(5)
STANDARDS
There is no current POSIX standard for the cpio command; it appeared in
ISO/IEC 9945-1:1996 (``POSIX.1'') but was dropped from IEEE Std
1003.1-2001 (``POSIX.1'').
The cpio, ustar, and pax interchange file formats are defined by IEEE Std
1003.1-2001 (``POSIX.1'') 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 libarchive(3) 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 for-
mats cannot support files over 4 gigabytes, except for the ``odc'' vari-
ant, which can support files up to 8 gigabytes.
BSD September 16, 2014 BSD

841
dependencies/libarchive-3.4.2/doc/text/bsdtar.1.txt vendored Normal file
View file

@ -0,0 +1,841 @@
TAR(1) BSD General Commands Manual TAR(1)
NAME
tar -- manipulate tape archives
SYNOPSIS
tar [bundled-flags <args>] [<file> | <pattern> ...]
tar {-c} [options] [files | directories]
tar {-r | -u} -f archive-file [options] [files | directories]
tar {-t | -x} [options] [patterns]
DESCRIPTION
tar creates and manipulates streaming archive files. This implementation
can extract from tar, pax, cpio, zip, jar, ar, xar, rpm, 7-zip, and ISO
9660 cdrom images and can create tar, pax, cpio, ar, zip, 7-zip, and shar
archives.
The first synopsis form shows a ``bundled'' option word. This usage is
provided for compatibility with historical implementations. See COMPATI-
BILITY below for details.
The other synopsis forms show the preferred usage. The first option to
tar is a mode indicator from the following list:
-c Create a new archive containing the specified items. The long
option form is --create.
-r Like -c, but new entries are appended to the archive. Note that
this only works on uncompressed archives stored in regular files.
The -f option is required. The long option form is --append.
-t List archive contents to stdout. The long option form is --list.
-u Like -r, but new entries are added only if they have a modifica-
tion date newer than the corresponding entry in the archive.
Note that this only works on uncompressed archives stored in reg-
ular files. The -f option is required. The long form is
--update.
-x Extract to disk from the archive. If a file with the same name
appears more than once in the archive, each copy will be
extracted, with later copies overwriting (replacing) earlier
copies. The long option form is --extract.
In -c, -r, or -u mode, each specified file or directory is added to the
archive in the order specified on the command line. By default, the con-
tents of each directory are also archived.
In extract or list mode, the entire command line is read and parsed
before the archive is opened. The pathnames or patterns on the command
line indicate which items in the archive should be processed. Patterns
are shell-style globbing patterns as documented in tcsh(1).
OPTIONS
Unless specifically stated otherwise, options are applicable in all oper-
ating modes.
@archive
(c and r modes only) The specified archive is opened and the
entries in it will be appended to the current archive. As a sim-
ple example,
tar -c -f - newfile @original.tar
writes a new archive to standard output containing a file newfile
and all of the entries from original.tar. In contrast,
tar -c -f - newfile original.tar
creates a new archive with only two entries. Similarly,
tar -czf - --format pax @-
reads an archive from standard input (whose format will be deter-
mined automatically) and converts it into a gzip-compressed pax-
format archive on stdout. In this way, tar can be used to con-
vert archives from one format to another.
-a, --auto-compress
(c mode only) Use the archive suffix to decide a set of the for-
mat and the compressions. As a simple example,
tar -a -cf archive.tgz source.c source.h
creates a new archive with restricted pax format and gzip com-
pression,
tar -a -cf archive.tar.bz2.uu source.c source.h
creates a new archive with restricted pax format and bzip2 com-
pression and uuencode compression,
tar -a -cf archive.zip source.c source.h
creates a new archive with zip format,
tar -a -jcf archive.tgz source.c source.h
ignores the ``-j'' option, and creates a new archive with
restricted pax format and gzip compression,
tar -a -jcf archive.xxx source.c source.h
if it is unknown suffix or no suffix, creates a new archive with
restricted pax format and bzip2 compression.
--acls (c, r, u, x modes only) Archive or extract POSIX.1e or NFSv4
ACLs. This is the reverse of --no-acls and the default behavior
in c, r, and u modes (except on Mac OS X) or if tar is run in x
mode as root. On Mac OS X this option translates extended ACLs
to NFSv4 ACLs. To store extended ACLs the --mac-metadata option
is preferred.
-B, --read-full-blocks
Ignored for compatibility with other tar(1) implementations.
-b blocksize, --block-size blocksize
Specify the block size, in 512-byte records, for tape drive I/O.
As a rule, this argument is only needed when reading from or
writing to tape drives, and usually not even then as the default
block size of 20 records (10240 bytes) is very common.
-C directory, --cd directory, --directory directory
In c and r mode, this changes the directory before adding the
following files. In x mode, change directories after opening the
archive but before extracting entries from the archive.
--chroot
(x mode only) chroot() to the current directory after processing
any -C options and before extracting any files.
--clear-nochange-fflags
(x mode only) Before removing file system objects to replace
them, clear platform-specific file attributes or file flags that
might prevent removal.
--exclude pattern
Do not process files or directories that match the specified pat-
tern. Note that exclusions take precedence over patterns or
filenames specified on the command line.
--exclude-vcs
Do not process files or directories internally used by the ver-
sion control systems 'Arch', 'Bazaar', 'CVS', 'Darcs',
'Mercurial', 'RCS', 'SCCS', 'SVN' and 'git'.
--fflags
(c, r, u, x modes only) Archive or extract platform-specific file
attributes or file flags. This is the reverse of --no-fflags and
the default behavior in c, r, and u modes or if tar is run in x
mode as root.
--format format
(c, r, u mode only) Use the specified format for the created ar-
chive. Supported formats include ``cpio'', ``pax'', ``shar'',
and ``ustar''. Other formats may also be supported; see
libarchive-formats(5) for more information about currently-sup-
ported formats. In r and u modes, when extending an existing ar-
chive, the format specified here must be compatible with the for-
mat of the existing archive on disk.
-f file, --file file
Read the archive from or write the archive to the specified file.
The filename can be - for standard input or standard output. The
default varies by system; on FreeBSD, the default is /dev/sa0; on
Linux, the default is /dev/st0.
--gid id
Use the provided group id number. On extract, this overrides the
group id in the archive; the group name in the archive will be
ignored. On create, this overrides the group id read from disk;
if --gname is not also specified, the group name will be set to
match the group id.
--gname name
Use the provided group name. On extract, this overrides the
group name in the archive; if the provided group name does not
exist on the system, the group id (from the archive or from the
--gid option) will be used instead. On create, this sets the
group name that will be stored in the archive; the name will not
be verified against the system group database.
-H (c and r modes only) Symbolic links named on the command line
will be followed; the target of the link will be archived, not
the link itself.
-h (c and r modes only) Synonym for -L.
-I Synonym for -T.
--help Show usage.
--hfsCompression
(x mode only) Mac OS X specific (v10.6 or later). Compress
extracted regular files with HFS+ compression.
--ignore-zeros
An alias of --options read_concatenated_archives for compatibil-
ity with GNU tar.
--include pattern
Process only files or directories that match the specified pat-
tern. Note that exclusions specified with --exclude take prece-
dence over inclusions. If no inclusions are explicitly speci-
fied, all entries are processed by default. The --include option
is especially useful when filtering archives. For example, the
command
tar -c -f new.tar --include='*foo*' @old.tgz
creates a new archive new.tar containing only the entries from
old.tgz containing the string 'foo'.
-J, --xz
(c mode only) Compress the resulting archive with xz(1). In
extract or list modes, this option is ignored. Note that this
tar implementation recognizes XZ compression automatically when
reading archives.
-j, --bzip, --bzip2, --bunzip2
(c mode only) Compress the resulting archive with bzip2(1). In
extract or list modes, this option is ignored. Note that this
tar implementation recognizes bzip2 compression automatically
when reading archives.
-k, --keep-old-files
(x mode only) Do not overwrite existing files. In particular, if
a file appears more than once in an archive, later copies will
not overwrite earlier copies.
--keep-newer-files
(x mode only) Do not overwrite existing files that are newer than
the versions appearing in the archive being extracted.
-L, --dereference
(c and r modes only) All symbolic links will be followed. Nor-
mally, symbolic links are archived as such. With this option,
the target of the link will be archived instead.
-l, --check-links
(c and r modes only) Issue a warning message unless all links to
each file are archived.
--lrzip
(c mode only) Compress the resulting archive with lrzip(1). In
extract or list modes, this option is ignored. Note that this
tar implementation recognizes lrzip compression automatically
when reading archives.
--lz4 (c mode only) Compress the archive with lz4-compatible compres-
sion before writing it. In extract or list modes, this option is
ignored. Note that this tar implementation recognizes lz4 com-
pression automatically when reading archives.
--zstd (c mode only) Compress the archive with zstd-compatible compres-
sion before writing it. In extract or list modes, this option is
ignored. Note that this tar implementation recognizes zstd com-
pression automatically when reading archives.
--lzma (c mode only) Compress the resulting archive with the original
LZMA algorithm. In extract or list modes, this option is
ignored. Use of this option is discouraged and new archives
should be created with --xz instead. Note that this tar imple-
mentation recognizes LZMA compression automatically when reading
archives.
--lzop (c mode only) Compress the resulting archive with lzop(1). In
extract or list modes, this option is ignored. Note that this
tar implementation recognizes LZO compression automatically when
reading archives.
-m, --modification-time
(x mode only) Do not extract modification time. By default, the
modification time is set to the time stored in the archive.
--mac-metadata
(c, r, u and x mode only) Mac OS X specific. Archive or extract
extended ACLs and extended file attributes using copyfile(3) in
AppleDouble format. This is the reverse of --no-mac-metadata.
and the default behavior in c, r, and u modes or if tar is run in
x mode as root.
-n, --norecurse, --no-recursion
Do not operate recursively on the content of directories.
--newer date
(c, r, u modes only) Only include files and directories newer
than the specified date. This compares ctime entries.
--newer-mtime date
(c, r, u modes only) Like --newer, except it compares mtime
entries instead of ctime entries.
--newer-than file
(c, r, u modes only) Only include files and directories newer
than the specified file. This compares ctime entries.
--newer-mtime-than file
(c, r, u modes only) Like --newer-than, except it compares mtime
entries instead of ctime entries.
--nodump
(c and r modes only) Honor the nodump file flag by skipping this
file.
--nopreserveHFSCompression
(x mode only) Mac OS X specific (v10.6 or later). Do not compress
extracted regular files which were compressed with HFS+ compres-
sion before archived. By default, compress the regular files
again with HFS+ compression.
--null (use with -I or -T) Filenames or patterns are separated by null
characters, not by newlines. This is often used to read file-
names output by the -print0 option to find(1).
--no-acls
(c, r, u, x modes only) Do not archive or extract POSIX.1e or
NFSv4 ACLs. This is the reverse of --acls and the default behav-
ior if tar is run as non-root in x mode (on Mac OS X as any user
in c, r, u and x modes).
--no-fflags
(c, r, u, x modes only) Do not archive or extract file attributes
or file flags. This is the reverse of --fflags and the default
behavior if tar is run as non-root in x mode.
--no-mac-metadata
(x mode only) Mac OS X specific. Do not archive or extract ACLs
and extended file attributes using copyfile(3) in AppleDouble
format. This is the reverse of --mac-metadata. and the default
behavior if tar is run as non-root in x mode.
--no-safe-writes
(x mode only) Do not create temporary files and use rename(2) to
replace the original ones. This is the reverse of --safe-writes.
--no-same-owner
(x mode only) Do not extract owner and group IDs. This is the
reverse of --same-owner and the default behavior if tar is run as
non-root.
--no-same-permissions
(x mode only) Do not extract full permissions (SGID, SUID, sticky
bit, file attributes or file flags, extended file attributes and
ACLs). This is the reverse of -p and the default behavior if tar
is run as non-root.
--no-xattrs
(c, r, u, x modes only) Do not archive or extract extended file
attributes. This is the reverse of --xattrs and the default
behavior if tar is run as non-root in x mode.
--numeric-owner
This is equivalent to --uname "" --gname "". On extract, it
causes user and group names in the archive to be ignored in favor
of the numeric user and group ids. On create, it causes user and
group names to not be stored in the archive.
-O, --to-stdout
(x, t modes only) In extract (-x) mode, files will be written to
standard out rather than being extracted to disk. In list (-t)
mode, the file listing will be written to stderr rather than the
usual stdout.
-o (x mode) Use the user and group of the user running the program
rather than those specified in the archive. Note that this has
no significance unless -p is specified, and the program is being
run by the root user. In this case, the file modes and flags
from the archive will be restored, but ACLs or owner information
in the archive will be discarded.
-o (c, r, u mode) A synonym for --format ustar
--older date
(c, r, u modes only) Only include files and directories older
than the specified date. This compares ctime entries.
--older-mtime date
(c, r, u modes only) Like --older, except it compares mtime
entries instead of ctime entries.
--older-than file
(c, r, u modes only) Only include files and directories older
than the specified file. This compares ctime entries.
--older-mtime-than file
(c, r, u modes only) Like --older-than, except it compares mtime
entries instead of ctime entries.
--one-file-system
(c, r, and u modes) Do not cross mount points.
--options options
Select optional behaviors for particular modules. The argument
is a text string containing comma-separated keywords and values.
These are passed to the modules that handle particular formats to
control how those formats will behave. Each option has one of
the following forms:
key=value
The key will be set to the specified value in every mod-
ule that supports it. Modules that do not support this
key will ignore it.
key The key will be enabled in every module that supports it.
This is equivalent to key=1.
!key The key will be disabled in every module that supports
it.
module:key=value, module:key, module:!key
As above, but the corresponding key and value will be
provided only to modules whose name matches module.
The complete list of supported modules and keys for create and
append modes is in archive_write_set_options(3) and for extract
and list modes in archive_read_set_options(3).
Examples of supported options:
iso9660:joliet
Support Joliet extensions. This is enabled by default,
use !joliet or iso9660:!joliet to disable.
iso9660:rockridge
Support Rock Ridge extensions. This is enabled by
default, use !rockridge or iso9660:!rockridge to disable.
gzip:compression-level
A decimal integer from 1 to 9 specifying the gzip com-
pression level.
gzip:timestamp
Store timestamp. This is enabled by default, use
!timestamp or gzip:!timestamp to disable.
lrzip:compression=type
Use type as compression method. Supported values are
bzip2, gzip, lzo (ultra fast), and zpaq (best, extremely
slow).
lrzip:compression-level
A decimal integer from 1 to 9 specifying the lrzip com-
pression level.
lz4:compression-level
A decimal integer from 1 to 9 specifying the lzop com-
pression level.
lz4:stream-checksum
Enable stream checksum. This is by default, use
lz4:!stream-checksum to disable.
lz4:block-checksum
Enable block checksum (Disabled by default).
lz4:block-size
A decimal integer from 4 to 7 specifying the lz4 compres-
sion block size (7 is set by default).
lz4:block-dependence
Use the previous block of the block being compressed for
a compression dictionary to improve compression ratio.
zstd:compression-level
A decimal integer from 1 to 22 specifying the zstd com-
pression level.
lzop:compression-level
A decimal integer from 1 to 9 specifying the lzop com-
pression level.
xz:compression-level
A decimal integer from 0 to 9 specifying the xz compres-
sion level.
mtree:keyword
The mtree writer module allows you to specify which mtree
keywords will be included in the output. Supported key-
words include: cksum, device, flags, gid, gname, indent,
link, md5, mode, nlink, rmd160, sha1, sha256, sha384,
sha512, size, time, uid, uname. The default is equiva-
lent to: ``device, flags, gid, gname, link, mode, nlink,
size, time, type, uid, uname''.
mtree:all
Enables all of the above keywords. You can also use
mtree:!all to disable all keywords.
mtree:use-set
Enable generation of /set lines in the output.
mtree:indent
Produce human-readable output by indenting options and
splitting lines to fit into 80 columns.
zip:compression=type
Use type as compression method. Supported values are
store (uncompressed) and deflate (gzip algorithm).
zip:encryption
Enable encryption using traditional zip encryption.
zip:encryption=type
Use type as encryption type. Supported values are
zipcrypt (traditional zip encryption), aes128 (WinZip
AES-128 encryption) and aes256 (WinZip AES-256 encryp-
tion).
read_concatenated_archives
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 con-
catenated archive would be read. This option is compara-
ble to the -i, --ignore-zeros option of GNU tar.
If a provided option is not supported by any module, that is a
fatal error.
-P, --absolute-paths
Preserve pathnames. By default, absolute pathnames (those that
begin with a / character) have the leading slash removed both
when creating archives and extracting from them. Also, tar will
refuse to extract archive entries whose pathnames contain .. or
whose target directory would be altered by a symlink. This
option suppresses these behaviors.
-p, --insecure, --preserve-permissions
(x mode only) Preserve file permissions. Attempt to restore the
full permissions, including file modes, file attributes or file
flags, extended file attributes and ACLs, if available, for each
item extracted from the archive. This is the reverse of
--no-same-permissions and the default if tar is being run as
root. It can be partially overridden by also specifying
--no-acls, --no-fflags, --no-mac-metadata or --no-xattrs.
--passphrase passphrase
The passphrase is used to extract or create an encrypted archive.
Currently, zip is the only supported format that supports encryp-
tion. You shouldn't use this option unless you realize how inse-
cure use of this option is.
--posix
(c, r, u mode only) Synonym for --format pax
-q, --fast-read
(x and t mode only) Extract or list only the first archive entry
that matches each pattern or filename operand. Exit as soon as
each specified pattern or filename has been matched. By default,
the archive is always read to the very end, since there can be
multiple entries with the same name and, by convention, later
entries overwrite earlier entries. This option is provided as a
performance optimization.
-S (x mode only) Extract files as sparse files. For every block on
disk, check first if it contains only NULL bytes and seek over it
otherwise. This works similar to the conv=sparse option of dd.
-s pattern
Modify file or archive member names according to pattern. The
pattern has the format /old/new/[ghHprRsS] where old is a basic
regular expression, new is the replacement string of the matched
part, and the optional trailing letters modify how the replace-
ment is handled. If old is not matched, the pattern is skipped.
Within new, ~ is substituted with the match, \1 to \9 with the
content of the corresponding captured group. The optional trail-
ing g specifies that matching should continue after the matched
part and stop on the first unmatched pattern. The optional
trailing s specifies that the pattern applies to the value of
symbolic links. The optional trailing p specifies that after a
successful substitution the original path name and the new path
name should be printed to standard error. Optional trailing H,
R, or S characters suppress substitutions for hardlink targets,
regular filenames, or symlink targets, respectively. Optional
trailing h, r, or s characters enable substitutions for hardlink
targets, regular filenames, or symlink targets, respectively.
The default is hrs which applies substitutions to all names. In
particular, it is never necessary to specify h, r, or s.
--safe-writes
(x mode only) Extract files atomically. By default tar unlinks
the original file with the same name as the extracted file (if it
exists), and then creates it immediately under the same name and
writes to it. For a short period of time, applications trying to
access the file might not find it, or see incomplete results. If
--safe-writes is enabled, tar first creates a unique temporary
file, then writes the new contents to the temporary file, and
finally renames the temporary file to its final name atomically
using rename(2). This guarantees that an application accessing
the file, will either see the old contents or the new contents at
all times.
--same-owner
(x mode only) Extract owner and group IDs. This is the reverse
of --no-same-owner and the default behavior if tar is run as
root.
--strip-components count
Remove the specified number of leading path elements. Pathnames
with fewer elements will be silently skipped. Note that the
pathname is edited after checking inclusion/exclusion patterns
but before security checks.
-T filename, --files-from filename
In x or t mode, tar will read the list of names to be extracted
from filename. In c mode, tar will read names to be archived
from filename. The special name ``-C'' on a line by itself will
cause the current directory to be changed to the directory speci-
fied on the following line. Names are terminated by newlines
unless --null is specified. Note that --null also disables the
special handling of lines containing ``-C''. Note: If you are
generating lists of files using find(1), you probably want to use
-n as well.
--totals
(c, r, u modes only) After archiving all files, print a summary
to stderr.
-U, --unlink, --unlink-first
(x mode only) Unlink files before creating them. This can be a
minor performance optimization if most files already exist, but
can make things slower if most files do not already exist. This
flag also causes tar to remove intervening directory symlinks
instead of reporting an error. See the SECURITY section below
for more details.
--uid id
Use the provided user id number and ignore the user name from the
archive. On create, if --uname is not also specified, the user
name will be set to match the user id.
--uname name
Use the provided user name. On extract, this overrides the user
name in the archive; if the provided user name does not exist on
the system, it will be ignored and the user id (from the archive
or from the --uid option) will be used instead. On create, this
sets the user name that will be stored in the archive; the name
is not verified against the system user database.
--use-compress-program program
Pipe the input (in x or t mode) or the output (in c mode) through
program instead of using the builtin compression support.
-v, --verbose
Produce verbose output. In create and extract modes, tar will
list each file name as it is read from or written to the archive.
In list mode, tar will produce output similar to that of ls(1).
An additional -v option will also provide ls-like details in cre-
ate and extract mode.
--version
Print version of tar and libarchive, and exit.
-w, --confirmation, --interactive
Ask for confirmation for every action.
-X filename, --exclude-from filename
Read a list of exclusion patterns from the specified file. See
--exclude for more information about the handling of exclusions.
--xattrs
(c, r, u, x modes only) Archive or extract extended file
attributes. This is the reverse of --no-xattrs and the default
behavior in c, r, and u modes or if tar is run in x mode as root.
-y (c mode only) Compress the resulting archive with bzip2(1). In
extract or list modes, this option is ignored. Note that this
tar implementation recognizes bzip2 compression automatically
when reading archives.
-Z, --compress, --uncompress
(c mode only) Compress the resulting archive with compress(1).
In extract or list modes, this option is ignored. Note that this
tar implementation recognizes compress compression automatically
when reading archives.
-z, --gunzip, --gzip
(c mode only) Compress the resulting archive with gzip(1). In
extract or list modes, this option is ignored. Note that this
tar implementation recognizes gzip compression automatically when
reading archives.
ENVIRONMENT
The following environment variables affect the execution of tar:
TAR_READER_OPTIONS
The default options for format readers and compression read-
ers. The --options option overrides this.
TAR_WRITER_OPTIONS
The default options for format writers and compression writ-
ers. The --options option overrides this.
LANG The locale to use. See environ(7) for more information.
TAPE The default device. The -f option overrides this. Please see
the description of the -f option above for more details.
TZ The timezone to use when displaying dates. See environ(7) for
more information.
EXIT STATUS
The tar utility exits 0 on success, and >0 if an error occurs.
EXAMPLES
The following creates a new archive called file.tar.gz that contains two
files source.c and source.h:
tar -czf file.tar.gz source.c source.h
To view a detailed table of contents for this archive:
tar -tvf file.tar.gz
To extract all entries from the archive on the default tape drive:
tar -x
To examine the contents of an ISO 9660 cdrom image:
tar -tf image.iso
To move file hierarchies, invoke tar as
tar -cf - -C srcdir . | tar -xpf - -C destdir
or more traditionally
cd srcdir ; tar -cf - . | (cd destdir ; tar -xpf -)
In create mode, the list of files and directories to be archived can also
include directory change instructions of the form -Cfoo/baz and archive
inclusions of the form @archive-file. For example, the command line
tar -c -f new.tar foo1 @old.tgz -C/tmp foo2
will create a new archive new.tar. tar will read the file foo1 from the
current directory and add it to the output archive. It will then read
each entry from old.tgz and add those entries to the output archive.
Finally, it will switch to the /tmp directory and add foo2 to the output
archive.
An input file in mtree(5) format can be used to create an output archive
with arbitrary ownership, permissions, or names that differ from existing
data on disk:
$ cat input.mtree
#mtree
usr/bin uid=0 gid=0 mode=0755 type=dir
usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
$ tar -cvf output.tar @input.mtree
The --newer and --newer-mtime switches accept a variety of common date
and time specifications, including ``12 Mar 2005 7:14:29pm'',
``2005-03-12 19:14'', ``5 minutes ago'', and ``19:14 PST May 1''.
The --options argument can be used to control various details of archive
generation or reading. For example, you can generate mtree output which
only contains type, time, and uid keywords:
tar -cf file.tar --format=mtree --options='!all,type,time,uid' dir
or you can set the compression level used by gzip or xz compression:
tar -czf file.tar --options='compression-level=9'.
For more details, see the explanation of the archive_read_set_options()
and archive_write_set_options() API calls that are described in
archive_read(3) and archive_write(3).
COMPATIBILITY
The bundled-arguments format is supported for compatibility with historic
implementations. It consists of an initial word (with no leading - char-
acter) in which each character indicates an option. Arguments follow as
separate words. The order of the arguments must match the order of the
corresponding characters in the bundled command word. For example,
tar tbf 32 file.tar
specifies three flags t, b, and f. The b and f flags both require argu-
ments, so there must be two additional items on the command line. The 32
is the argument to the b flag, and file.tar is the argument to the f
flag.
The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and
w comply with SUSv2.
For maximum portability, scripts that invoke tar should use the bundled-
argument format above, should limit themselves to the c, t, and x modes,
and the b, f, m, v, and w options.
Additional long options are provided to improve compatibility with other
tar implementations.
SECURITY
Certain security issues are common to many archiving programs, including
tar. In particular, carefully-crafted archives can request that tar
extract files to locations outside of the target directory. This can
potentially be used to cause unwitting users to overwrite files they did
not intend to overwrite. If the archive is being extracted by the supe-
ruser, any file on the system can potentially be overwritten. There are
three ways this can happen. Although tar has mechanisms to protect
against each one, savvy users should be aware of the implications:
o Archive entries can have absolute pathnames. By default, tar
removes the leading / character from filenames before restoring
them to guard against this problem.
o Archive entries can have pathnames that include .. components.
By default, tar will not extract files containing .. components
in their pathname.
o Archive entries can exploit symbolic links to restore files to
other directories. An archive can restore a symbolic link to
another directory, then use that link to restore a file into that
directory. To guard against this, tar checks each extracted path
for symlinks. If the final path element is a symlink, it will be
removed and replaced with the archive entry. If -U is specified,
any intermediate symlink will also be unconditionally removed.
If neither -U nor -P is specified, tar will refuse to extract the
entry.
To protect yourself, you should be wary of any archives that come from
untrusted sources. You should examine the contents of an archive with
tar -tf filename
before extraction. You should use the -k option to ensure that tar will
not overwrite any existing files or the -U option to remove any pre-
existing files. You should generally not extract archives while running
with super-user privileges. Note that the -P option to tar disables the
security checks above and allows you to extract an archive while preserv-
ing any absolute pathnames, .. components, or symlinks to other directo-
ries.
SEE ALSO
bzip2(1), compress(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), xz(1),
libarchive(3), libarchive-formats(5), tar(5)
STANDARDS
There is no current POSIX standard for the tar command; it appeared in
ISO/IEC 9945-1:1996 (``POSIX.1'') but was dropped from IEEE Std
1003.1-2001 (``POSIX.1''). The options supported by this implementation
were developed by surveying a number of existing tar implementations as
well as the old POSIX specification for tar and the current POSIX speci-
fication for pax.
The ustar and pax interchange file formats are defined by IEEE Std
1003.1-2001 (``POSIX.1'') for the pax command.
HISTORY
A tar command appeared in Seventh Edition Unix, which was released in
January, 1979. There have been numerous other implementations, many of
which extended the file format. John Gilmore's pdtar public-domain
implementation (circa November, 1987) was quite influential, and formed
the basis of GNU tar. GNU tar was included as the standard system tar in
FreeBSD beginning with FreeBSD 1.0.
This is a complete re-implementation based on the libarchive(3) library.
It was first released with FreeBSD 5.4 in May, 2005.
BUGS
This program follows ISO/IEC 9945-1:1996 (``POSIX.1'') for the definition
of the -l option. Note that GNU tar prior to version 1.15 treated -l as
a synonym for the --one-file-system option.
The -C dir option may differ from historic implementations.
All archive output is written in correctly-sized blocks, even if the out-
put is being compressed. Whether or not the last output block is padded
to a full block size varies depending on the format and the output
device. For tar and cpio formats, the last block of output is padded to
a full block size if the output is being written to standard output or to
a character or block device such as a tape drive. If the output is being
written to a regular file, the last block will not be padded. Many com-
pressors, including gzip(1) and bzip2(1), complain about the null padding
when decompressing an archive created by tar, although they still extract
it correctly.
The compression and decompression is implemented internally, so there may
be insignificant differences between the compressed output generated by
tar -czf - file
and that generated by
tar -cf - file | gzip
The default should be to read and write archives to the standard I/O
paths, but tradition (and POSIX) dictates otherwise.
The r and u modes require that the archive be uncompressed and located in
a regular file on disk. Other archives can be modified using c mode with
the @archive-file extension.
To archive a file called @foo or -foo you must specify it as ./@foo or
./-foo, respectively.
In create mode, a leading ./ is always removed. A leading / is stripped
unless the -P option is specified.
There needs to be better support for file selection on both create and
extract.
There is not yet any support for multi-volume archives.
Converting between dissimilar archive formats (such as tar and cpio)
using the @- convention can cause hard link information to be lost.
(This is a consequence of the incompatible ways that different archive
formats store hardlink information.)
BSD January 31, 2020 BSD

235
dependencies/libarchive-3.4.2/doc/text/cpio.5.txt vendored Normal file
View file

@ -0,0 +1,235 @@
CPIO(5) BSD File Formats Manual CPIO(5)
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 gen-
erally follow the fields in struct stat. (See stat(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:
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
magic The integer value octal 070707. This value can be used to deter-
mine whether this archive is written with little-endian or big-
endian integers.
dev, ino
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.
mode The mode specifies both the regular permissions and the file
type. It consists of several bit fields as follows:
0170000 This masks the file type bits.
0140000 File type value for sockets.
0120000 File type value for symbolic links. For symbolic links,
the link body is stored as file data.
0100000 File type value for regular files.
0060000 File type value for block special devices.
0040000 File type value for directories.
0020000 File type value for character special devices.
0010000 File type value for named pipes or FIFOs.
0004000 SUID bit.
0002000 SGID bit.
0001000 Sticky bit. On some systems, this modifies the behavior
of executables and/or directories.
0000777 The lower 9 bits specify read/write/execute permissions
for world, group, and user following standard POSIX con-
ventions.
uid, gid
The numeric user id and group id of the owner.
nlink 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.
rdev For block special and character special entries, this field con-
tains the associated device number. For all other entry types,
it should be set to zero by writers and ignored by readers.
mtime 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.
namesize
The number of bytes in the pathname that follows the header.
This count includes the trailing NUL byte.
filesize
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.
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
Version 2 of the Single UNIX Specification (``SUSv2'') 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.
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 num-
bers.
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.
magic The string ``070701''.
check This field is always set to zero by writers and ignored by read-
ers. See the next section for more details.
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 giga-
byte 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 pre-
vious 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 arith-
metic. 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 ar-
chives.
XXX Others? XXX
SEE ALSO
cpio(1), tar(5)
STANDARDS
The cpio utility is no longer a part of POSIX or the Single Unix Stan-
dard. It last appeared in Version 2 of the Single UNIX Specification
(``SUSv2''). It has been supplanted in subsequent standards by pax(1).
The portable ASCII format is currently part of the specification for the
pax(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 Version 6 AT&T UNIX 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 IEEE Std 1003.1-1988 (``POSIX.1''). 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 number-
ing.
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.
BSD December 23, 2011 BSD

333
dependencies/libarchive-3.4.2/doc/text/libarchive-formats.5.txt vendored Normal file
View file

@ -0,0 +1,333 @@
LIBARCHIVE-FORMATS(5) BSD File Formats Manual LIBARCHIVE-FORMATS(5)
NAME
libarchive-formats -- archive formats supported by the libarchive library
DESCRIPTION
The libarchive(3) 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 limita-
tions 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 libarchive(3) 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.
gnutar The libarchive(3) 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 libarchive(3) library can write GNU tar format, including
long filename and linkname support, as well as atime and ctime
data.
pax The libarchive(3) 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 under-
stand.
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-han-
dle non-ASCII filenames on systems that did not satisfy this
assumption.
restricted pax
The libarchive library can also write pax archives in which it
attempts to suppress the extended attributes entry whenever pos-
sible. 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-com-
pliant pax interchange format archives. Programs that correctly
read ustar format (see below) will also be able to read this for-
mat; any extended attributes will be extracted as separate files
stored in PaxHeader directories.
ustar The libarchive library can both read and write this format. This
format has the following limitations:
o Device major and minor numbers are limited to 21 bits. Nodes
with larger numbers will not be added to the archive.
o Path names in the archive are limited to 255 bytes. (Shorter
if there is no / character in exactly the right place.)
o Symbolic links and hard links are stored in the archive with
the name of the referenced file. This name is limited to 100
bytes.
o Extended attributes, file flags, and other extended security
information cannot be stored.
o Archive entries are limited to 8 gigabytes in size.
Note that the pax interchange format has none of these restric-
tions. The ustar format is old and widely supported. It is rec-
ommended when compatibility is the primary concern.
v7 The libarchive library can read and write the legacy v7 tar for-
mat. This format has the following limitations:
o Only regular files, directories, and symbolic links can be
archived. Block and character device nodes, FIFOs, and sock-
ets cannot be archived.
o Path names in the archive are limited to 100 bytes.
o Symbolic links and hard links are stored in the archive with
the name of the referenced file. This name is limited to 100
bytes.
o User and group information are stored as numeric IDs; there
is no provision for storing user or group names.
o Extended attributes, file flags, and other extended security
information cannot be stored.
o Archive entries are limited to 8 gigabytes in size.
Generally, users should prefer the ustar format for portability
as the v7 tar format is both less useful and less portable.
The libarchive library also reads a variety of commonly-used extensions
to the basic tar format. These extensions are recognized automatically
whenever they appear.
Numeric extensions.
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.
Solaris extensions
Libarchive recognizes ACL and extended attribute records written
by Solaris tar.
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 vari-
ants, 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.
binary 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.
odc The libarchive library can both read and write this POSIX-stan-
dard format, which is officially known as the ``cpio interchange
format'' or the ``octet-oriented cpio archive format'' and some-
times 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.
SVR4/newc
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.
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 limita-
tions 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 dissim-
ilar user numbering.
Shar Formats
A ``shell archive'' is a shell script that, when executed on a POSIX-com-
pliant system, will recreate a collection of file system objects. The
libarchive library can write two different kinds of shar archives:
shar The traditional shar format uses a limited set of POSIX commands,
including echo(1), mkdir(1), and sed(1). It is suitable for
portably archiving small collections of plain text files. How-
ever, it is not generally well-suited for large archives (many
implementations of sh(1) have limits on the size of a script) nor
should it be used with non-text files.
shardump
This format is similar to shar but encodes files using
uuencode(1) so that the result will be a plain text file regard-
less 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 com-
mands used to restore file attributes make shardump archives less
portable than plain shar archives.
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 exten-
sions 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 opti-
mized with the directory information preceding all file data. This is
done by storing all file data to a temporary file while collecting direc-
tory information in memory. When the image is finished, libarchive
writes out the directory structure followed by the file data. The loca-
tion 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 ar-
chives: 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 sup-
port, 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 pro-
gram portion, but the seeking reader starts by reading the Central Direc-
tory 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) archiver) is a
general-purpose format which is used almost exclusively for object files
to be read by the link editor ld(1). The ar format has never been stan-
dardised. 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 mtree(5) 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 key-
words supported by both the NetBSD and FreeBSD versions of mtree(8),
although many of the keywords cannot currently be stored in an
archive_entry object. When writing, libarchive supports use of the
archive_write_set_options(3) 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 file-
name. 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. Cur-
rently, 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 informa-
tion
XAR
Libarchive can read and write the XAR format used by many Apple tools.
TODO: Need more information
SEE ALSO
ar(1), cpio(1), mkisofs(1), shar(1), tar(1), zip(1), zlib(3), cpio(5),
mtree(5), tar(5)
BSD December 27, 2016 BSD

156
dependencies/libarchive-3.4.2/doc/text/libarchive.3.txt vendored Normal file
View file

@ -0,0 +1,156 @@
LIBARCHIVE(3) BSD Library Functions Manual LIBARCHIVE(3)
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 com-
pression 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 modifi-
cation.
When reading an archive, the library automatically detects the format and
the compression. The library currently has read support for:
o old-style tar archives,
o most variants of the POSIX ``ustar'' format,
o the POSIX ``pax interchange'' format,
o GNU-format tar archives,
o most common cpio archive formats,
o ISO9660 CD images (including RockRidge and Joliet extensions),
o Zip archives,
o ar archives (including GNU/SysV and BSD extensions),
o Microsoft CAB archives,
o LHA archives,
o mtree file tree descriptions,
o RAR archives,
o XAR archives.
The library automatically detects archives compressed with gzip(1),
bzip2(1), xz(1), lzip(1), or compress(1) and decompresses them transpar-
ently. It can similarly detect and decode archives processed with
uuencode(1) or which have an rpm(1) header.
When writing an archive, you can specify the compression to be used and
the format to use. The library can write
o POSIX-standard ``ustar'' archives,
o POSIX ``pax interchange format'' archives,
o POSIX octet-oriented cpio archives,
o Zip archive,
o two different variants of shar archives,
o ISO9660 CD images,
o 7-Zip archives,
o ar archives,
o mtree file tree descriptions,
o XAR archives.
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) implemen-
tations on many systems as well as several newer implementations of
tar(1). 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() func-
tions 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 opera-
tion. More detailed information can be found in the individual manual
pages for each API or utility function.
READING AN ARCHIVE
See archive_read(3).
WRITING AN ARCHIVE
See archive_write(3).
WRITING ENTRIES TO DISK
The archive_write_disk(3) API allows you to write archive_entry(3)
objects to disk using the same API used by archive_write(3). The
archive_write_disk(3) API is used internally by archive_read_extract();
using it directly can provide greater control over how entries get writ-
ten to disk. This API also makes it possible to share code between ar-
chive-to-archive copy and archive-to-disk extraction operations.
READING ENTRIES FROM DISK
The archive_read_disk(3) supports for populating archive_entry(3) objects
from information in the filesystem. This includes the information acces-
sible from the stat(2) system call as well as ACLs, extended attributes,
and other metadata. The archive_read_disk(3) API also supports iterating
over directory trees, which allows directories of files to be read using
an API compatible with the archive_read(3) 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 pro-
vides 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 docu-
mented in archive_entry(3).
Users familiar with historic formats should be aware that the newer vari-
ants 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)). The archive_error_string() returns a textual
error message suitable for display.
archive_read_new() and archive_write_new() return pointers to an allo-
cated 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 archive_entry(3) functions
that are impacted by the currently-selected locale.
SEE ALSO
tar(1), archive_entry(3), archive_read(3), archive_util(3),
archive_write(3), tar(5)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was originally written by Tim Kientzle
<kientzle@acm.org>.
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 sup-
port 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.
BSD March 18, 2012 BSD

260
dependencies/libarchive-3.4.2/doc/text/libarchive_changes.3.txt vendored Normal file
View file

@ -0,0 +1,260 @@
LIBARCHIVE_CHANGES(3) BSD Library Functions Manual LIBARCHIVE_CHANGES(3)
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 ar-
chive. 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 ar-
chives 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 read-
ers and writers to control the character set that will be used for file-
names written in those archives. When possible, this will be set auto-
matically 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:
o In some cases, libarchive's wider types will introduce the possibil-
ity of truncation: for example, on a system with a 16-bit uid_t, you
risk having uid 65536 be truncated to uid 0, which can cause serious
security problems.
o Typedef function pointer types will be incompatible. For example,
if you define custom skip callbacks, you may have to use code simi-
lar to the following if you want to support building against
libarchive2 and libarchive3:
#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 ...
}
Affected functions:
o archive_entry_gid(), archive_entry_set_gid()
o archive_entry_uid(), archive_entry_set_uid()
o archive_entry_ino(), archive_entry_set_ino()
o archive_read_data_block(), archive_write_data_block()
o archive_read_disk_gname(), archive_read_disk_uname()
o archive_read_disk_set_gname_lookup(),
archive_read_disk_set_group_lookup(),
archive_read_disk_set_uname_lookup(),
archive_read_disk_set_user_lookup()
o archive_skip_callback()
o archive_read_extract_set_skip_file(),
archive_write_disk_set_skip_file(), archive_write_set_skip_file()
o archive_write_disk_set_group_lookup(),
archive_write_disk_set_user_lookup()
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:
archive_position_compressed(), archive_position_uncompressed()
archive_filter_bytes()
archive_compression()
archive_filter_code()
archive_compression_name()
archive_filter_name()
archive_read_finish(), archive_write_finish()
archive_read_free(), archive_write_free()
archive_read_open_file(), archive_write_open_file()
archive_read_open_filename(), archive_write_open_filename()
archive_read_support_compression_all()
archive_read_support_filter_all()
archive_read_support_compression_bzip2()
archive_read_support_filter_bzip2()
archive_read_support_compression_compress()
archive_read_support_filter_compress()
archive_read_support_compression_gzip()
archive_read_support_filter_gzip()
archive_read_support_compression_lzip()
archive_read_support_filter_lzip()
archive_read_support_compression_lzma()
archive_read_support_filter_lzma()
archive_read_support_compression_none()
archive_read_support_filter_none()
archive_read_support_compression_program()
archive_read_support_filter_program()
archive_read_support_compression_program_signature()
archive_read_support_filter_program_signature()
archive_read_support_compression_rpm()
archive_read_support_filter_rpm()
archive_read_support_compression_uu()
archive_read_support_filter_uu()
archive_read_support_compression_xz()
archive_read_support_filter_xz()
archive_write_set_compression_bzip2()
archive_write_add_filter_bzip2()
archive_write_set_compression_compress()
archive_write_add_filter_compress()
archive_write_set_compression_gzip()
archive_write_add_filter_gzip()
archive_write_set_compression_lzip()
archive_write_add_filter_lzip()
archive_write_set_compression_lzma()
archive_write_add_filter_lzma()
archive_write_set_compression_none()
archive_write_add_filter_none()
archive_write_set_compression_program()
archive_write_add_filter_program()
archive_write_set_compression_filter()
archive_write_add_filter_filter()
Removed Symbols
These symbols, listed below along with their replacements if any, were
deprecated in libarchive2, and are not part of libarchive3.
archive_api_feature()
archive_version_number()
archive_api_version()
archive_version_number()
archive_version()
archive_version_string()
archive_version_stamp()
archive_version_number()
archive_read_set_filter_options()
archive_read_set_options() or archive_read_set_filter_option()
archive_read_set_format_options()
archive_read_set_options() or archive_read_set_format_option()
archive_write_set_filter_options()
archive_write_set_options() or archive_write_set_filter_option()
archive_write_set_format_options()
archive_write_set_options() or archive_write_set_format_option()
ARCHIVE_API_FEATURE
ARCHIVE_VERSION_NUMBER
ARCHIVE_API_VERSION
ARCHIVE_VERSION_NUMBER
ARCHIVE_VERSION_STAMP
ARCHIVE_VERSION_NUMBER
ARCHIVE_LIBRARY_VERSION
ARCHIVE_VERSION_STRING
ARCHIVE_COMPRESSION_NONE
ARCHIVE_FILTER_NONE
ARCHIVE_COMPRESSION_GZIP
ARCHIVE_FILTER_GZIP
ARCHIVE_COMPRESSION_BZIP2
ARCHIVE_FILTER_BZIP2
ARCHIVE_COMPRESSION_COMPRESS
ARCHIVE_FILTER_COMPRESS
ARCHIVE_COMPRESSION_PROGRAM
ARCHIVE_FILTER_PROGRAM
ARCHIVE_COMPRESSION_LZMA
ARCHIVE_FILTER_LZMA
ARCHIVE_COMPRESSION_XZ
ARCHIVE_FILTER_XZ
ARCHIVE_COMPRESSION_UU
ARCHIVE_FILTER_UU
ARCHIVE_COMPRESSION_RPM
ARCHIVE_FILTER_RPM
ARCHIVE_COMPRESSION_LZIP
ARCHIVE_FILTER_LZIP
ARCHIVE_BYTES_PER_RECORD
512
ARCHIVE_DEFAULT_BYTES_PER_BLOCK
10240
SEE ALSO
archive_read(3), archive_read_filter(3), archive_read_format(3),
archive_read_set_options(3), archive_util(3), archive_write(3),
archive_write_filter(3), archive_write_format(3),
archive_write_set_options(3), libarchive(3)
BSD December 23, 2011 BSD

247
dependencies/libarchive-3.4.2/doc/text/libarchive_internals.3.txt vendored Normal file
View file

@ -0,0 +1,247 @@
LIBARCHIVE_INTERNALS(3) BSD Library Functions Manual LIBARCHIVE_INTERNALS(3)
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 ar-
chive and compression formats.
GENERAL ARCHITECTURE
Externally, libarchive exposes most operations through an opaque, object-
style interface. The archive_entry(3) objects store information about a
single filesystem object. The rest of the library provides facilities to
write archive_entry(3) objects to archive files, read them from archive
files, and write them to disk. (There are plans to add a facility to
read archive_entry(3) objects from disk as well.)
The read and write APIs each have four layers: a public API layer, a for-
mat 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 archive_read(3) API to manipulate an
archive object to read entries and bodies from an archive stream. Inter-
nally, 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
archive_read_open_memory(3), and archive_read_open_fd(3). The compres-
sion 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 ar-
chive, 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 bid-
ders were invoked for each entry, but this design hindered error recov-
ery.)
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 call-
back 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) 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 decom-
pression 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 avail-
able, 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:
Registration/Configuration
When the client invokes the public support function, the decom-
pression 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 con-
tains a void * config slot that can be used for storing any cus-
tomization information.
Bid 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 func-
tion 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.)
Initialize
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.
Satisfy I/O requests
The format handler will invoke the read_ahead, consume, and skip
functions as needed.
Finish 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.
Format Layer
The read formats have a similar lifecycle to the decompression handlers:
Registration
Allocate your private data and initialize your pointers.
Bid 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.)
Read header
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.
Read Data
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. Remem-
ber 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.
Skip All Data
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.
Cleanup
On cleanup, the format should release all of its allocated mem-
ory.
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 regis-
tered 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 con-
tain 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. Direc-
tories are parsed when they are encountered and new items are added to
the list. This design relies heavily on the ISO9660 image being opti-
mized 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
archive_entry(3), archive_read(3), archive_write(3),
archive_write_disk(3), libarchive(3)
HISTORY
The libarchive library first appeared in FreeBSD 5.3.
AUTHORS
The libarchive library was written by Tim Kientzle <kientzle@acm.org>.
BSD January 26, 2011 BSD

184
dependencies/libarchive-3.4.2/doc/text/mtree.5.txt vendored Normal file
View file

@ -0,0 +1,184 @@
MTREE(5) BSD File Formats Manual MTREE(5)
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 back-
slash followed by three octal digits. When reading mtree files, any
appearance of a backslash followed by three octal digits should be con-
verted into the corresponding character.
Each line is interpreted independently as one of the following types:
Blank Blank lines are ignored.
Comment Lines beginning with # are ignored.
Special Lines beginning with / are special commands that influence
the interpretation of later lines.
Relative If the first whitespace-delimited word has no / characters,
it is the name of a file in the current directory. Any rela-
tive entry that describes a directory changes the current
directory.
dot-dot 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.
Full If the first whitespace-delimited word has a / character
after the first character, it is the pathname of a file rela-
tive to the starting directory. There can be multiple full
entries describing the same file.
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 spec-
ification.
Special commands
Two special commands are currently defined:
/set 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 key-
word.
/unset This command removes any default value set by a previous /set
command. It is followed on the same line by one or more key-
words separated by whitespace.
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 unrec-
ognized keywords.
Currently supported keywords are as follows:
cksum The checksum of the file using the default algorithm speci-
fied by the cksum(1) utility.
device The device number for block or char file types. The value
must be one of the following forms:
format,major,minor[,subunit]
A device with major, minor and optional subunit fields.
Their meaning is specified by the operating's system
format. See below for valid formats.
number
Opaque number (as stored on the file system).
The following values for format are recognized: native,
386bsd, 4bsd, bsdos, freebsd, hpux, isc, linux, netbsd, osf1,
sco, solaris, sunos, svr3, svr4, and ultrix.
See mknod(8) for more details.
contents The full pathname of a file that holds the contents of this
file.
flags The file flags as a symbolic name. See chflags(1) for infor-
mation on these names. If no flags are to be set the string
``none'' may be used to override the current default.
gid The file group as a numeric value.
gname The file group as a symbolic name.
ignore Ignore any file hierarchy below this file.
inode The inode number.
link The target of the symbolic link when type=link.
md5 The MD5 message digest of the file.
md5digest A synonym for md5.
mode The current file's permissions as a numeric (octal) or sym-
bolic value.
nlink The number of hard links the file is expected to have.
nochange Make sure this file or directory exists but otherwise ignore
all attributes.
optional The file is optional; do not complain about the file if it is
not in the file hierarchy.
resdevice 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.
ripemd160digest
The RIPEMD160 message digest of the file.
rmd160 A synonym for ripemd160digest.
rmd160digest
A synonym for ripemd160digest.
sha1 The FIPS 160-1 (``SHA-1'') message digest of the file.
sha1digest A synonym for sha1.
sha256 The FIPS 180-2 (``SHA-256'') message digest of the file.
sha256digest
A synonym for sha256.
sha384 The FIPS 180-2 (``SHA-384'') message digest of the file.
sha384digest
A synonym for sha384.
sha512 The FIPS 180-2 (``SHA-512'') message digest of the file.
sha512digest
A synonym for sha512.
size The size, in bytes, of the file.
time The last modification time of the file.
type The type of the file; may be set to any one of the following:
block block special device
char character special device
dir directory
fifo fifo
file regular file
link symbolic link
socket socket
uid The file owner as a numeric value.
uname The file owner as a symbolic name.
SEE ALSO
cksum(1), find(1), mtree(8)
HISTORY
The mtree utility appeared in 4.3BSD-Reno. The MD5 digest capability was
added in FreeBSD 2.1, in response to the widespread use of programs which
can spoof cksum(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.
BSD September 4, 2013 BSD

676
dependencies/libarchive-3.4.2/doc/text/tar.5.txt vendored Normal file
View file

@ -0,0 +1,676 @@
TAR(5) BSD File Formats Manual TAR(5)
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 implemen-
tations 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 docu-
ment 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
Version 7 AT&T UNIX, 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:
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.
name Pathname, stored as a null-terminated string. Early tar imple-
mentations only stored regular files (including hardlinks to
those files). One common early convention used a trailing "/"
character to indicate a directory name, allowing directory per-
missions and owner information to be archived and restored.
mode File mode, stored as an octal number in ASCII.
uid, gid
User id and group id of owner, as octal numbers in ASCII.
size 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.
mtime 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.
checksum
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 inter-
operability problems when transferring archives between systems.
Modern robust readers compute the checksum both ways and accept
the header if either computation matches.
linkflag, linkname
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 '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.)
Early tar implementations varied in how they terminated these fields.
The tar command in Version 7 AT&T UNIX 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 prac-
tice until the IEEE Std 1003.1-1988 (``POSIX.1'') standard was released.
For best portability, modern implementations should fill the numeric
fields with leading zeros.
Pre-POSIX Archives
An early draft of IEEE Std 1003.1-1988 (``POSIX.1'') 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:
o The magic value consists of the five characters ``ustar'' fol-
lowed by a space. The version field contains a space character
followed by a null.
o The numeric fields are generally filled with leading spaces (not
leading zeros as recommended in the final standard).
o The prefix field is often not used, limiting pathnames to the 100
characters of old-style archives.
POSIX ustar Archives
IEEE Std 1003.1-1988 (``POSIX.1'') defined a standard tar file format to
be read and written by compliant implementations of tar(1). 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:
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];
};
typeflag
Type of entry. POSIX extended the earlier linkflag field with
several new type values:
``0'' Regular file. NUL should be treated as a synonym, for
compatibility purposes.
``1'' Hard link.
``2'' Symbolic link.
``3'' Character device node.
``4'' Block device node.
``5'' Directory.
``6'' FIFO node.
``7'' Reserved.
Other A POSIX-compliant implementation must treat any unrecog-
nized typeflag value as a regular file. In particular,
writers should ensure that all entries have a valid file-
name 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.
It is worth noting that the size field, in particular, has dif-
ferent 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.
magic 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.
version
Version. This should be ``00'' (two copies of the ASCII digit
zero) for POSIX standard archives.
uname, gname
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.
devmajor, devminor
Major and minor numbers for character device or block device
entry.
name, prefix
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 compat-
ibility reasons.
Note that all unused bytes must be set to NUL.
Field termination is specified slightly differently by POSIX than by pre-
vious 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, occa-
sionally 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 imple-
mentations, 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 pro-
gram 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 imple-
mentation.
Pax Interchange Format
There are many attributes that cannot be portably stored in a POSIX ustar
archive. IEEE Std 1003.1-2001 (``POSIX.1'') defined a ``pax interchange
format'' that uses two new types of entries to hold text-formatted meta-
data that applies to following entries. Note that a pax interchange for-
mat 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 meta-
data can be examined as necessary.
An entry in a pax interchange format archive consists of one or two stan-
dard 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 indi-
cates 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:
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 deci-
mal, not octal. A description of some common keys follows:
atime, ctime, mtime
File access, inode change, and modification times. These fields
can be negative or include a decimal point and a fractional
value.
hdrcharset
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 particu-
lar, this flag should not be used as a general mechanism to allow
filenames to be stored in arbitrary encodings.
uname, uid, gname, gid
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.
linkpath
The full path of the linked-to file. Note that this is encoded
in UTF8 and can thus include non-ASCII characters.
path The full pathname of the entry. Note that this is encoded in
UTF8 and can thus include non-ASCII characters.
realtime.*, security.*
These keys are reserved and may be used for future standardiza-
tion.
size 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.
SCHILY.*
Vendor-specific attributes used by Joerg Schilling's star imple-
mentation.
SCHILY.acl.access, SCHILY.acl.default, SCHILY.acl.ace
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).
SCHILY.devminor, SCHILY.devmajor
The full minor and major numbers for device nodes.
SCHILY.fflags
The file flags.
SCHILY.realsize
The full size of the file on disk. XXX explain? XXX
SCHILY.dev, SCHILY.ino, SCHILY.nlinks
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.
LIBARCHIVE.*
Vendor-specific attributes used by the libarchive library and
programs that use it.
LIBARCHIVE.creationtime
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.)
LIBARCHIVE.xattr.namespace.key
Libarchive stores POSIX.1e-style extended attributes using keys
of this form. The key value is URL-encoded: All non-ASCII char-
acters 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
VENDOR.*
XXX document other vendor-specific extensions XXX
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 arbitrar-
ily 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 speci-
fies 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 mod-
ify 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 compati-
ble, although more lenient POSIX-compliant readers can successfully
extract most GNU tar archives.
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];
};
typeflag
GNU tar uses the following special entry types, in addition to
those defined by POSIX:
7 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.
D This indicates a directory entry. Unlike the POSIX-stan-
dard "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 ar-
chive 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.
K The data for this entry is a long linkname for the fol-
lowing regular entry.
L The data for this entry is a long pathname for the fol-
lowing regular entry.
M 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 vol-
ume. The "M" typeflag indicates that this entry contin-
ues 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 spec-
ifies 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.
N 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 syn-
tax. Due to security concerns, "N" records are now gen-
erally ignored when reading archives.
S 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 nec-
essary with ``extra'' header extensions (an older format
that is no longer used), or ``sparse'' extensions.
V The name field should be interpreted as a tape/volume
header name. This entry should generally be ignored on
extraction.
magic The magic field holds the five characters ``ustar'' followed by a
space. Note that POSIX ustar archives have a trailing null.
version
The version field holds a space character followed by a null.
Note that POSIX ustar archives use two copies of the ASCII digit
``0''.
atime, ctime
The time the file was last accessed and the time of last change
of file information, stored in octal as with mtime.
longnames
This field is apparently no longer used.
Sparse offset / numbytes
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.
isextended
If this is set to non-zero, the header will be followed by addi-
tional ``sparse header'' records. Each such record contains
information about as many as 21 additional sparse blocks as shown
here:
struct gnu_sparse_header {
struct {
char offset[12];
char numbytes[12];
} sparse[21];
char isextended[1];
char padding[7];
};
realsize
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.
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 introduc-
ing 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''.
GNU.sparse.numblocks, GNU.sparse.offset, GNU.sparse.numbytes,
GNU.sparse.size
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.
GNU.sparse.map
The ``0.1'' format used a single attribute that stored a comma-
separated list of decimal numbers. Each pair of numbers indi-
cated 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.
GNU.sparse.major, GNU.sparse.minor, GNU.sparse.name, GNU.sparse.realsize
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.
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 for-
mat, with the following differences:
o 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.
o 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.
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 addi-
tional 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 file-
names. 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:
NUL Early tar programs stored a zero byte for regular files.
0 POSIX standard type code for a regular file.
1 POSIX standard type code for a hard link description.
2 POSIX standard type code for a symbolic link description.
3 POSIX standard type code for a character device node.
4 POSIX standard type code for a block device node.
5 POSIX standard type code for a directory.
6 POSIX standard type code for a FIFO.
7 POSIX reserved.
7 GNU tar used for pre-allocated files on some systems.
A Solaris tar ACL description stored prior to a regular file header.
A AIX tar ACL description stored after the file body.
D GNU tar directory dump.
K GNU tar long linkname for the following header.
L GNU tar long pathname for the following header.
M GNU tar multivolume marker, indicating the file is a continuation of
a file from the previous volume.
N GNU tar long filename support. Deprecated.
S GNU tar sparse regular file.
V GNU tar tape/volume header name.
X Solaris tar general-purpose extension header.
g POSIX pax interchange format global extensions.
x POSIX pax interchange format per-file extensions.
SEE ALSO
ar(1), pax(1), tar(1)
STANDARDS
The tar utility is no longer a part of POSIX or the Single Unix Standard.
It last appeared in Version 2 of the Single UNIX Specification
(``SUSv2''). It has been supplanted in subsequent standards by pax(1).
The ustar format is currently part of the specification for the pax(1)
utility. The pax interchange file format is new with IEEE Std
1003.1-2001 (``POSIX.1'').
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 <kientzle@FreeBSD.org>.
BSD December 27, 2016 BSD