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