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