diff options
Diffstat (limited to 'libarchive/libarchive-2.8.0/doc/man/archive_entry.3')
| -rw-r--r-- | libarchive/libarchive-2.8.0/doc/man/archive_entry.3 | 519 |
1 files changed, 519 insertions, 0 deletions
diff --git a/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 b/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 new file mode 100644 index 0000000..d459f00 --- /dev/null +++ b/libarchive/libarchive-2.8.0/doc/man/archive_entry.3 @@ -0,0 +1,519 @@ +.TH archive_entry 3 "May 12, 2008" "" +.SH NAME +.ad l +\fB\%archive_entry_acl_add_entry\fP, +\fB\%archive_entry_acl_add_entry_w\fP, +\fB\%archive_entry_acl_clear\fP, +\fB\%archive_entry_acl_count\fP, +\fB\%archive_entry_acl_next\fP, +\fB\%archive_entry_acl_next_w\fP, +\fB\%archive_entry_acl_reset\fP, +\fB\%archive_entry_acl_text_w\fP, +\fB\%archive_entry_atime\fP, +\fB\%archive_entry_atime_nsec\fP, +\fB\%archive_entry_clear\fP, +\fB\%archive_entry_clone\fP, +\fB\%archive_entry_copy_fflags_text\fP, +\fB\%archive_entry_copy_fflags_text_w\fP, +\fB\%archive_entry_copy_gname\fP, +\fB\%archive_entry_copy_gname_w\fP, +\fB\%archive_entry_copy_hardlink\fP, +\fB\%archive_entry_copy_hardlink_w\fP, +\fB\%archive_entry_copy_link\fP, +\fB\%archive_entry_copy_link_w\fP, +\fB\%archive_entry_copy_pathname_w\fP, +\fB\%archive_entry_copy_sourcepath\fP, +\fB\%archive_entry_copy_stat\fP, +\fB\%archive_entry_copy_symlink\fP, +\fB\%archive_entry_copy_symlink_w\fP, +\fB\%archive_entry_copy_uname\fP, +\fB\%archive_entry_copy_uname_w\fP, +\fB\%archive_entry_dev\fP, +\fB\%archive_entry_devmajor\fP, +\fB\%archive_entry_devminor\fP, +\fB\%archive_entry_filetype\fP, +\fB\%archive_entry_fflags\fP, +\fB\%archive_entry_fflags_text\fP, +\fB\%archive_entry_free\fP, +\fB\%archive_entry_gid\fP, +\fB\%archive_entry_gname\fP, +\fB\%archive_entry_hardlink\fP, +\fB\%archive_entry_ino\fP, +\fB\%archive_entry_mode\fP, +\fB\%archive_entry_mtime\fP, +\fB\%archive_entry_mtime_nsec\fP, +\fB\%archive_entry_nlink\fP, +\fB\%archive_entry_new\fP, +\fB\%archive_entry_pathname\fP, +\fB\%archive_entry_pathname_w\fP, +\fB\%archive_entry_rdev\fP, +\fB\%archive_entry_rdevmajor\fP, +\fB\%archive_entry_rdevminor\fP, +\fB\%archive_entry_set_atime\fP, +\fB\%archive_entry_set_ctime\fP, +\fB\%archive_entry_set_dev\fP, +\fB\%archive_entry_set_devmajor\fP, +\fB\%archive_entry_set_devminor\fP, +\fB\%archive_entry_set_filetype\fP, +\fB\%archive_entry_set_fflags\fP, +\fB\%archive_entry_set_gid\fP, +\fB\%archive_entry_set_gname\fP, +\fB\%archive_entry_set_hardlink\fP, +\fB\%archive_entry_set_link\fP, +\fB\%archive_entry_set_mode\fP, +\fB\%archive_entry_set_mtime\fP, +\fB\%archive_entry_set_pathname\fP, +\fB\%archive_entry_set_rdevmajor\fP, +\fB\%archive_entry_set_rdevminor\fP, +\fB\%archive_entry_set_size\fP, +\fB\%archive_entry_set_symlink\fP, +\fB\%archive_entry_set_uid\fP, +\fB\%archive_entry_set_uname\fP, +\fB\%archive_entry_size\fP, +\fB\%archive_entry_sourcepath\fP, +\fB\%archive_entry_stat\fP, +\fB\%archive_entry_symlink\fP, +\fB\%archive_entry_uid\fP, +\fB\%archive_entry_uname\fP +\- functions for manipulating archive entry descriptions +.SH SYNOPSIS +.ad l +\fB#include <archive_entry.h>\fP +.br +\fIvoid\fP +.br +\fB\%archive_entry_acl_add_entry\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ char\ *name\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_acl_add_entry_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP, \fI\%int\ permset\fP, \fI\%int\ tag\fP, \fI\%int\ qual\fP, \fI\%const\ wchar_t\ *name\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_acl_clear\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_count\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ type\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_next\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ char\ **name\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_next_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP, \fI\%int\ *type\fP, \fI\%int\ *permset\fP, \fI\%int\ *tag\fP, \fI\%int\ *qual\fP, \fI\%const\ wchar_t\ **name\fP); +.br +\fIint\fP +.br +\fB\%archive_entry_acl_reset\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ want_type\fP); +.br +\fIconst wchar_t *\fP +.br +\fB\%archive_entry_acl_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int\ flags\fP); +.br +\fItime_t\fP +.br +\fB\%archive_entry_atime\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIlong\fP +.br +\fB\%archive_entry_atime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_clear\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_clone\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char * *\fP +.br +\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIconst wchar_t *\fP +.br +\fB\%archive_entry_copy_fflags_text_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_gname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_hardlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_stat\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ struct\ stat\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_symlink_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_copy_uname_w\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ wchar_t\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_dev\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_devmajor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_devminor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fImode_t\fP +.br +\fB\%archive_entry_filetype\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ *set\fP, \fI\%unsigned\ long\ *clear\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_fflags_text\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_free\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_gname\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_hardlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIino_t\fP +.br +\fB\%archive_entry_ino\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fImode_t\fP +.br +\fB\%archive_entry_mode\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fItime_t\fP +.br +\fB\%archive_entry_mtime\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIlong\fP +.br +\fB\%archive_entry_mtime_nsec\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIunsigned int\fP +.br +\fB\%archive_entry_nlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIstruct archive_entry *\fP +.br +\fB\%archive_entry_new\fP(\fI\%void\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_pathname\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst wchar_t *\fP +.br +\fB\%archive_entry_pathname_w\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_rdev\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIdev_t\fP +.br +\fB\%archive_entry_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_dev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_devmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_devminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_filetype\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_fflags\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\ set\fP, \fI\%unsigned\ long\ clear\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_gid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%gid_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_gname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_hardlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_ino\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ long\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_link\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_mode\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%mode_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_mtime\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%time_t\fP, \fI\%long\ nanos\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_nlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%unsigned\ int\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_pathname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_rdev\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_rdevmajor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_rdevminor\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%dev_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_size\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%int64_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_symlink\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_uid\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%uid_t\fP); +.br +\fIvoid\fP +.br +\fB\%archive_entry_set_uname\fP(\fI\%struct\ archive_entry\ *\fP, \fI\%const\ char\ *\fP); +.br +\fIint64_t\fP +.br +\fB\%archive_entry_size\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_sourcepath\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst struct stat *\fP +.br +\fB\%archive_entry_stat\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_symlink\fP(\fI\%struct\ archive_entry\ *\fP); +.br +\fIconst char *\fP +.br +\fB\%archive_entry_uname\fP(\fI\%struct\ archive_entry\ *\fP); +.SH DESCRIPTION +.ad l +These functions create and manipulate data objects that +represent entries within an archive. +You can think of a +Tn struct archive_entry +as a heavy-duty version of +Tn struct stat: +it includes everything from +Tn struct stat +plus associated pathname, textual group and user names, etc. +These objects are used by +\fBlibarchive\fP(3) +to represent the metadata associated with a particular +entry in an archive. +.SS Create and Destroy +There are functions to allocate, destroy, clear, and copy +\fIarchive_entry\fP +objects: +.RS 5 +.TP +\fB\%archive_entry_clear\fP() +Erases the object, resetting all internal fields to the +same state as a newly-created object. +This is provided to allow you to quickly recycle objects +without thrashing the heap. +.TP +\fB\%archive_entry_clone\fP() +A deep copy operation; all text fields are duplicated. +.TP +\fB\%archive_entry_free\fP() +Releases the +Tn struct archive_entry +object. +.TP +\fB\%archive_entry_new\fP() +Allocate and return a blank +Tn struct archive_entry +object. +.RE +.SS Set and Get Functions +Most of the functions here set or read entries in an object. +Such functions have one of the following forms: +.RS 5 +.TP +\fB\%archive_entry_set_XXXX\fP() +Stores the provided data in the object. +In particular, for strings, the pointer is stored, +not the referenced string. +.TP +\fB\%archive_entry_copy_XXXX\fP() +As above, except that the referenced data is copied +into the object. +.TP +\fB\%archive_entry_XXXX\fP() +Returns the specified data. +In the case of strings, a const-qualified pointer to +the string is returned. +.RE +String data can be set or accessed as wide character strings +or normal +\fIchar\fP +strings. +The functions that use wide character strings are suffixed with +\fB_w\fP. +Note that these are different representations of the same data: +For example, if you store a narrow string and read the corresponding +wide string, the object will transparently convert formats +using the current locale. +Similarly, if you store a wide string and then store a +narrow string for the same data, the previously-set wide string will +be discarded in favor of the new data. +.PP +There are a few set/get functions that merit additional description: +.RS 5 +.TP +\fB\%archive_entry_set_link\fP() +This function sets the symlink field if it is already set. +Otherwise, it sets the hardlink field. +.RE +.SS File Flags +File flags are transparently converted between a bitmap +representation and a textual format. +For example, if you set the bitmap and ask for text, the library +will build a canonical text format. +However, if you set a text format and request a text format, +you will get back the same text, even if it is ill-formed. +If you need to canonicalize a textual flags string, you should first set the +text form, then request the bitmap form, then use that to set the bitmap form. +Setting the bitmap format will clear the internal text representation +and force it to be reconstructed when you next request the text form. +.PP +The bitmap format consists of two integers, one containing bits +that should be set, the other specifying bits that should be +cleared. +Bits not mentioned in either bitmap will be ignored. +Usually, the bitmap of bits to be cleared will be set to zero. +In unusual circumstances, you can force a fully-specified set +of file flags by setting the bitmap of flags to clear to the complement +of the bitmap of flags to set. +(This differs from +\fBfflagstostr\fP(3), +which only includes names for set bits.) +Converting a bitmap to a textual string is a platform-specific +operation; bits that are not meaningful on the current platform +will be ignored. +.PP +The canonical text format is a comma-separated list of flag names. +The +\fB\%archive_entry_copy_fflags_text\fP() +and +\fB\%archive_entry_copy_fflags_text_w\fP() +functions parse the provided text and sets the internal bitmap values. +This is a platform-specific operation; names that are not meaningful +on the current platform will be ignored. +The function returns a pointer to the start of the first name that was not +recognized, or NULL if every name was recognized. +Note that every name--including names that follow an unrecognized name--will +be evaluated, and the bitmaps will be set to reflect every name that is +recognized. +(In particular, this differs from +\fBstrtofflags\fP(3), +which stops parsing at the first unrecognized name.) +.SS ACL Handling +XXX This needs serious help. +XXX +.PP +An +``Access Control List'' +(ACL) is a list of permissions that grant access to particular users or +groups beyond what would normally be provided by standard POSIX mode bits. +The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL +specification. +In particular, POSIX.1e draft 17 specifies several different formats, but +none of those formats include both textual user/group names and numeric +UIDs/GIDs. +.PP +XXX explain ACL stuff XXX +.SH SEE ALSO +.ad l +\fBarchive\fP(3) +.SH HISTORY +.ad l +The +\fB\%libarchive\fP +library first appeared in +FreeBSD 5.3. +.SH AUTHORS +.ad l +-nosplit +The +\fB\%libarchive\fP +library was written by +Tim Kientzle \%<kientzle@acm.org.> |