diff options
Diffstat (limited to 'archivers/libarchive/files/doc/wiki/ManPageArchiveReadDisk3.wiki')
| -rw-r--r-- | archivers/libarchive/files/doc/wiki/ManPageArchiveReadDisk3.wiki | 525 |
1 files changed, 267 insertions, 258 deletions
diff --git a/archivers/libarchive/files/doc/wiki/ManPageArchiveReadDisk3.wiki b/archivers/libarchive/files/doc/wiki/ManPageArchiveReadDisk3.wiki index 4135470e704..15d837a103c 100644 --- a/archivers/libarchive/files/doc/wiki/ManPageArchiveReadDisk3.wiki +++ b/archivers/libarchive/files/doc/wiki/ManPageArchiveReadDisk3.wiki @@ -1,178 +1,190 @@ -#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.) +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''', +'''archive_read_free''' +- functions for reading objects from disk +== LIBRARY == +Streaming Archive Library (libarchive, -larchive) +== SYNOPSIS == +'''<nowiki>#include <archive.h></nowiki>''' +<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 *''); +<br> +''int'' +<br> +'''archive_read_free'''(''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 +[[getpwuid(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwuid&sektion=3]] +and +[[getgrgid(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrgid&sektion=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 +[[getpwuid(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwuid&sektion=3]] +and +[[getgrgid(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrgid&sektion=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 +[[ManPagerchiventryew3]] +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. +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.) +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. -{{{ +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> +Does nothing for +'''archive_read_disk''' +handles. +</dd><dt>'''archive_read_finish'''()</dt><dd> +This is a deprecated synonym for +'''archive_read_free'''(). +</dd><dt>'''archive_read_free'''()</dt><dd> +Invokes +'''archive_read_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 +[[ManPageibarchive3]] +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. +```text void file_to_archive(struct archive *a, const char *name) { @@ -187,101 +199,98 @@ file_to_archive(struct archive *a, const char *name) fd = open(name, O_RDONLY); if (fd < 0) return; - archive_entry_copy_sourcepath(entry, name); + archive_entry_copy_pathname(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_read_free(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.) +``` +== 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. -*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_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. +'''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. +== ERRORS == +Detailed error codes and textual descriptions are available from the +'''archive_errno'''() +and +'''archive_error_string'''() +functions. +== SEE ALSO == +[[ManPagerchiveead3]], +[[ManPagerchivetil3]], +[[ManPagerchiverite3]], +[[ManPagerchiveriteisk3]], +[[ManPageBsdtar1]], +[[ManPageibarchive3]] +== 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 +[[getgrgid(3)|http://www.freebsd.org/cgi/man.cgi?query=getgrgid&sektion=3]] +and +[[getpwuid(3)|http://www.freebsd.org/cgi/man.cgi?query=getpwuid&sektion=3]] +are sometimes too large for particular applications. +The current design allows the application author to use a more +compact implementation when appropriate. -== 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 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. -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. +This API should provide a set of methods for walking a directory tree. +That would make it a direct parallel of the +[[ManPagerchiveead3]] +API. +When such methods are implemented, the +"hybrid" +symbolic link mode will make sense. |