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$ 27.\" 28.Dd February 2, 2012 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 LIBRARY 38Streaming Archive Library (libarchive, -larchive) 39.Sh SYNOPSIS 40.In archive_entry.h 41.Ft "struct archive_entry *" 42.Fn archive_entry_clear "struct archive_entry *" 43.Ft struct archive_entry * 44.Fn archive_entry_clone "struct archive_entry *" 45.Ft void 46.Fn archive_entry_free "struct archive_entry *" 47.Ft struct archive_entry * 48.Fn archive_entry_new "void" 49.Sh DESCRIPTION 50These functions create and manipulate data objects that 51represent entries within an archive. 52You can think of a 53.Tn struct archive_entry 54as a heavy-duty version of 55.Tn struct stat : 56it includes everything from 57.Tn struct stat 58plus associated pathname, textual group and user names, etc. 59These objects are used by 60.Xr libarchive 3 61to represent the metadata associated with a particular 62entry in an archive. 63.Ss Create and Destroy 64There are functions to allocate, destroy, clear, and copy 65.Va archive_entry 66objects: 67.Bl -tag -compact -width indent 68.It Fn archive_entry_clear 69Erases the object, resetting all internal fields to the 70same state as a newly-created object. 71This is provided to allow you to quickly recycle objects 72without thrashing the heap. 73.It Fn archive_entry_clone 74A deep copy operation; all text fields are duplicated. 75.It Fn archive_entry_free 76Releases the 77.Tn struct archive_entry 78object. 79.It Fn archive_entry_new 80Allocate and return a blank 81.Tn struct archive_entry 82object. 83.El 84.Ss Function groups 85Due to high number of functions, the accessor functions can be found in 86man pages grouped by the purpose. 87.Bl -tag -width ".Xr archive_entry_perms 3" 88.It Xr archive_entry_acl 3 89Access Control List manipulation 90.It Xr archive_entry_paths 3 91Path name manipulation 92.It Xr archive_entry_perms 3 93User, group and mode manipulation 94.It Xr archive_entry_stat 3 95Functions not in the other groups and copying to/from 96.Vt struct stat . 97.It Xr archive_entry_time 3 98Time field manipulation 99.El 100.Pp 101Most of the functions set or read entries in an object. 102Such functions have one of the following forms: 103.Bl -tag -compact -width indent 104.It Fn archive_entry_set_XXXX 105Stores the provided data in the object. 106In particular, for strings, the pointer is stored, 107not the referenced string. 108.It Fn archive_entry_copy_XXXX 109As above, except that the referenced data is copied 110into the object. 111.It Fn archive_entry_XXXX 112Returns the specified data. 113In the case of strings, a const-qualified pointer to 114the string is returned. 115.El 116String data can be set or accessed as wide character strings 117or normal 118.Va char 119strings. 120The functions that use wide character strings are suffixed with 121.Cm _w . 122Note that these are different representations of the same data: 123For example, if you store a narrow string and read the corresponding 124wide string, the object will transparently convert formats 125using the current locale. 126Similarly, if you store a wide string and then store a 127narrow string for the same data, the previously-set wide string will 128be discarded in favor of the new data. 129.\" .Sh EXAMPLE 130.\" .Sh RETURN VALUES 131.\" .Sh ERRORS 132.Sh SEE ALSO 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.Xr libarchive 3 138.Sh HISTORY 139The 140.Nm libarchive 141library first appeared in 142.Fx 5.3 . 143.Sh AUTHORS 144.An -nosplit 145The 146.Nm libarchive 147library was written by 148.An Tim Kientzle Aq kientzle@acm.org . 149.\" .Sh BUGS 150