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