1.\" Copyright (c) 2003-2007 Tim Kientzle 2.\" Copyright (c) 2010 Joerg Sonnenberger 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/lib/libarchive/archive_entry.3,v 1.18 2008/05/26 17:00:22 kientzle Exp $ 27.\" 28.Dd Feburary 22, 2010 29.Dt ARCHIVE_ENTRY 3 30.Os 31.Sh NAME 32.Nm archive_entry_clear , 33.Nm archive_entry_clone , 34.Nm archive_entry_free , 35.Nm archive_entry_new , 36.Nd functions for managing archive entry descriptions 37.Sh SYNOPSIS 38.In archive_entry.h 39.Ft "struct archive_entry *" 40.Fn archive_entry_clear "struct archive_entry *" 41.Ft struct archive_entry * 42.Fn archive_entry_clone "struct archive_entry *" 43.Ft void 44.Fn archive_entry_free "struct archive_entry *" 45.Ft struct archive_entry * 46.Fn archive_entry_new "void" 47.Sh DESCRIPTION 48These functions create and manipulate data objects that 49represent entries within an archive. 50You can think of a 51.Tn struct archive_entry 52as a heavy-duty version of 53.Tn struct stat : 54it includes everything from 55.Tn struct stat 56plus associated pathname, textual group and user names, etc. 57These objects are used by 58.Xr libarchive 3 59to represent the metadata associated with a particular 60entry in an archive. 61.Ss Create and Destroy 62There are functions to allocate, destroy, clear, and copy 63.Va archive_entry 64objects: 65.Bl -tag -compact -width indent 66.It Fn archive_entry_clear 67Erases the object, resetting all internal fields to the 68same state as a newly-created object. 69This is provided to allow you to quickly recycle objects 70without thrashing the heap. 71.It Fn archive_entry_clone 72A deep copy operation; all text fields are duplicated. 73.It Fn archive_entry_free 74Releases the 75.Tn struct archive_entry 76object. 77.It Fn archive_entry_new 78Allocate and return a blank 79.Tn struct archive_entry 80object. 81.El 82.Ss Function groups 83Due to high number of functions, the accessor functions can be found in 84man pages grouped by the purpose. 85.Bl -tag -width ".Xr archive_entry_perms 3" 86.It Xr archive_entry_acl 3 87Access Control List manipulation 88.It Xr archive_entry_paths 3 89Path name manipulation 90.It Xr archive_entry_perms 3 91User, group and mode manipulation 92.It Xr archive_entry_stat 3 93Functions not in the other groups and copying to/from 94.Vt struct stat . 95.It Xr archive_entry_time 3 96Time field manipulation 97.El 98.Pp 99Most of the functions set or read entries in an object. 100Such functions have one of the following forms: 101.Bl -tag -compact -width indent 102.It Fn archive_entry_set_XXXX 103Stores the provided data in the object. 104In particular, for strings, the pointer is stored, 105not the referenced string. 106.It Fn archive_entry_copy_XXXX 107As above, except that the referenced data is copied 108into the object. 109.It Fn archive_entry_XXXX 110Returns the specified data. 111In the case of strings, a const-qualified pointer to 112the string is returned. 113.El 114String data can be set or accessed as wide character strings 115or normal 116.Va char 117strings. 118The functions that use wide character strings are suffixed with 119.Cm _w . 120Note that these are different representations of the same data: 121For example, if you store a narrow string and read the corresponding 122wide string, the object will transparently convert formats 123using the current locale. 124Similarly, if you store a wide string and then store a 125narrow string for the same data, the previously-set wide string will 126be discarded in favor of the new data. 127.Pp 128.\" .Sh EXAMPLE 129.\" .Sh RETURN VALUES 130.\" .Sh ERRORS 131.Sh SEE ALSO 132.Xr archive 3 , 133.Xr archive_entry_acl 3 , 134.Xr archive_entry_paths 3 , 135.Xr archive_entry_perms 3 , 136.Xr archive_entry_time 3 137.Sh HISTORY 138The 139.Nm libarchive 140library first appeared in 141.Fx 5.3 . 142.Sh AUTHORS 143.An -nosplit 144The 145.Nm libarchive 146library was written by 147.An Tim Kientzle Aq kientzle@acm.org . 148.\" .Sh BUGS 149