1
.\" Copyright (c) 2003-2007 Tim Kientzle
2
.\" All rights reserved.
4
.\" Redistribution and use in source and binary forms, with or without
5
.\" modification, are permitted provided that the following conditions
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.
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
25
.\" $FreeBSD: src/lib/libarchive/archive_entry.3,v 1.18 2008/05/26 17:00:22 kientzle Exp $
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
109
.Fo archive_entry_acl_add_entry
110
.Fa "struct archive_entry *"
115
.Fa "const char *name"
118
.Fo archive_entry_acl_add_entry_w
119
.Fa "struct archive_entry *"
124
.Fa "const wchar_t *name"
127
.Fn archive_entry_acl_clear "struct archive_entry *"
129
.Fn archive_entry_acl_count "struct archive_entry *" "int type"
131
.Fo archive_entry_acl_next
132
.Fa "struct archive_entry *"
138
.Fa "const char **name"
141
.Fo archive_entry_acl_next_w
142
.Fa "struct archive_entry *"
148
.Fa "const wchar_t **name"
151
.Fn archive_entry_acl_reset "struct archive_entry *" "int want_type"
153
.Fn archive_entry_acl_text_w "struct archive_entry *" "int flags"
155
.Fn archive_entry_atime "struct archive_entry *"
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 *"
163
.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const char *"
165
.Fn archive_entry_copy_fflags_text_w "struct archive_entry *" "const wchar_t *"
167
.Fn archive_entry_copy_gname "struct archive_entry *" "const char *"
169
.Fn archive_entry_copy_gname_w "struct archive_entry *" "const wchar_t *"
171
.Fn archive_entry_copy_hardlink "struct archive_entry *" "const char *"
173
.Fn archive_entry_copy_hardlink_w "struct archive_entry *" "const wchar_t *"
175
.Fn archive_entry_copy_sourcepath "struct archive_entry *" "const char *"
177
.Fn archive_entry_copy_pathname_w "struct archive_entry *" "const wchar_t *"
179
.Fn archive_entry_copy_stat "struct archive_entry *" "const struct stat *"
181
.Fn archive_entry_copy_symlink "struct archive_entry *" "const char *"
183
.Fn archive_entry_copy_symlink_w "struct archive_entry *" "const wchar_t *"
185
.Fn archive_entry_copy_uname "struct archive_entry *" "const char *"
187
.Fn archive_entry_copy_uname_w "struct archive_entry *" "const wchar_t *"
189
.Fn archive_entry_dev "struct archive_entry *"
191
.Fn archive_entry_devmajor "struct archive_entry *"
193
.Fn archive_entry_devminor "struct archive_entry *"
195
.Fn archive_entry_filetype "struct archive_entry *"
197
.Fo archive_entry_fflags
198
.Fa "struct archive_entry *"
199
.Fa "unsigned long *set"
200
.Fa "unsigned long *clear"
203
.Fn archive_entry_fflags_text "struct archive_entry *"
205
.Fn archive_entry_free "struct archive_entry *"
207
.Fn archive_entry_gname "struct archive_entry *"
209
.Fn archive_entry_hardlink "struct archive_entry *"
211
.Fn archive_entry_ino "struct archive_entry *"
213
.Fn archive_entry_mode "struct archive_entry *"
215
.Fn archive_entry_mtime "struct archive_entry *"
217
.Fn archive_entry_mtime_nsec "struct archive_entry *"
219
.Fn archive_entry_nlink "struct archive_entry *"
220
.Ft struct archive_entry *
221
.Fn archive_entry_new "void"
223
.Fn archive_entry_pathname "struct archive_entry *"
225
.Fn archive_entry_pathname_w "struct archive_entry *"
227
.Fn archive_entry_rdev "struct archive_entry *"
229
.Fn archive_entry_rdevmajor "struct archive_entry *"
231
.Fn archive_entry_rdevminor "struct archive_entry *"
233
.Fn archive_entry_set_dev "struct archive_entry *" "dev_t"
235
.Fn archive_entry_set_devmajor "struct archive_entry *" "dev_t"
237
.Fn archive_entry_set_devminor "struct archive_entry *" "dev_t"
239
.Fn archive_entry_set_filetype "struct archive_entry *" "unsigned int"
241
.Fo archive_entry_set_fflags
242
.Fa "struct archive_entry *"
243
.Fa "unsigned long set"
244
.Fa "unsigned long clear"
247
.Fn archive_entry_set_gid "struct archive_entry *" "gid_t"
249
.Fn archive_entry_set_gname "struct archive_entry *" "const char *"
251
.Fn archive_entry_set_hardlink "struct archive_entry *" "const char *"
253
.Fn archive_entry_set_ino "struct archive_entry *" "unsigned long"
255
.Fn archive_entry_set_link "struct archive_entry *" "const char *"
257
.Fn archive_entry_set_mode "struct archive_entry *" "mode_t"
259
.Fn archive_entry_set_mtime "struct archive_entry *" "time_t" "long nanos"
261
.Fn archive_entry_set_nlink "struct archive_entry *" "unsigned int"
263
.Fn archive_entry_set_pathname "struct archive_entry *" "const char *"
265
.Fn archive_entry_set_rdev "struct archive_entry *" "dev_t"
267
.Fn archive_entry_set_rdevmajor "struct archive_entry *" "dev_t"
269
.Fn archive_entry_set_rdevminor "struct archive_entry *" "dev_t"
271
.Fn archive_entry_set_size "struct archive_entry *" "int64_t"
273
.Fn archive_entry_set_symlink "struct archive_entry *" "const char *"
275
.Fn archive_entry_set_uid "struct archive_entry *" "uid_t"
277
.Fn archive_entry_set_uname "struct archive_entry *" "const char *"
279
.Fn archive_entry_size "struct archive_entry *"
281
.Fn archive_entry_sourcepath "struct archive_entry *"
282
.Ft const struct stat *
283
.Fn archive_entry_stat "struct archive_entry *"
285
.Fn archive_entry_symlink "struct archive_entry *"
287
.Fn archive_entry_uname "struct archive_entry *"
289
These functions create and manipulate data objects that
290
represent entries within an archive.
292
.Tn struct archive_entry
293
as a heavy-duty version of
295
it includes everything from
297
plus associated pathname, textual group and user names, etc.
298
These objects are used by
300
to represent the metadata associated with a particular
302
.Ss Create and Destroy
303
There are functions to allocate, destroy, clear, and copy
306
.Bl -tag -compact -width indent
307
.It Fn archive_entry_clear
308
Erases the object, resetting all internal fields to the
309
same state as a newly-created object.
310
This is provided to allow you to quickly recycle objects
311
without thrashing the heap.
312
.It Fn archive_entry_clone
313
A deep copy operation; all text fields are duplicated.
314
.It Fn archive_entry_free
316
.Tn struct archive_entry
318
.It Fn archive_entry_new
319
Allocate and return a blank
320
.Tn struct archive_entry
323
.Ss Set and Get Functions
324
Most of the functions here set or read entries in an object.
325
Such functions have one of the following forms:
326
.Bl -tag -compact -width indent
327
.It Fn archive_entry_set_XXXX
328
Stores the provided data in the object.
329
In particular, for strings, the pointer is stored,
330
not the referenced string.
331
.It Fn archive_entry_copy_XXXX
332
As above, except that the referenced data is copied
334
.It Fn archive_entry_XXXX
335
Returns the specified data.
336
In the case of strings, a const-qualified pointer to
337
the string is returned.
339
String data can be set or accessed as wide character strings
343
The functions that use wide character strings are suffixed with
345
Note that these are different representations of the same data:
346
For example, if you store a narrow string and read the corresponding
347
wide string, the object will transparently convert formats
348
using the current locale.
349
Similarly, if you store a wide string and then store a
350
narrow string for the same data, the previously-set wide string will
351
be discarded in favor of the new data.
353
There are a few set/get functions that merit additional description:
354
.Bl -tag -compact -width indent
355
.It Fn archive_entry_set_link
356
This function sets the symlink field if it is already set.
357
Otherwise, it sets the hardlink field.
360
File flags are transparently converted between a bitmap
361
representation and a textual format.
362
For example, if you set the bitmap and ask for text, the library
363
will build a canonical text format.
364
However, if you set a text format and request a text format,
365
you will get back the same text, even if it is ill-formed.
366
If you need to canonicalize a textual flags string, you should first set the
367
text form, then request the bitmap form, then use that to set the bitmap form.
368
Setting the bitmap format will clear the internal text representation
369
and force it to be reconstructed when you next request the text form.
371
The bitmap format consists of two integers, one containing bits
372
that should be set, the other specifying bits that should be
374
Bits not mentioned in either bitmap will be ignored.
375
Usually, the bitmap of bits to be cleared will be set to zero.
376
In unusual circumstances, you can force a fully-specified set
377
of file flags by setting the bitmap of flags to clear to the complement
378
of the bitmap of flags to set.
381
which only includes names for set bits.)
382
Converting a bitmap to a textual string is a platform-specific
383
operation; bits that are not meaningful on the current platform
386
The canonical text format is a comma-separated list of flag names.
388
.Fn archive_entry_copy_fflags_text
390
.Fn archive_entry_copy_fflags_text_w
391
functions parse the provided text and sets the internal bitmap values.
392
This is a platform-specific operation; names that are not meaningful
393
on the current platform will be ignored.
394
The function returns a pointer to the start of the first name that was not
395
recognized, or NULL if every name was recognized.
396
Note that every name--including names that follow an unrecognized name--will
397
be evaluated, and the bitmaps will be set to reflect every name that is
399
(In particular, this differs from
401
which stops parsing at the first unrecognized name.)
403
XXX This needs serious help.
407
.Dq Access Control List
408
(ACL) is a list of permissions that grant access to particular users or
409
groups beyond what would normally be provided by standard POSIX mode bits.
410
The ACL handling here addresses some deficiencies in the POSIX.1e draft 17 ACL
412
In particular, POSIX.1e draft 17 specifies several different formats, but
413
none of those formats include both textual user/group names and numeric
416
XXX explain ACL stuff XXX
418
.\" .Sh RETURN VALUES
425
library first appeared in
431
library was written by
432
.An Tim Kientzle Aq kientzle@acm.org .
added
removed
src/libarchive/libarchive/archive_entry.3
