| blob | 6b1b270f1a50e2298841a389cd5a19a170095f26 |
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: src/lib/libarchive/archive_entry.3,v 1.15 2007/07/15 19:10:34 kientzle Exp $
26 .\"
27 .Dd December 15, 2003
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_w ,
44 .Nm archive_entry_copy_gname ,
45 .Nm archive_entry_copy_gname_w ,
46 .Nm archive_entry_copy_hardlink ,
47 .Nm archive_entry_copy_hardlink_w ,
48 .Nm archive_entry_copy_pathname_w ,
49 .Nm archive_entry_copy_stat ,
50 .Nm archive_entry_copy_symlink ,
51 .Nm archive_entry_copy_symlink_w ,
52 .Nm archive_entry_copy_uname ,
53 .Nm archive_entry_copy_uname_w ,
54 .Nm archive_entry_dev ,
55 .Nm archive_entry_devmajor ,
56 .Nm archive_entry_devminor ,
57 .Nm archive_entry_filetype ,
58 .Nm archive_entry_fflags ,
59 .Nm archive_entry_fflags_text ,
60 .Nm archive_entry_free ,
61 .Nm archive_entry_gid ,
62 .Nm archive_entry_gname ,
63 .Nm archive_entry_hardlink ,
64 .Nm archive_entry_ino ,
65 .Nm archive_entry_mode ,
66 .Nm archive_entry_mtime ,
67 .Nm archive_entry_mtime_nsec ,
68 .Nm archive_entry_nlink ,
69 .Nm archive_entry_new ,
70 .Nm archive_entry_pathname ,
71 .Nm archive_entry_pathname_w ,
72 .Nm archive_entry_rdev ,
73 .Nm archive_entry_rdevmajor ,
74 .Nm archive_entry_rdevminor ,
75 .Nm archive_entry_set_atime ,
76 .Nm archive_entry_set_ctime ,
77 .Nm archive_entry_set_dev ,
78 .Nm archive_entry_set_devmajor ,
79 .Nm archive_entry_set_devminor ,
80 .Nm archive_entry_set_filetype ,
81 .Nm archive_entry_set_fflags ,
82 .Nm archive_entry_set_gid ,
83 .Nm archive_entry_set_gname ,
84 .Nm archive_entry_set_hardlink ,
85 .Nm archive_entry_set_link ,
86 .Nm archive_entry_set_mode ,
87 .Nm archive_entry_set_mtime ,
88 .Nm archive_entry_set_pathname ,
89 .Nm archive_entry_set_rdevmajor ,
90 .Nm archive_entry_set_rdevminor ,
91 .Nm archive_entry_set_size ,
92 .Nm archive_entry_set_symlink ,
93 .Nm archive_entry_set_uid ,
94 .Nm archive_entry_set_uname ,
95 .Nm archive_entry_size ,
96 .Nm archive_entry_stat ,
97 .Nm archive_entry_symlink ,
98 .Nm archive_entry_uid ,
99 .Nm archive_entry_uname
100 .Nd functions for manipulating archive entry descriptions
101 .Sh SYNOPSIS
102 .In archive_entry.h
103 .Ft void
104 .Fn archive_entry_acl_add_entry "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const char *name"
105 .Ft void
106 .Fn archive_entry_acl_add_entry_w "struct archive_entry *" "int type" "int permset" "int tag" "int qual" "const wchar_t *name"
107 .Ft void
108 .Fn archive_entry_acl_clear "struct archive_entry *"
109 .Ft int
110 .Fn archive_entry_acl_count "struct archive_entry *" "int type"
111 .Ft int
112 .Fn archive_entry_acl_next "struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const char **name"
113 .Ft int
114 .Fn archive_entry_acl_next_w "struct archive_entry *" "int want_type" "int *type" "int *permset" "int *tag" "int *qual" "const wchar_t **name"
115 .Ft int
116 .Fn archive_entry_acl_reset "struct archive_entry *" "int want_type"
117 .Ft const wchar_t *
118 .Fn archive_entry_acl_text_w "struct archive_entry *" "int flags"
119 .Ft time_t
120 .Fn archive_entry_atime "struct archive_entry *"
121 .Ft long
122 .Fn archive_entry_atime_nsec "struct archive_entry *"
123 .Ft "struct archive_entry *"
124 .Fn archive_entry_clear "struct archive_entry *"
125 .Ft struct archive_entry *
126 .Fn archive_entry_clone "struct archive_entry *"
127 .Ft const wchar_t *
128 .Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const wchar_t *"
129 .Ft void
130 .Fn archive_entry_copy_gname "struct archive_entry *" "const char *"
131 .Ft void
132 .Fn archive_entry_copy_gname_w "struct archive_entry *" "const wchar_t *"
133 .Ft void
134 .Fn archive_entry_copy_hardlink "struct archive_entry *" "const char *"
135 .Ft void
136 .Fn archive_entry_copy_hardlink_w "struct archive_entry *" "const wchar_t *"
137 .Ft void
138 .Fn archive_entry_copy_pathname_w "struct archive_entry *" "const wchar_t *"
139 .Ft void
140 .Fn archive_entry_copy_stat "struct archive_entry *" "const struct stat *"
141 .Ft void
142 .Fn archive_entry_copy_symlink "struct archive_entry *" "const char *"
143 .Ft void
144 .Fn archive_entry_copy_symlink_w "struct archive_entry *" "const wchar_t *"
145 .Ft void
146 .Fn archive_entry_copy_uname "struct archive_entry *" "const char *"
147 .Ft void
148 .Fn archive_entry_copy_uname_w "struct archive_entry *" "const wchar_t *"
149 .Ft dev_t
150 .Fn archive_entry_dev "struct archive_entry *"
151 .Ft dev_t
152 .Fn archive_entry_devmajor "struct archive_entry *"
153 .Ft dev_t
154 .Fn archive_entry_devminor "struct archive_entry *"
155 .Ft mode_t
156 .Fn archive_entry_filetype "struct archive_entry *"
157 .Ft void
158 .Fn archive_entry_fflags "struct archive_entry *" "unsigned long *set" "unsigned long *clear"
159 .Ft const char *
160 .Fn archive_entry_fflags_text "struct archive_entry *"
161 .Ft void
162 .Fn archive_entry_free "struct archive_entry *"
163 .Ft const char *
164 .Fn archive_entry_gname "struct archive_entry *"
165 .Ft const char *
166 .Fn archive_entry_hardlink "struct archive_entry *"
167 .Ft ino_t
168 .Fn archive_entry_ino "struct archive_entry *"
169 .Ft mode_t
170 .Fn archive_entry_mode "struct archive_entry *"
171 .Ft time_t
172 .Fn archive_entry_mtime "struct archive_entry *"
173 .Ft long
174 .Fn archive_entry_mtime_nsec "struct archive_entry *"
175 .Ft unsigned int
176 .Fn archive_entry_nlink "struct archive_entry *"
177 .Ft struct archive_entry *
178 .Fn archive_entry_new "void"
179 .Ft const char *
180 .Fn archive_entry_pathname "struct archive_entry *"
181 .Ft const wchar_t *
182 .Fn archive_entry_pathname_w "struct archive_entry *"
183 .Ft dev_t
184 .Fn archive_entry_rdev "struct archive_entry *"
185 .Ft dev_t
186 .Fn archive_entry_rdevmajor "struct archive_entry *"
187 .Ft dev_t
188 .Fn archive_entry_rdevminor "struct archive_entry *"
189 .Ft void
190 .Fn archive_entry_set_dev "struct archive_entry *" "dev_t"
191 .Ft void
192 .Fn archive_entry_set_devmajor "struct archive_entry *" "dev_t"
193 .Ft void
194 .Fn archive_entry_set_devminor "struct archive_entry *" "dev_t"
195 .Ft void
196 .Fn archive_entry_set_filetype "struct archive_entry *" "unsigned int"
197 .Ft void
198 .Fn archive_entry_set_fflags "struct archive_entry *" "unsigned long set" "unsigned long clear"
199 .Ft void
200 .Fn archive_entry_set_gid "struct archive_entry *" "gid_t"
201 .Ft void
202 .Fn archive_entry_set_gname "struct archive_entry *" "const char *"
203 .Ft void
204 .Fn archive_entry_set_hardlink "struct archive_entry *" "const char *"
205 .Ft void
206 .Fn archive_entry_set_ino "struct archive_entry *" "unsigned long"
207 .Ft void
208 .Fn archive_entry_set_link "struct archive_entry *" "const char *"
209 .Ft void
210 .Fn archive_entry_set_mode "struct archive_entry *" "mode_t"
211 .Ft void
212 .Fn archive_entry_set_mtime "struct archive_entry *" "time_t" "long nanos"
213 .Ft void
214 .Fn archive_entry_set_nlink "struct archive_entry *" "unsigned int"
215 .Ft void
216 .Fn archive_entry_set_pathname "struct archive_entry *" "const char *"
217 .Ft void
218 .Fn archive_entry_set_rdev "struct archive_entry *" "dev_t"
219 .Ft void
220 .Fn archive_entry_set_rdevmajor "struct archive_entry *" "dev_t"
221 .Ft void
222 .Fn archive_entry_set_rdevminor "struct archive_entry *" "dev_t"
223 .Ft void
224 .Fn archive_entry_set_size "struct archive_entry *" "int64_t"
225 .Ft void
226 .Fn archive_entry_set_symlink "struct archive_entry *" "const char *"
227 .Ft void
228 .Fn archive_entry_set_uid "struct archive_entry *" "uid_t"
229 .Ft void
230 .Fn archive_entry_set_uname "struct archive_entry *" "const char *"
231 .Ft int64_t
232 .Fn archive_entry_size "struct archive_entry *"
233 .Ft const struct stat *
234 .Fn archive_entry_stat "struct archive_entry *"
235 .Ft const char *
236 .Fn archive_entry_symlink "struct archive_entry *"
237 .Ft const char *
238 .Fn archive_entry_uname "struct archive_entry *"
239 .Sh DESCRIPTION
240 These functions create and manipulate data objects that
241 represent entries within an archive.
242 You can think of a
243 .Tn struct archive_entry
244 as a heavy-duty version of
245 .Tn struct stat :
246 it includes everything from
247 .Tn struct stat
248 plus associated pathname, textual group and user names, etc.
249 These objects are used by
250 .Xr libarchive 3
251 to represent the metadata associated with a particular
252 entry in an archive.
253 .Ss Create and Destroy
254 There are functions to allocate, destroy, clear, and copy
255 .Va archive_entry
256 objects:
257 .Bl -tag -compact -width indent
258 .It Fn archive_entry_clear
259 Erases the object, resetting all internal fields to the
260 same state as a newly-created object.
261 This is provided to allow you to quickly recycle objects
262 without thrashing the heap.
263 .It Fn archive_entry_clone
264 A deep copy operation; all text fields are duplicated.
265 .It Fn archive_entry_free
266 Releases the
267 .Tn struct archive_entry
268 object.
269 .It Fn archive_entry_new
270 Allocate and return a blank
271 .Tn struct archive_entry
272 object.
273 .El
274 .Ss Set and Get Functions
275 Most of the functions here set or read entries in an object.
276 Such functions have one of the following forms:
277 .Bl -tag -compact -width indent
278 .It Fn archive_entry_set_XXXX
279 Stores the provided data in the object.
280 In particular, for strings, the pointer is stored,
281 not the referenced string.
282 .It Fn archive_entry_copy_XXXX
283 As above, except that the referenced data is copied
284 into the object.
285 .It Fn archive_entry_XXXX
286 Returns the specified data.
287 In the case of strings, a const-qualified pointer to
288 the string is returned.
289 .El
290 String data can be set or accessed as wide character strings
291 or normal
292 .Va char
293 strings.
294 The functions that use wide character strings are suffixed with
295 .Cm _w .
296 Note that these are different representations of the same data:
297 For example, if you store a narrow string and read the corresponding
298 wide string, the object will transparently convert formats
299 using the current locale.
300 Similarly, if you store a wide string and then store a
301 narrow string for the same data, the previously-set wide string will
302 be discarded in favor of the new data.
303 .Pp
304 There are a few set/get functions that merit additional description:
305 .Bl -tag -compact -width indent
306 .It Fn archive_entry_set_link
307 This function sets the symlink field if it is already set.
308 Otherwise, it sets the hardlink field.
309 .El
310 .Ss File Flags
311 File flags are transparently converted between a bitmap
312 representation and a textual format.
313 For example, if you set the bitmap and ask for text, the library
314 will build a canonical text format.
315 However, if you set a text format and request a text format,
316 you will get back the same text, even if it is ill-formed.
317 If you need to canonicalize a textual flags string, you should first set the
318 text form, then request the bitmap form, then use that to set the bitmap form.
319 Setting the bitmap format will clear the internal text representation
320 and force it to be reconstructed when you next request the text form.
321 .Pp
322 The bitmap format consists of two integers, one containing bits
323 that should be set, the other specifying bits that should be
324 cleared.
325 Bits not mentioned in either bitmap will be ignored.
326 Usually, the bitmap of bits to be cleared will be set to zero.
327 In unusual circumstances, you can force a fully-specified set
328 of file flags by setting the bitmap of flags to clear to the complement
329 of the bitmap of flags to set.
330 (This differs from
331 .Xr fflagstostr 3 ,
332 which only includes names for set bits.)
333 Converting a bitmap to a textual string is a platform-specific
334 operation; bits that are not meaningful on the current platform
335 will be ignored.
336 .Pp
337 The canonical text format is a comma-separated list of flag names.
338 The
339 .Fn archive_entry_copy_fflags_text_w
340 function parses the provided text and sets the internal bitmap values.
341 This is a platform-specific operation; names that are not meaningful
342 on the current platform will be ignored.
343 The function returns a pointer to the start of the first name that was not
344 recognized, or NULL if every name was recognized.
345 Note that every name--including names that follow an unrecognized name--will
346 be evaluated, and the bitmaps will be set to reflect every name that is
347 recognized.
348 (In particular, this differs from
349 .Xr strtofflags 3 ,
350 which stops parsing at the first unrecognized name.)
351 .Ss ACL Handling
352 XXX This needs serious help.
353 XXX
354 .Pp
355 An
356 .Dq Access Control List
357 (ACL) is a list of permissions that grant access to particular users or
358 groups beyond what would normally be provided by standard POSIX mode bits.
359 The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL
360 specification.
361 In particular, POSIX.1e draft 17 specifies several different formats, but
362 none of those formats include both textual user/group names and numeric
363 UIDs/GIDs.
364 .Pp
365 XXX explain ACL stuff XXX
366 .\" .Sh EXAMPLE
367 .\" .Sh RETURN VALUES
368 .\" .Sh ERRORS
369 .Sh SEE ALSO
370 .Xr archive 3
371 .Sh HISTORY
372 The
373 .Nm libarchive
374 library first appeared in
375 .Fx 5.3 .
376 .Sh AUTHORS
377 .An -nosplit
378 The
379 .Nm libarchive
380 library was written by
381 .An Tim Kientzle Aq kientzle@acm.org .
382 .\" .Sh BUGS