From: Joerg Sonnenberger Date: Mon, 22 Feb 2010 04:12:35 +0000 (-0500) Subject: Reduce to the basic creation/destroy functions and an overview over the X-Git-Tag: v3.0.0a~1205 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d64586c52ad8e3226f7c3a7d579a9321099f7f10;p=thirdparty%2Flibarchive.git Reduce to the basic creation/destroy functions and an overview over the accessor functions. Reference the man page groups for the details. SVN-Revision: 1960 --- diff --git a/libarchive/archive_entry.3 b/libarchive/archive_entry.3 index 6464ab940..e79d7fe7f 100644 --- a/libarchive/archive_entry.3 +++ b/libarchive/archive_entry.3 @@ -1,4 +1,5 @@ .\" Copyright (c) 2003-2007 Tim Kientzle +.\" Copyright (c) 2010 Joerg Sonnenberger .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,269 +25,25 @@ .\" .\" $FreeBSD: src/lib/libarchive/archive_entry.3,v 1.18 2008/05/26 17:00:22 kientzle Exp $ .\" -.Dd May 12, 2008 +.Dd Feburary 22, 2010 .Dt archive_entry 3 .Os .Sh NAME -.Nm archive_entry_acl_add_entry , -.Nm archive_entry_acl_add_entry_w , -.Nm archive_entry_acl_clear , -.Nm archive_entry_acl_count , -.Nm archive_entry_acl_next , -.Nm archive_entry_acl_next_w , -.Nm archive_entry_acl_reset , -.Nm archive_entry_acl_text_w , -.Nm archive_entry_atime , -.Nm archive_entry_atime_nsec , .Nm archive_entry_clear , .Nm archive_entry_clone , -.Nm archive_entry_copy_fflags_text , -.Nm archive_entry_copy_fflags_text_w , -.Nm archive_entry_copy_gname , -.Nm archive_entry_copy_gname_w , -.Nm archive_entry_copy_hardlink , -.Nm archive_entry_copy_hardlink_w , -.Nm archive_entry_copy_link , -.Nm archive_entry_copy_link_w , -.Nm archive_entry_copy_pathname_w , -.Nm archive_entry_copy_sourcepath , -.Nm archive_entry_copy_stat , -.Nm archive_entry_copy_symlink , -.Nm archive_entry_copy_symlink_w , -.Nm archive_entry_copy_uname , -.Nm archive_entry_copy_uname_w , -.Nm archive_entry_dev , -.Nm archive_entry_devmajor , -.Nm archive_entry_devminor , -.Nm archive_entry_filetype , -.Nm archive_entry_fflags , -.Nm archive_entry_fflags_text , .Nm archive_entry_free , -.Nm archive_entry_gid , -.Nm archive_entry_gname , -.Nm archive_entry_hardlink , -.Nm archive_entry_ino , -.Nm archive_entry_mode , -.Nm archive_entry_mtime , -.Nm archive_entry_mtime_nsec , -.Nm archive_entry_nlink , .Nm archive_entry_new , -.Nm archive_entry_pathname , -.Nm archive_entry_pathname_w , -.Nm archive_entry_perm , -.Nm archive_entry_rdev , -.Nm archive_entry_rdevmajor , -.Nm archive_entry_rdevminor , -.Nm archive_entry_set_atime , -.Nm archive_entry_set_ctime , -.Nm archive_entry_set_dev , -.Nm archive_entry_set_devmajor , -.Nm archive_entry_set_devminor , -.Nm archive_entry_set_filetype , -.Nm archive_entry_set_fflags , -.Nm archive_entry_set_gid , -.Nm archive_entry_set_gname , -.Nm archive_entry_set_hardlink , -.Nm archive_entry_set_link , -.Nm archive_entry_set_mode , -.Nm archive_entry_set_mtime , -.Nm archive_entry_set_pathname , -.Nm archive_entry_set_perm , -.Nm archive_entry_set_rdevmajor , -.Nm archive_entry_set_rdevminor , -.Nm archive_entry_set_size , -.Nm archive_entry_set_symlink , -.Nm archive_entry_set_uid , -.Nm archive_entry_set_uname , -.Nm archive_entry_size , -.Nm archive_entry_sourcepath , -.Nm archive_entry_stat , -.Nm archive_entry_symlink , -.Nm archive_entry_uid , -.Nm archive_entry_uname -.Nd functions for manipulating archive entry descriptions +.Nd functions for managing archive entry descriptions .Sh SYNOPSIS .In archive_entry.h -.Ft void -.Fo archive_entry_acl_add_entry -.Fa "struct archive_entry *" -.Fa "int type" -.Fa "int permset" -.Fa "int tag" -.Fa "int qual" -.Fa "const char *name" -.Fc -.Ft void -.Fo archive_entry_acl_add_entry_w -.Fa "struct archive_entry *" -.Fa "int type" -.Fa "int permset" -.Fa "int tag" -.Fa "int qual" -.Fa "const wchar_t *name" -.Fc -.Ft void -.Fn archive_entry_acl_clear "struct archive_entry *" -.Ft int -.Fn archive_entry_acl_count "struct archive_entry *" "int type" -.Ft int -.Fo archive_entry_acl_next -.Fa "struct archive_entry *" -.Fa "int want_type" -.Fa "int *type" -.Fa "int *permset" -.Fa "int *tag" -.Fa "int *qual" -.Fa "const char **name" -.Fc -.Ft int -.Fo archive_entry_acl_next_w -.Fa "struct archive_entry *" -.Fa "int want_type" -.Fa "int *type" -.Fa "int *permset" -.Fa "int *tag" -.Fa "int *qual" -.Fa "const wchar_t **name" -.Fc -.Ft int -.Fn archive_entry_acl_reset "struct archive_entry *" "int want_type" -.Ft const wchar_t * -.Fn archive_entry_acl_text_w "struct archive_entry *" "int flags" -.Ft time_t -.Fn archive_entry_atime "struct archive_entry *" -.Ft long -.Fn archive_entry_atime_nsec "struct archive_entry *" .Ft "struct archive_entry *" .Fn archive_entry_clear "struct archive_entry *" .Ft struct archive_entry * .Fn archive_entry_clone "struct archive_entry *" -.Ft const char * * -.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const char *" -.Ft const wchar_t * -.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const wchar_t *" -.Ft void -.Fn archive_entry_copy_gname "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_copy_gname_w "struct archive_entry *" "const wchar_t *" -.Ft void -.Fn archive_entry_copy_hardlink "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_copy_hardlink_w "struct archive_entry *" "const wchar_t *" -.Ft void -.Fn archive_entry_copy_sourcepath "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_copy_pathname_w "struct archive_entry *" "const wchar_t *" -.Ft void -.Fn archive_entry_copy_stat "struct archive_entry *" "const struct stat *" -.Ft void -.Fn archive_entry_copy_symlink "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_copy_symlink_w "struct archive_entry *" "const wchar_t *" -.Ft void -.Fn archive_entry_copy_uname "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_copy_uname_w "struct archive_entry *" "const wchar_t *" -.Ft dev_t -.Fn archive_entry_dev "struct archive_entry *" -.Ft dev_t -.Fn archive_entry_devmajor "struct archive_entry *" -.Ft dev_t -.Fn archive_entry_devminor "struct archive_entry *" -.Ft mode_t -.Fn archive_entry_filetype "struct archive_entry *" -.Ft void -.Fo archive_entry_fflags -.Fa "struct archive_entry *" -.Fa "unsigned long *set" -.Fa "unsigned long *clear" -.Fc -.Ft const char * -.Fn archive_entry_fflags_text "struct archive_entry *" .Ft void .Fn archive_entry_free "struct archive_entry *" -.Ft const char * -.Fn archive_entry_gname "struct archive_entry *" -.Ft const char * -.Fn archive_entry_hardlink "struct archive_entry *" -.Ft ino_t -.Fn archive_entry_ino "struct archive_entry *" -.Ft mode_t -.Fn archive_entry_mode "struct archive_entry *" -.Ft time_t -.Fn archive_entry_mtime "struct archive_entry *" -.Ft long -.Fn archive_entry_mtime_nsec "struct archive_entry *" -.Ft unsigned int -.Fn archive_entry_nlink "struct archive_entry *" .Ft struct archive_entry * .Fn archive_entry_new "void" -.Ft const char * -.Fn archive_entry_pathname "struct archive_entry *" -.Ft const wchar_t * -.Fn archive_entry_pathname_w "struct archive_entry *" -.Ft dev_t -.Fn archive_entry_rdev "struct archive_entry *" -.Ft dev_t -.Fn archive_entry_rdevmajor "struct archive_entry *" -.Ft dev_t -.Fn archive_entry_rdevminor "struct archive_entry *" -.Ft void -.Fn archive_entry_set_dev "struct archive_entry *" "dev_t" -.Ft void -.Fn archive_entry_set_devmajor "struct archive_entry *" "dev_t" -.Ft void -.Fn archive_entry_set_devminor "struct archive_entry *" "dev_t" -.Ft void -.Fn archive_entry_set_filetype "struct archive_entry *" "unsigned int" -.Ft void -.Fo archive_entry_set_fflags -.Fa "struct archive_entry *" -.Fa "unsigned long set" -.Fa "unsigned long clear" -.Fc -.Ft void -.Fn archive_entry_set_gid "struct archive_entry *" "gid_t" -.Ft void -.Fn archive_entry_set_gname "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_set_hardlink "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_set_ino "struct archive_entry *" "unsigned long" -.Ft void -.Fn archive_entry_set_link "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_set_mode "struct archive_entry *" "mode_t" -.Ft void -.Fn archive_entry_set_mtime "struct archive_entry *" "time_t" "long nanos" -.Ft void -.Fn archive_entry_set_nlink "struct archive_entry *" "unsigned int" -.Ft void -.Fn archive_entry_set_pathname "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_set_rdev "struct archive_entry *" "dev_t" -.Ft void -.Fn archive_entry_set_rdevmajor "struct archive_entry *" "dev_t" -.Ft void -.Fn archive_entry_set_rdevminor "struct archive_entry *" "dev_t" -.Ft void -.Fn archive_entry_set_size "struct archive_entry *" "int64_t" -.Ft void -.Fn archive_entry_set_symlink "struct archive_entry *" "const char *" -.Ft void -.Fn archive_entry_set_uid "struct archive_entry *" "uid_t" -.Ft void -.Fn archive_entry_set_uname "struct archive_entry *" "const char *" -.Ft int64_t -.Fn archive_entry_size "struct archive_entry *" -.Ft const char * -.Fn archive_entry_sourcepath "struct archive_entry *" -.Ft const struct stat * -.Fn archive_entry_stat "struct archive_entry *" -.Ft const char * -.Fn archive_entry_symlink "struct archive_entry *" -.Ft const char * -.Fn archive_entry_uname "struct archive_entry *" .Sh DESCRIPTION These functions create and manipulate data objects that represent entries within an archive. @@ -322,8 +79,24 @@ Allocate and return a blank .Tn struct archive_entry object. .El -.Ss Set and Get Functions -Most of the functions here set or read entries in an object. +.Ss Function groups +Due to high number of functions, the accessor functions can be found in +man pages grouped by the purpose. +.Bl -tag -width ".Xr archive_entry_perms 3" +.It Xr archive_entry_acl 3 +Access Control List manipulation +.It Xr archive_entry_paths 3 +Path name manipulation +.It Xr archive_entry_perms 3 +User, group and mode manipulation +.It Xr archive_entry_stat 3 +Files not in the other groups and copying to/from +.Vt struct stat . +.It Xr archive_entry time 3 +Time field manipulation +.El +.Pp +Most of the functions set or read entries in an object. Such functions have one of the following forms: .Bl -tag -compact -width indent .It Fn archive_entry_set_XXXX @@ -352,81 +125,15 @@ 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: -.Bl -tag -compact -width indent -.It Fn archive_entry_set_link -This function sets the symlink field if it is already set. -Otherwise, it sets the hardlink field. -.It Fn archive_entry_filetype , Fn archive_entry_set_filetype -These allow reading and writing of the file type information -stored in the mode value without affecting the permission bits. -.It Fn archive_entry_perm , Fn archive_entry_set_perm -These allow reading and writing the permission bits stored -in the mode value without affecting the file type information. -.El -.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 -.Xr fflagstostr 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 -.Fn archive_entry_copy_fflags_text -and -.Fn archive_entry_copy_fflags_text_w -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 -.Xr strtofflags 3 , -which stops parsing at the first unrecognized name.) -.Ss ACL Handling -XXX This needs serious help. -XXX -.Pp -An -.Dq 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 EXAMPLE .\" .Sh RETURN VALUES .\" .Sh ERRORS .Sh SEE ALSO -.Xr archive 3 +.Xr archive 3 , +.Xr archive_entry_acl 3 , +.Xr archive_entry_paths 3 , +.Xr archive_entry_perms 3 , +.Xr archive_entry_time 3 .Sh HISTORY The .Nm libarchive