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