diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html new file mode 100644 index 0000000..2257ffe --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/html/archive_read_disk.3.html @@ -0,0 +1,341 @@ +<!-- Creator : groff version 1.19.2 --> +<!-- CreationDate: Thu Feb 4 20:36:31 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 8.0 +March 10, 2009 FreeBSD 8.0</p> +<hr> +</body> +</html> |