source-git / libarchive

Clone
Source Code
GIT

Blame doc/html/archive_read_disk.3.html

c8 c8s master
  1.   1d0348c96cfc3f14a424865c9ba093106955a51d
  2.   doc
  3.   html
  4.   archive_read_disk.3.html
Blob History Raw
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
"http://www.w3.org/TR/html4/loose.dtd">
Packit Service 1d0348 
<html>
Packit Service 1d0348 
<head>
Packit Service 1d0348 
<meta name="generator" content="groff -Thtml, see www.gnu.org">
Packit Service 1d0348 
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
Packit Service 1d0348 
<meta name="Content-Style" content="text/css">
Packit Service 1d0348 
<style type="text/css">
Packit Service 1d0348 
       p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
Packit Service 1d0348 
       pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
Packit Service 1d0348 
       table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
Packit Service 1d0348 
       h1      { text-align: center }
Packit Service 1d0348 
</style>
Packit Service 1d0348 
<title></title>
Packit Service 1d0348 
</head>
Packit Service 1d0348 
<body>
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READ_DISK(3) BSD Library Functions Manual
Packit Service 1d0348 
ARCHIVE_READ_DISK(3)
Packit Service 1d0348
Packit Service 1d0348 
NAME
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_new,
Packit Service 1d0348 
archive_read_disk_set_behavior,
Packit Service 1d0348 
archive_read_disk_set_symlink_logical,
Packit Service 1d0348 
archive_read_disk_set_symlink_physical,
Packit Service 1d0348 
archive_read_disk_set_symlink_hybrid,
Packit Service 1d0348 
archive_read_disk_entry_from_file,
Packit Service 1d0348 
archive_read_disk_gname,
Packit Service 1d0348 
archive_read_disk_uname,
Packit Service 1d0348 
archive_read_disk_set_uname_lookup,
Packit Service 1d0348 
archive_read_disk_set_gname_lookup,
Packit Service 1d0348 
archive_read_disk_set_standard_lookup —
Packit Service 1d0348 
functions for reading objects from disk
Packit Service 1d0348
Packit Service 1d0348 
LIBRARY
Packit Service 1d0348
Packit Service 1d0348 
Streaming Archive Library
Packit Service 1d0348 
(libarchive, -larchive)
Packit Service 1d0348
Packit Service 1d0348 
SYNOPSIS
Packit Service 1d0348
Packit Service 1d0348 
#include
Packit Service 1d0348 
<archive.h>
Packit Service 1d0348
Packit Service 1d0348 
struct
Packit Service 1d0348 
archive *
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_new(void);
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_behavior(struct archive *,
Packit Service 1d0348 
int);
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_symlink_logical(struct archive *);
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_symlink_physical(struct archive *);
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_symlink_hybrid(struct archive *);
Packit Service 1d0348
Packit Service 1d0348 
const char
Packit Service 1d0348 
*
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_gname(struct archive *,
Packit Service 1d0348 
gid_t);
Packit Service 1d0348
Packit Service 1d0348 
const char
Packit Service 1d0348 
*
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_uname(struct archive *,
Packit Service 1d0348 
uid_t);
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_gname_lookup(struct archive *,
Packit Service 1d0348 
void *,
Packit Service 1d0348 
const char *(*lookup)(void *, gid_t),
Packit Service 1d0348 
void (*cleanup)(void *));
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_uname_lookup(struct archive *,
Packit Service 1d0348 
void *,
Packit Service 1d0348 
const char *(*lookup)(void *, uid_t),
Packit Service 1d0348 
void (*cleanup)(void *));
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_standard_lookup(struct archive *);
Packit Service 1d0348
Packit Service 1d0348 
int
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_entry_from_file(struct archive *,
Packit Service 1d0348 
struct archive_entry *, int fd,
Packit Service 1d0348 
const struct stat *);
Packit Service 1d0348
Packit Service 1d0348 
DESCRIPTION
Packit Service 1d0348
Packit Service 1d0348 
These functions provide an API
Packit Service 1d0348 
for reading information about objects on disk. In
Packit Service 1d0348 
particular, they provide an interface for populating struct
Packit Service 1d0348 
archive_entry objects.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_new()
Packit Service 1d0348
Packit Service 1d0348 
Allocates and initializes a
Packit Service 1d0348 
struct archive object suitable for reading object
Packit Service 1d0348 
information from disk.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_behavior()
Packit Service 1d0348
Packit Service 1d0348 
Configures various behavior
Packit Service 1d0348 
options when reading entries from disk. The flags field
Packit Service 1d0348 
consists of a bitwise OR of one or more of the following
Packit Service 1d0348 
values:
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_HONOR_NODUMP
Packit Service 1d0348
Packit Service 1d0348 
Skip files and directories with
Packit Service 1d0348 
the nodump file attribute (file flag) set. By default, the
Packit Service 1d0348 
nodump file atrribute is ignored.
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_MAC_COPYFILE
Packit Service 1d0348
Packit Service 1d0348 
Mac OS X specific. Read
Packit Service 1d0348 
metadata (ACLs and extended attributes) with copyfile(3). By
Packit Service 1d0348 
default, metadata is read using copyfile(3).
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_NO_ACL
Packit Service 1d0348
Packit Service 1d0348 
Do not read Access Control
Packit Service 1d0348 
Lists. By default, ACLs are read from disk.
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_NO_FFLAGS
Packit Service 1d0348
Packit Service 1d0348 
Do not read file attributes
Packit Service 1d0348 
(file flags). By default, file attributes are read from
Packit Service 1d0348 
disk. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS
Packit Service 1d0348 
X) for more information on file attributes.
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
Packit Service 1d0348
Packit Service 1d0348 
Do not traverse mount points.
Packit Service 1d0348 
By defaut, moint points are traversed.
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_NO_XATTR
Packit Service 1d0348
Packit Service 1d0348 
Do not read extended file
Packit Service 1d0348 
attributes (xattrs). By default, extended file attributes
Packit Service 1d0348 
are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS
Packit Service 1d0348 
X), or getextattr(8) (FreeBSD) for more information on
Packit Service 1d0348 
extended file attributes.
Packit Service 1d0348
Packit Service 1d0348 
ARCHIVE_READDISK_RESTORE_ATIME
Packit Service 1d0348
Packit Service 1d0348 
Restore access time of
Packit Service 1d0348 
traversed files. By default, access time of traversed files
Packit Service 1d0348 
is not restored.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_symlink_logical(),
Packit Service 1d0348 
archive_read_disk_set_symlink_physical(),
Packit Service 1d0348 
archive_read_disk_set_symlink_hybrid()
Packit Service 1d0348
Packit Service 1d0348 
This sets the mode used for
Packit Service 1d0348 
handling symbolic links. The
Packit Service 1d0348 
’’logical’’ mode follows all
Packit Service 1d0348 
symbolic links. The ’’physical’’
Packit Service 1d0348 
mode does not follow any symbolic links. The
Packit Service 1d0348 
’’hybrid’’ mode currently behaves
Packit Service 1d0348 
identically to the ’’logical’’
Packit Service 1d0348 
mode.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_gname(),
Packit Service 1d0348 
archive_read_disk_uname()
Packit Service 1d0348
Packit Service 1d0348 
Returns a user or group name
Packit Service 1d0348 
given a gid or uid value. By default, these always return a
Packit Service 1d0348 
NULL string.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_gname_lookup(),
Packit Service 1d0348 
archive_read_disk_set_uname_lookup()
Packit Service 1d0348
Packit Service 1d0348 
These allow you to override the
Packit Service 1d0348 
functions used for user and group name lookups. You may also
Packit Service 1d0348 
provide a void * pointer to a private data structure and a
Packit Service 1d0348 
cleanup function for that data. The cleanup function will be
Packit Service 1d0348 
invoked when the struct archive object is destroyed or when
Packit Service 1d0348 
new lookup functions are registered.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_set_standard_lookup()
Packit Service 1d0348
Packit Service 1d0348 
This convenience function
Packit Service 1d0348 
installs a standard set of user and group name lookup
Packit Service 1d0348 
functions. These functions use getpwuid(3) and getgrgid(3)
Packit Service 1d0348 
to convert ids to names, defaulting to NULL if the names
Packit Service 1d0348 
cannot be looked up. These functions also implement a simple
Packit Service 1d0348 
memory cache to reduce the number of calls to getpwuid(3)
Packit Service 1d0348 
and getgrgid(3).
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_entry_from_file()
Packit Service 1d0348
Packit Service 1d0348 
Populates a struct
Packit Service 1d0348 
archive_entry object with information about a particular
Packit Service 1d0348 
file. The archive_entry object must have already been
Packit Service 1d0348 
created with archive_entry_new(3) and at least one of the
Packit Service 1d0348 
source path or path fields must already be set. (If both are
Packit Service 1d0348 
set, the source path will be used.)
Packit Service 1d0348
Packit Service 1d0348 
Information is
Packit Service 1d0348 
read from disk using the path name from the struct
Packit Service 1d0348 
archive_entry object. If a file descriptor is provided, some
Packit Service 1d0348 
information will be obtained using that file descriptor, on
Packit Service 1d0348 
platforms that support the appropriate system calls.
Packit Service 1d0348
Packit Service 1d0348 
If a pointer to
Packit Service 1d0348 
a struct stat is provided, information from that structure
Packit Service 1d0348 
will be used instead of reading from the disk where
Packit Service 1d0348 
appropriate. This can provide performance benefits in
Packit Service 1d0348 
scenarios where struct stat information has already been
Packit Service 1d0348 
read from the disk as a side effect of some other operation.
Packit Service 1d0348 
(For example, directory traversal libraries often provide
Packit Service 1d0348 
this information.)
Packit Service 1d0348
Packit Service 1d0348 
Where
Packit Service 1d0348 
necessary, user and group ids are converted to user and
Packit Service 1d0348 
group names using the currently registered lookup functions
Packit Service 1d0348 
above. This affects the file ownership fields and ACL values
Packit Service 1d0348 
in the struct archive_entry object.
Packit Service 1d0348
Packit Service 1d0348 
More information about the
Packit Service 1d0348 
struct archive object and the overall design of the
Packit Service 1d0348 
library can be found in the libarchive(3) overview.
Packit Service 1d0348
Packit Service 1d0348 
EXAMPLE
Packit Service 1d0348
Packit Service 1d0348 
The following illustrates basic
Packit Service 1d0348 
usage of the library by showing how to use it to copy an
Packit Service 1d0348 
item on disk into an archive.
Packit Service 1d0348
Packit Service 1d0348 
void
Packit Service 1d0348 
file_to_archive(struct archive *a, const char *name)
Packit Service 1d0348 
{
Packit Service 1d0348 
char buff[8192];
Packit Service 1d0348 
size_t bytes_read;
Packit Service 1d0348 
struct archive *ard;
Packit Service 1d0348 
struct archive_entry *entry;
Packit Service 1d0348 
int fd;
Packit Service 1d0348
Packit Service 1d0348 
ard =
Packit Service 1d0348 
archive_read_disk_new();
Packit Service 1d0348 
archive_read_disk_set_standard_lookup(ard);
Packit Service 1d0348 
entry = archive_entry_new();
Packit Service 1d0348 
fd = open(name, O_RDONLY);
Packit Service 1d0348 
if (fd < 0)
Packit Service 1d0348 
return;
Packit Service 1d0348 
archive_entry_copy_pathname(entry, name);
Packit Service 1d0348 
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
Packit Service 1d0348

Packit Service 1d0348 
archive_write_header(a, entry);
Packit Service 1d0348 
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
Packit Service 1d0348

Packit Service 1d0348 
archive_write_data(a, buff, bytes_read);
Packit Service 1d0348 
archive_write_finish_entry(a);
Packit Service 1d0348 
archive_read_free(ard);
Packit Service 1d0348 
archive_entry_free(entry);
Packit Service 1d0348 
}
Packit Service 1d0348
Packit Service 1d0348 
RETURN VALUES
Packit Service 1d0348
Packit Service 1d0348 
Most functions return
Packit Service 1d0348 
ARCHIVE_OK (zero) on success, or one of several
Packit Service 1d0348 
negative error codes for errors. Specific error codes
Packit Service 1d0348 
include: ARCHIVE_RETRY for operations that might
Packit Service 1d0348 
succeed if retried, ARCHIVE_WARN for unusual
Packit Service 1d0348 
conditions that do not prevent further operations, and
Packit Service 1d0348 
ARCHIVE_FATAL for serious errors that make remaining
Packit Service 1d0348 
operations impossible.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_new()
Packit Service 1d0348 
returns a pointer to a newly-allocated struct archive object
Packit Service 1d0348 
or NULL if the allocation failed for any reason.
Packit Service 1d0348
Packit Service 1d0348
Packit Service 1d0348 
archive_read_disk_gname()
Packit Service 1d0348 
and archive_read_disk_uname() return const char *
Packit Service 1d0348 
pointers to the textual name or NULL if the lookup failed
Packit Service 1d0348 
for any reason. The returned pointer points to internal
Packit Service 1d0348 
storage that may be reused on the next call to either of
Packit Service 1d0348 
these functions; callers should copy the string if they need
Packit Service 1d0348 
to continue accessing it.
Packit Service 1d0348
Packit Service 1d0348 
ERRORS
Packit Service 1d0348
Packit Service 1d0348 
Detailed error codes and textual
Packit Service 1d0348 
descriptions are available from the archive_errno()
Packit Service 1d0348 
and archive_error_string() functions.
Packit Service 1d0348
Packit Service 1d0348 
SEE ALSO
Packit Service 1d0348
Packit Service 1d0348 
archive_read(3),
Packit Service 1d0348 
archive_util(3), archive_write(3), archive_write_disk(3),
Packit Service 1d0348 
tar(1), libarchive(3)
Packit Service 1d0348
Packit Service 1d0348 
HISTORY
Packit Service 1d0348
Packit Service 1d0348 
The libarchive library
Packit Service 1d0348 
first appeared in FreeBSD 5.3. The
Packit Service 1d0348 
archive_read_disk interface was added to
Packit Service 1d0348 
libarchive 2.6 and first appeared in
Packit Service 1d0348 
FreeBSD 8.0.
Packit Service 1d0348
Packit Service 1d0348 
AUTHORS
Packit Service 1d0348
Packit Service 1d0348 
The libarchive library
Packit Service 1d0348 
was written by Tim Kientzle
Packit Service 1d0348 
<kientzle@FreeBSD.org>.
Packit Service 1d0348
Packit Service 1d0348 
BUGS
Packit Service 1d0348
Packit Service 1d0348 
The
Packit Service 1d0348 
’’standard’’ user name and group
Packit Service 1d0348 
name lookup functions are not the defaults because
Packit Service 1d0348 
getgrgid(3) and getpwuid(3) are sometimes too large for
Packit Service 1d0348 
particular applications. The current design allows the
Packit Service 1d0348 
application author to use a more compact implementation when
Packit Service 1d0348 
appropriate.
Packit Service 1d0348
Packit Service 1d0348 
The full list of
Packit Service 1d0348 
metadata read from disk by
Packit Service 1d0348 
archive_read_disk_entry_from_file() is necessarily
Packit Service 1d0348 
system-dependent.
Packit Service 1d0348
Packit Service 1d0348 
The
Packit Service 1d0348 
archive_read_disk_entry_from_file() function reads as
Packit Service 1d0348 
much information as it can from disk. Some method should be
Packit Service 1d0348 
provided to limit this so that clients who do not need ACLs,
Packit Service 1d0348 
for instance, can avoid the extra work needed to look up
Packit Service 1d0348 
such information.
Packit Service 1d0348
Packit Service 1d0348 
This API should
Packit Service 1d0348 
provide a set of methods for walking a directory tree. That
Packit Service 1d0348 
would make it a direct parallel of the archive_read(3) API.
Packit Service 1d0348 
When such methods are implemented, the
Packit Service 1d0348 
’’hybrid’’ symbolic link mode will
Packit Service 1d0348 
make sense.
Packit Service 1d0348
Packit Service 1d0348 
BSD
Packit Service 1d0348 
April 3, 2017 BSD
Packit Service 1d0348
Packit Service 1d0348 
</body>
Packit Service 1d0348 
</html>

Powered by Pagure 5.14.1

SSH Hostkey/Fingerprint | Documentation