diff options
Diffstat (limited to 'libarchive/libarchive-2.7.1/doc/man/archive_read_disk.3')
| -rw-r--r-- | libarchive/libarchive-2.7.1/doc/man/archive_read_disk.3 | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.7.1/doc/man/archive_read_disk.3 b/libarchive/libarchive-2.7.1/doc/man/archive_read_disk.3 new file mode 100644 index 0000000..6e10f4f --- /dev/null +++ b/libarchive/libarchive-2.7.1/doc/man/archive_read_disk.3 @@ -0,0 +1,300 @@ +.TH archive_read_disk 3 "March 10, 2009" "" +.SH NAME +.ad l +\fB\%archive_read_disk_new\fP, +\fB\%archive_read_disk_set_symlink_logical\fP, +\fB\%archive_read_disk_set_symlink_physical\fP, +\fB\%archive_read_disk_set_symlink_hybrid\fP, +\fB\%archive_read_disk_entry_from_file\fP, +\fB\%archive_read_disk_gname\fP, +\fB\%archive_read_disk_uname\fP, +\fB\%archive_read_disk_set_uname_lookup\fP, +\fB\%archive_read_disk_set_gname_lookup\fP, +\fB\%archive_read_disk_set_standard_lookup\fP, +\fB\%archive_read_close\fP, +\fB\%archive_read_finish\fP +\- functions for reading objects from disk +.SH SYNOPSIS +.ad l +\fB#include <archive.h>\fP +.br +\fIstruct archive *\fP +.br +\fB\%archive_read_disk_new\fP(\fI\%void\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_logical\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_physical\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_symlink_hybrid\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_gname\fP(\fI\%struct\ archive\ *\fP, \fI\%gid_t\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_uname\fP(\fI\%struct\ archive\ *\fP, \fI\%uid_t\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_gname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ gid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_uname_lookup\fP(\fI\%struct\ archive\ *\fP, \fI\%void\ *\fP, \fI\%const\ char\ *(*lookup)(void\ *,\ uid_t)\fP, \fI\%void\ (*cleanup)(void\ *)\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_set_standard_lookup\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_disk_entry_from_file\fP(\fI\%struct\ archive\ *\fP, \fI\%struct\ archive_entry\ *\fP, \fI\%int\ fd\fP, \fI\%const\ struct\ stat\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_close\fP(\fI\%struct\ archive\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_read_finish\fP(\fI\%struct\ archive\ *\fP); +.SH DESCRIPTION +.ad l +These functions provide an API for reading information about +objects on disk. +In particular, they provide an interface for populating +Tn struct archive_entry +objects. +.RS 5 +.TP +\fB\%archive_read_disk_new\fP() +Allocates and initializes a +Tn struct archive +object suitable for reading object information from disk. +.TP +\fB\%archive_read_disk_set_symlink_logical\fP(), +\fB\%archive_read_disk_set_symlink_physical\fP(), +\fB\%archive_read_disk_set_symlink_hybrid\fP() +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. +.TP +\fB\%archive_read_disk_gname\fP(), +\fB\%archive_read_disk_uname\fP() +Returns a user or group name given a gid or uid value. +By default, these always return a NULL string. +.TP +\fB\%archive_read_disk_set_gname_lookup\fP(), +\fB\%archive_read_disk_set_uname_lookup\fP() +These allow you to override the functions used for +user and group name lookups. +You may also provide a +Tn void * +pointer to a private data structure and a cleanup function for +that data. +The cleanup function will be invoked when the +Tn struct archive +object is destroyed or when new lookup functions are registered. +.TP +\fB\%archive_read_disk_set_standard_lookup\fP() +This convenience function installs a standard set of user +and group name lookup functions. +These functions use +\fBgetpwid\fP(3) +and +\fBgetgrid\fP(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 +\fBgetpwid\fP(3) +and +\fBgetgrid\fP(3). +.TP +\fB\%archive_read_disk_entry_from_file\fP() +Populates a +Tn struct archive_entry +object with information about a particular file. +The +Tn archive_entry +object must have already been created with +\fBarchive_entry_new\fP(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.) +.PP +Information is read from disk using the path name from the +Tn 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. +.PP +If a pointer to a +Tn 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 +Tn 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.) +.PP +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 +Tn struct archive_entry +object. +.TP +\fB\%archive_read_close\fP() +This currently does nothing. +.TP +\fB\%archive_write_finish\fP() +Invokes +\fB\%archive_write_close\fP() +if it was not invoked manually, then releases all resources. +.RE +More information about the +\fIstruct\fP archive +object and the overall design of the library can be found in the +\fBlibarchive\fP(3) +overview. +.SH EXAMPLE +.ad l +The following illustrates basic usage of the library by +showing how to use it to copy an item on disk into an archive. +.RS 4 +.nf +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_sourcepath(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_finish(ard); + archive_entry_free(entry); +} +.RE +.SH RETURN VALUES +.ad l +Most functions return +\fBARCHIVE_OK\fP +(zero) on success, or one of several negative +error codes for errors. +Specific error codes include: +\fBARCHIVE_RETRY\fP +for operations that might succeed if retried, +\fBARCHIVE_WARN\fP +for unusual conditions that do not prevent further operations, and +\fBARCHIVE_FATAL\fP +for serious errors that make remaining operations impossible. +The +\fBarchive_errno\fP(3) +and +\fBarchive_error_string\fP(3) +functions can be used to retrieve an appropriate error code and a +textual error message. +(See +\fBarchive_util\fP(3) +for details.) +.PP +\fB\%archive_read_disk_new\fP() +returns a pointer to a newly-allocated +Tn struct archive +object or NULL if the allocation failed for any reason. +.PP +\fB\%archive_read_disk_gname\fP() +and +\fB\%archive_read_disk_uname\fP() +return +Tn 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. +.PP +.SH SEE ALSO +.ad l +\fBarchive_read\fP(3), +\fBarchive_write\fP(3), +\fBarchive_write_disk\fP(3), +\fBtar\fP(1), +\fBlibarchive\fP(3) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +The +\fB\%archive_read_disk\fP +interface was added to +\fB\%libarchive\fP 2.6 +and first appeared in +FreeBSD 8.0. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@freebsd.org.> +.SH BUGS +.ad l +The +``standard'' +user name and group name lookup functions are not the defaults because +\fBgetgrid\fP(3) +and +\fBgetpwid\fP(3) +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. +.PP +The full list of metadata read from disk by +\fB\%archive_read_disk_entry_from_file\fP() +is necessarily system-dependent. +.PP +The +\fB\%archive_read_disk_entry_from_file\fP() +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. +.PP +This API should provide a set of methods for walking a directory tree. +That would make it a direct parallel of the +\fBarchive_read\fP(3) +API. +When such methods are implemented, the +``hybrid'' +symbolic link mode will make sense. |