archive_read_disk.3.html [plain text]
<!-- Creator : groff version 1.19.2 -->
<!-- CreationDate: Sun Mar 14 19:50:19 2010 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; }
pre { margin-top: 0; margin-bottom: 0; }
table { margin-top: 0; margin-bottom: 0; }
</style>
<title></title>
</head>
<body>
<hr>
<p valign="top">archive_read_disk(3) FreeBSD Library
Functions Manual archive_read_disk(3)</p>
<p style="margin-top: 1em" valign="top"><b>NAME</b></p>
<p style="margin-left:8%;"><b>archive_read_disk_new</b>,
<b>archive_read_disk_set_symlink_logical</b>,
<b>archive_read_disk_set_symlink_physical</b>,
<b>archive_read_disk_set_symlink_hybrid</b>,
<b>archive_read_disk_entry_from_file</b>,
<b>archive_read_disk_gname</b>,
<b>archive_read_disk_uname</b>,
<b>archive_read_disk_set_uname_lookup</b>,
<b>archive_read_disk_set_gname_lookup</b>,
<b>archive_read_disk_set_standard_lookup</b>,
<b>archive_read_close</b>, <b>archive_read_finish</b>
— functions for reading objects from disk</p>
<p style="margin-top: 1em" valign="top"><b>SYNOPSIS</b></p>
<p style="margin-left:8%;"><b>#include
<archive.h></b></p>
<p style="margin-left:8%; margin-top: 1em"><i>struct
archive *</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_new</b>(<i>void</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_logical</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_physical</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_symlink_hybrid</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_gname</b>(<i>struct archive *</i>,
<i>gid_t</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_uname</b>(<i>struct archive *</i>,
<i>uid_t</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_disk_set_gname_lookup</b>(<i>struct archive *</i>,
<i>void *</i>,
<i>const char *(*lookup)(void *, gid_t)</i>,
<i>void (*cleanup)(void *)</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_disk_set_uname_lookup</b>(<i>struct archive *</i>,
<i>void *</i>,
<i>const char *(*lookup)(void *, uid_t)</i>,
<i>void (*cleanup)(void *)</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p valign="top"><b>archive_read_disk_entry_from_file</b>(<i>struct archive *</i>,
<i>struct archive_entry *</i>, <i>int fd</i>,
<i>const struct stat *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_close</b>(<i>struct archive *</i>);</p>
<p style="margin-left:8%; margin-top: 1em"><i>int</i></p>
<p style="margin-left:14%;"><b>archive_read_finish</b>(<i>struct archive *</i>);</p>
<p style="margin-top: 1em" valign="top"><b>DESCRIPTION</b></p>
<p style="margin-left:8%;">These functions provide an API
for reading information about objects on disk. In
particular, they provide an interface for populating struct
archive_entry objects.</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_disk_new</b>()</p>
<p style="margin-left:20%;">Allocates and initializes a
struct archive object suitable for reading object
information from disk.</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_disk_set_symlink_logical</b>(),
<b>archive_read_disk_set_symlink_physical</b>(),
<b>archive_read_disk_set_symlink_hybrid</b>()</p>
<p style="margin-left:20%;">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.</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_disk_gname</b>(),
<b>archive_read_disk_uname</b>()</p>
<p style="margin-left:20%;">Returns a user or group name
given a gid or uid value. By default, these always return a
NULL string.</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_disk_set_gname_lookup</b>(),
<b>archive_read_disk_set_uname_lookup</b>()</p>
<p style="margin-left:20%;">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.</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_disk_set_standard_lookup</b>()</p>
<p style="margin-left:20%;">This convenience function
installs a standard set of user and group name lookup
functions. These functions use getpwid(3) and getgrid(3) to
convert ids to names, defaulting to NULL if the names cannot
be looked up. These functions also implement a simple memory
cache to reduce the number of calls to getpwid(3) and
getgrid(3).</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_disk_entry_from_file</b>()</p>
<p style="margin-left:20%;">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.)</p>
<p style="margin-left:20%; margin-top: 1em">Information is
read from disk using the path name from the struct
archive_entry object. If a file descriptor is provided, some
information will be obtained using that file descriptor, on
platforms that support the appropriate system calls.</p>
<p style="margin-left:20%; margin-top: 1em">If a pointer to
a struct stat is provided, information from that structure
will be used instead of reading from the disk where
appropriate. This can provide performance benefits in
scenarios where struct stat information has already been
read from the disk as a side effect of some other operation.
(For example, directory traversal libraries often provide
this information.)</p>
<p style="margin-left:20%; margin-top: 1em">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.</p>
<p style="margin-top: 1em" valign="top"><b>archive_read_close</b>()</p>
<p style="margin-left:20%;">This currently does
nothing.</p>
<p style="margin-top: 1em" valign="top"><b>archive_write_finish</b>()</p>
<p style="margin-left:20%;">Invokes
<b>archive_write_close</b>() if it was not invoked manually,
then releases all resources.</p>
<p style="margin-left:8%;">More information about the
<i>struct archive</i> object and the overall design of the
library can be found in the libarchive(3) overview.</p>
<p style="margin-top: 1em" valign="top"><b>EXAMPLE</b></p>
<p style="margin-left:8%;">The following illustrates basic
usage of the library by showing how to use it to copy an
item on disk into an archive.</p>
<p style="margin-left:17%; margin-top: 1em">void <br>
file_to_archive(struct archive *a, const char *name) <br>
{ <br>
char buff[8192]; <br>
size_t bytes_read; <br>
struct archive *ard; <br>
struct archive_entry *entry; <br>
int fd;</p>
<p style="margin-left:17%; margin-top: 1em">ard =
archive_read_disk_new(); <br>
archive_read_disk_set_standard_lookup(ard); <br>
entry = archive_entry_new(); <br>
fd = open(name, O_RDONLY); <br>
if (fd < 0) <br>
return; <br>
archive_entry_copy_sourcepath(entry, name); <br>
archive_read_disk_entry_from_file(ard, entry, fd, NULL);
<br>
archive_write_header(a, entry); <br>
while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
<br>
archive_write_data(a, buff, bytes_read); <br>
archive_write_finish_entry(a); <br>
archive_read_finish(ard); <br>
archive_entry_free(entry); <br>
}</p>
<p style="margin-top: 1em" valign="top"><b>RETURN
VALUES</b></p>
<p style="margin-left:8%;">Most functions return
<b>ARCHIVE_OK</b> (zero) on success, or one of several
negative error codes for errors. Specific error codes
include: <b>ARCHIVE_RETRY</b> for operations that might
succeed if retried, <b>ARCHIVE_WARN</b> for unusual
conditions that do not prevent further operations, and
<b>ARCHIVE_FATAL</b> for serious errors that make remaining
operations impossible. The archive_errno(3) and
archive_error_string(3) functions can be used to retrieve an
appropriate error code and a textual error message. (See
archive_util(3) for details.)</p>
<p style="margin-left:8%; margin-top: 1em"><b>archive_read_disk_new</b>()
returns a pointer to a newly-allocated struct archive object
or NULL if the allocation failed for any reason.</p>
<p style="margin-left:8%; margin-top: 1em"><b>archive_read_disk_gname</b>()
and <b>archive_read_disk_uname</b>() return const char *
pointers to the textual name or NULL if the lookup failed
for any reason. The returned pointer points to internal
storage that may be reused on the next call to either of
these functions; callers should copy the string if they need
to continue accessing it.</p>
<p style="margin-top: 1em" valign="top"><b>SEE ALSO</b></p>
<p style="margin-left:8%;">archive_read(3),
archive_write(3), archive_write_disk(3), tar(1),
libarchive(3)</p>
<p style="margin-top: 1em" valign="top"><b>HISTORY</b></p>
<p style="margin-left:8%;">The <b>libarchive</b> library
first appeared in FreeBSD 5.3. The
<b>archive_read_disk</b> interface was added to
<b>libarchive 2.6</b> and first appeared in
FreeBSD 8.0.</p>
<p style="margin-top: 1em" valign="top"><b>AUTHORS</b></p>
<p style="margin-left:8%;">The <b>libarchive</b> library
was written by Tim Kientzle
⟨kientzle@freebsd.org⟩.</p>
<p style="margin-top: 1em" valign="top"><b>BUGS</b></p>
<p style="margin-left:8%;">The
‘‘standard’’ user name and group
name lookup functions are not the defaults because
getgrid(3) and getpwid(3) are sometimes too large for
particular applications. The current design allows the
application author to use a more compact implementation when
appropriate.</p>
<p style="margin-left:8%; margin-top: 1em">The full list of
metadata read from disk by
<b>archive_read_disk_entry_from_file</b>() is necessarily
system-dependent.</p>
<p style="margin-left:8%; margin-top: 1em">The
<b>archive_read_disk_entry_from_file</b>() function reads as
much information as it can from disk. Some method should be
provided to limit this so that clients who do not need ACLs,
for instance, can avoid the extra work needed to look up
such information.</p>
<p style="margin-left:8%; margin-top: 1em">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.</p>
<p style="margin-left:8%; margin-top: 1em">FreeBSD 9.0
March 10, 2009 FreeBSD 9.0</p>
<hr>
</body>
</html>