diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki new file mode 100644 index 0000000..4135470 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/wiki/ManPageArchiveReadDisk3.wiki @@ -0,0 +1,287 @@ +#summary archive_read_disk 3 manual page +== NAME == +*archive_read_disk_new*, +*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*, +*archive_read_close*, +*archive_read_finish* +- functions for reading objects from disk +== SYNOPSIS == +*#include <archive.h>* +<br> +*struct archive `*`* +<br> +*archive_read_disk_new*(_void_); +<br> +*int* +<br> +*archive_read_disk_set_symlink_logical*(_struct archive `*`_); +<br> +*int* +<br> +*archive_read_disk_set_symlink_physical*(_struct archive `*`_); +<br> +*int* +<br> +*archive_read_disk_set_symlink_hybrid*(_struct archive `*`_); +<br> +*int* +<br> +*archive_read_disk_gname*(_struct archive `*`_, _gid_t_); +<br> +*int* +<br> +*archive_read_disk_uname*(_struct archive `*`_, _uid_t_); +<br> +*int* +<br> +*archive_read_disk_set_gname_lookup*(_struct archive `*`_, _void `*`_, _const char `*`(`*`lookup)(void `*`, gid_t)_, _void (`*`cleanup)(void `*`)_); +<br> +*int* +<br> +*archive_read_disk_set_uname_lookup*(_struct archive `*`_, _void `*`_, _const char `*`(`*`lookup)(void `*`, uid_t)_, _void (`*`cleanup)(void `*`)_); +<br> +*int* +<br> +*archive_read_disk_set_standard_lookup*(_struct archive `*`_); +<br> +*int* +<br> +*archive_read_disk_entry_from_file*(_struct archive `*`_, _struct archive_entry `*`_, _int fd_, _const struct stat `*`_); +<br> +*int* +<br> +*archive_read_close*(_struct archive `*`_); +<br> +*int* +<br> +*archive_read_finish*(_struct archive `*`_); +== 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. +<dl> +<dt>*archive_read_disk_new*()</dt><dd> +Allocates and initializes a +*struct archive* +object suitable for reading object information from disk. +</dd><dt> +*archive_read_disk_set_symlink_logical*(), +*archive_read_disk_set_symlink_physical*(), +*archive_read_disk_set_symlink_hybrid*() +</dt> <dd> +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. +</dd><dt> +*archive_read_disk_gname*(), +*archive_read_disk_uname*() +</dt> <dd> +Returns a user or group name given a gid or uid value. +By default, these always return a NULL string. +</dd><dt> +*archive_read_disk_set_gname_lookup*(), +*archive_read_disk_set_uname_lookup*() +</dt> <dd> +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. +</dd><dt>*archive_read_disk_set_standard_lookup*()</dt><dd> +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). +</dd><dt>*archive_read_disk_entry_from_file*()</dt><dd> +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 platforms 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, directory 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. +</dd><dt>*archive_read_close*()</dt><dd> +This currently does nothing. +</dd><dt>*archive_write_finish*()</dt><dd> +Invokes +*archive_write_close*() +if it was not invoked manually, then releases all resources. +</dd></dl> +More information about the +_struct_ archive +object and the overall design of the library can be found in the +*libarchive*(3) +overview. +== EXAMPLE == +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_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); +} +}}} +== 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 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.) + +*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 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. + +== SEE ALSO == +*archive_read*(3), +*archive_write*(3), +*archive_write_disk*(3), +*tar*(1), +*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 +*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. + +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 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. + +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. |