1.\" Copyright (c) 2003-2007 Tim Kientzle 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd May 12, 2008 28.Dt ARCHIVE_ENTRY 3 29.Os 30.Sh NAME 31.Nm archive_entry_acl_add_entry , 32.Nm archive_entry_acl_add_entry_w , 33.Nm archive_entry_acl_clear , 34.Nm archive_entry_acl_count , 35.Nm archive_entry_acl_next , 36.Nm archive_entry_acl_next_w , 37.Nm archive_entry_acl_reset , 38.Nm archive_entry_acl_text_w , 39.Nm archive_entry_atime , 40.Nm archive_entry_atime_nsec , 41.Nm archive_entry_clear , 42.Nm archive_entry_clone , 43.Nm archive_entry_copy_fflags_text , 44.Nm archive_entry_copy_fflags_text_w , 45.Nm archive_entry_copy_gname , 46.Nm archive_entry_copy_gname_w , 47.Nm archive_entry_copy_hardlink , 48.Nm archive_entry_copy_hardlink_w , 49.Nm archive_entry_copy_link , 50.Nm archive_entry_copy_link_w , 51.Nm archive_entry_copy_pathname_w , 52.Nm archive_entry_copy_sourcepath , 53.Nm archive_entry_copy_stat , 54.Nm archive_entry_copy_symlink , 55.Nm archive_entry_copy_symlink_w , 56.Nm archive_entry_copy_uname , 57.Nm archive_entry_copy_uname_w , 58.Nm archive_entry_dev , 59.Nm archive_entry_devmajor , 60.Nm archive_entry_devminor , 61.Nm archive_entry_filetype , 62.Nm archive_entry_fflags , 63.Nm archive_entry_fflags_text , 64.Nm archive_entry_free , 65.Nm archive_entry_gid , 66.Nm archive_entry_gname , 67.Nm archive_entry_hardlink , 68.Nm archive_entry_ino , 69.Nm archive_entry_mode , 70.Nm archive_entry_mtime , 71.Nm archive_entry_mtime_nsec , 72.Nm archive_entry_nlink , 73.Nm archive_entry_new , 74.Nm archive_entry_pathname , 75.Nm archive_entry_pathname_w , 76.Nm archive_entry_rdev , 77.Nm archive_entry_rdevmajor , 78.Nm archive_entry_rdevminor , 79.Nm archive_entry_set_atime , 80.Nm archive_entry_set_ctime , 81.Nm archive_entry_set_dev , 82.Nm archive_entry_set_devmajor , 83.Nm archive_entry_set_devminor , 84.Nm archive_entry_set_filetype , 85.Nm archive_entry_set_fflags , 86.Nm archive_entry_set_gid , 87.Nm archive_entry_set_gname , 88.Nm archive_entry_set_hardlink , 89.Nm archive_entry_set_link , 90.Nm archive_entry_set_mode , 91.Nm archive_entry_set_mtime , 92.Nm archive_entry_set_pathname , 93.Nm archive_entry_set_rdevmajor , 94.Nm archive_entry_set_rdevminor , 95.Nm archive_entry_set_size , 96.Nm archive_entry_set_symlink , 97.Nm archive_entry_set_uid , 98.Nm archive_entry_set_uname , 99.Nm archive_entry_size , 100.Nm archive_entry_sourcepath , 101.Nm archive_entry_stat , 102.Nm archive_entry_symlink , 103.Nm archive_entry_uid , 104.Nm archive_entry_uname 105.Nd functions for manipulating archive entry descriptions 106.Sh SYNOPSIS 107.In archive_entry.h 108.Ft void 109.Fo archive_entry_acl_add_entry 110.Fa "struct archive_entry *" 111.Fa "int type" 112.Fa "int permset" 113.Fa "int tag" 114.Fa "int qual" 115.Fa "const char *name" 116.Fc 117.Ft void 118.Fo archive_entry_acl_add_entry_w 119.Fa "struct archive_entry *" 120.Fa "int type" 121.Fa "int permset" 122.Fa "int tag" 123.Fa "int qual" 124.Fa "const wchar_t *name" 125.Fc 126.Ft void 127.Fn archive_entry_acl_clear "struct archive_entry *" 128.Ft int 129.Fn archive_entry_acl_count "struct archive_entry *" "int type" 130.Ft int 131.Fo archive_entry_acl_next 132.Fa "struct archive_entry *" 133.Fa "int want_type" 134.Fa "int *type" 135.Fa "int *permset" 136.Fa "int *tag" 137.Fa "int *qual" 138.Fa "const char **name" 139.Fc 140.Ft int 141.Fo archive_entry_acl_next_w 142.Fa "struct archive_entry *" 143.Fa "int want_type" 144.Fa "int *type" 145.Fa "int *permset" 146.Fa "int *tag" 147.Fa "int *qual" 148.Fa "const wchar_t **name" 149.Fc 150.Ft int 151.Fn archive_entry_acl_reset "struct archive_entry *" "int want_type" 152.Ft const wchar_t * 153.Fn archive_entry_acl_text_w "struct archive_entry *" "int flags" 154.Ft time_t 155.Fn archive_entry_atime "struct archive_entry *" 156.Ft long 157.Fn archive_entry_atime_nsec "struct archive_entry *" 158.Ft "struct archive_entry *" 159.Fn archive_entry_clear "struct archive_entry *" 160.Ft struct archive_entry * 161.Fn archive_entry_clone "struct archive_entry *" 162.Ft const char * * 163.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const char *" 164.Ft const wchar_t * 165.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const wchar_t *" 166.Ft void 167.Fn archive_entry_copy_gname "struct archive_entry *" "const char *" 168.Ft void 169.Fn archive_entry_copy_gname_w "struct archive_entry *" "const wchar_t *" 170.Ft void 171.Fn archive_entry_copy_hardlink "struct archive_entry *" "const char *" 172.Ft void 173.Fn archive_entry_copy_hardlink_w "struct archive_entry *" "const wchar_t *" 174.Ft void 175.Fn archive_entry_copy_sourcepath "struct archive_entry *" "const char *" 176.Ft void 177.Fn archive_entry_copy_pathname_w "struct archive_entry *" "const wchar_t *" 178.Ft void 179.Fn archive_entry_copy_stat "struct archive_entry *" "const struct stat *" 180.Ft void 181.Fn archive_entry_copy_symlink "struct archive_entry *" "const char *" 182.Ft void 183.Fn archive_entry_copy_symlink_w "struct archive_entry *" "const wchar_t *" 184.Ft void 185.Fn archive_entry_copy_uname "struct archive_entry *" "const char *" 186.Ft void 187.Fn archive_entry_copy_uname_w "struct archive_entry *" "const wchar_t *" 188.Ft dev_t 189.Fn archive_entry_dev "struct archive_entry *" 190.Ft dev_t 191.Fn archive_entry_devmajor "struct archive_entry *" 192.Ft dev_t 193.Fn archive_entry_devminor "struct archive_entry *" 194.Ft mode_t 195.Fn archive_entry_filetype "struct archive_entry *" 196.Ft void 197.Fo archive_entry_fflags 198.Fa "struct archive_entry *" 199.Fa "unsigned long *set" 200.Fa "unsigned long *clear" 201.Fc 202.Ft const char * 203.Fn archive_entry_fflags_text "struct archive_entry *" 204.Ft void 205.Fn archive_entry_free "struct archive_entry *" 206.Ft const char * 207.Fn archive_entry_gname "struct archive_entry *" 208.Ft const char * 209.Fn archive_entry_hardlink "struct archive_entry *" 210.Ft ino_t 211.Fn archive_entry_ino "struct archive_entry *" 212.Ft mode_t 213.Fn archive_entry_mode "struct archive_entry *" 214.Ft time_t 215.Fn archive_entry_mtime "struct archive_entry *" 216.Ft long 217.Fn archive_entry_mtime_nsec "struct archive_entry *" 218.Ft unsigned int 219.Fn archive_entry_nlink "struct archive_entry *" 220.Ft struct archive_entry * 221.Fn archive_entry_new "void" 222.Ft const char * 223.Fn archive_entry_pathname "struct archive_entry *" 224.Ft const wchar_t * 225.Fn archive_entry_pathname_w "struct archive_entry *" 226.Ft dev_t 227.Fn archive_entry_rdev "struct archive_entry *" 228.Ft dev_t 229.Fn archive_entry_rdevmajor "struct archive_entry *" 230.Ft dev_t 231.Fn archive_entry_rdevminor "struct archive_entry *" 232.Ft void 233.Fn archive_entry_set_dev "struct archive_entry *" "dev_t" 234.Ft void 235.Fn archive_entry_set_devmajor "struct archive_entry *" "dev_t" 236.Ft void 237.Fn archive_entry_set_devminor "struct archive_entry *" "dev_t" 238.Ft void 239.Fn archive_entry_set_filetype "struct archive_entry *" "unsigned int" 240.Ft void 241.Fo archive_entry_set_fflags 242.Fa "struct archive_entry *" 243.Fa "unsigned long set" 244.Fa "unsigned long clear" 245.Fc 246.Ft void 247.Fn archive_entry_set_gid "struct archive_entry *" "gid_t" 248.Ft void 249.Fn archive_entry_set_gname "struct archive_entry *" "const char *" 250.Ft void 251.Fn archive_entry_set_hardlink "struct archive_entry *" "const char *" 252.Ft void 253.Fn archive_entry_set_ino "struct archive_entry *" "unsigned long" 254.Ft void 255.Fn archive_entry_set_link "struct archive_entry *" "const char *" 256.Ft void 257.Fn archive_entry_set_mode "struct archive_entry *" "mode_t" 258.Ft void 259.Fn archive_entry_set_mtime "struct archive_entry *" "time_t" "long nanos" 260.Ft void 261.Fn archive_entry_set_nlink "struct archive_entry *" "unsigned int" 262.Ft void 263.Fn archive_entry_set_pathname "struct archive_entry *" "const char *" 264.Ft void 265.Fn archive_entry_set_rdev "struct archive_entry *" "dev_t" 266.Ft void 267.Fn archive_entry_set_rdevmajor "struct archive_entry *" "dev_t" 268.Ft void 269.Fn archive_entry_set_rdevminor "struct archive_entry *" "dev_t" 270.Ft void 271.Fn archive_entry_set_size "struct archive_entry *" "int64_t" 272.Ft void 273.Fn archive_entry_set_symlink "struct archive_entry *" "const char *" 274.Ft void 275.Fn archive_entry_set_uid "struct archive_entry *" "uid_t" 276.Ft void 277.Fn archive_entry_set_uname "struct archive_entry *" "const char *" 278.Ft int64_t 279.Fn archive_entry_size "struct archive_entry *" 280.Ft const char * 281.Fn archive_entry_sourcepath "struct archive_entry *" 282.Ft const struct stat * 283.Fn archive_entry_stat "struct archive_entry *" 284.Ft const char * 285.Fn archive_entry_symlink "struct archive_entry *" 286.Ft const char * 287.Fn archive_entry_uname "struct archive_entry *" 288.Sh DESCRIPTION 289These functions create and manipulate data objects that 290represent entries within an archive. 291You can think of a 292.Tn struct archive_entry 293as a heavy-duty version of 294.Tn struct stat : 295it includes everything from 296.Tn struct stat 297plus associated pathname, textual group and user names, etc. 298These objects are used by 299.Xr libarchive 3 300to represent the metadata associated with a particular 301entry in an archive. 302.Ss Create and Destroy 303There are functions to allocate, destroy, clear, and copy 304.Va archive_entry 305objects: 306.Bl -tag -compact -width indent 307.It Fn archive_entry_clear 308Erases the object, resetting all internal fields to the 309same state as a newly-created object. 310This is provided to allow you to quickly recycle objects 311without thrashing the heap. 312.It Fn archive_entry_clone 313A deep copy operation; all text fields are duplicated. 314.It Fn archive_entry_free 315Releases the 316.Tn struct archive_entry 317object. 318.It Fn archive_entry_new 319Allocate and return a blank 320.Tn struct archive_entry 321object. 322.El 323.Ss Set and Get Functions 324Most of the functions here set or read entries in an object. 325Such functions have one of the following forms: 326.Bl -tag -compact -width indent 327.It Fn archive_entry_set_XXXX 328Stores the provided data in the object. 329In particular, for strings, the pointer is stored, 330not the referenced string. 331.It Fn archive_entry_copy_XXXX 332As above, except that the referenced data is copied 333into the object. 334.It Fn archive_entry_XXXX 335Returns the specified data. 336In the case of strings, a const-qualified pointer to 337the string is returned. 338.El 339String data can be set or accessed as wide character strings 340or normal 341.Va char 342strings. 343The functions that use wide character strings are suffixed with 344.Cm _w . 345Note that these are different representations of the same data: 346For example, if you store a narrow string and read the corresponding 347wide string, the object will transparently convert formats 348using the current locale. 349Similarly, if you store a wide string and then store a 350narrow string for the same data, the previously-set wide string will 351be discarded in favor of the new data. 352.Pp 353There are a few set/get functions that merit additional description: 354.Bl -tag -compact -width indent 355.It Fn archive_entry_set_link 356This function sets the symlink field if it is already set. 357Otherwise, it sets the hardlink field. 358.El 359.Ss File Flags 360File flags are transparently converted between a bitmap 361representation and a textual format. 362For example, if you set the bitmap and ask for text, the library 363will build a canonical text format. 364However, if you set a text format and request a text format, 365you will get back the same text, even if it is ill-formed. 366If you need to canonicalize a textual flags string, you should first set the 367text form, then request the bitmap form, then use that to set the bitmap form. 368Setting the bitmap format will clear the internal text representation 369and force it to be reconstructed when you next request the text form. 370.Pp 371The bitmap format consists of two integers, one containing bits 372that should be set, the other specifying bits that should be 373cleared. 374Bits not mentioned in either bitmap will be ignored. 375Usually, the bitmap of bits to be cleared will be set to zero. 376In unusual circumstances, you can force a fully-specified set 377of file flags by setting the bitmap of flags to clear to the complement 378of the bitmap of flags to set. 379(This differs from 380.Xr fflagstostr 3 , 381which only includes names for set bits.) 382Converting a bitmap to a textual string is a platform-specific 383operation; bits that are not meaningful on the current platform 384will be ignored. 385.Pp 386The canonical text format is a comma-separated list of flag names. 387The 388.Fn archive_entry_copy_fflags_text 389and 390.Fn archive_entry_copy_fflags_text_w 391functions parse the provided text and sets the internal bitmap values. 392This is a platform-specific operation; names that are not meaningful 393on the current platform will be ignored. 394The function returns a pointer to the start of the first name that was not 395recognized, or NULL if every name was recognized. 396Note that every name--including names that follow an unrecognized name--will 397be evaluated, and the bitmaps will be set to reflect every name that is 398recognized. 399(In particular, this differs from 400.Xr strtofflags 3 , 401which stops parsing at the first unrecognized name.) 402.Ss ACL Handling 403XXX This needs serious help. 404XXX 405.Pp 406An 407.Dq Access Control List 408(ACL) is a list of permissions that grant access to particular users or 409groups beyond what would normally be provided by standard POSIX mode bits. 410The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL 411specification. 412In particular, POSIX.1e draft 17 specifies several different formats, but 413none of those formats include both textual user/group names and numeric 414UIDs/GIDs. 415.Pp 416XXX explain ACL stuff XXX 417.\" .Sh EXAMPLE 418.\" .Sh RETURN VALUES 419.\" .Sh ERRORS 420.Sh SEE ALSO 421.Xr archive 3 422.Sh HISTORY 423The 424.Nm libarchive 425library first appeared in 426.Fx 5.3 . 427.Sh AUTHORS 428.An -nosplit 429The 430.Nm libarchive 431library was written by 432.An Tim Kientzle Aq kientzle@acm.org . 433.\" .Sh BUGS 434