1.\" Copyright (c) 2003-2009 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: head/lib/libarchive/archive_read_disk.3 190957 2009-04-12 05:04:02Z kientzle $
26.\"
27.Dd March 10, 2009
28.Dt ARCHIVE_READ_DISK 3
29.Os
30.Sh NAME
31.Nm archive_read_disk_new ,
32.Nm archive_read_disk_set_symlink_logical ,
33.Nm archive_read_disk_set_symlink_physical ,
34.Nm archive_read_disk_set_symlink_hybrid ,
35.Nm archive_read_disk_entry_from_file ,
36.Nm archive_read_disk_gname ,
37.Nm archive_read_disk_uname ,
38.Nm archive_read_disk_set_uname_lookup ,
39.Nm archive_read_disk_set_gname_lookup ,
40.Nm archive_read_disk_set_standard_lookup ,
41.Nm archive_read_close ,
42.Nm archive_read_finish ,
43.Nm archive_read_free
44.Nd functions for reading objects from disk
45.Sh SYNOPSIS
46.In archive.h
47.Ft struct archive *
48.Fn archive_read_disk_new "void"
49.Ft int
50.Fn archive_read_disk_set_symlink_logical "struct archive *"
51.Ft int
52.Fn archive_read_disk_set_symlink_physical "struct archive *"
53.Ft int
54.Fn archive_read_disk_set_symlink_hybrid "struct archive *"
55.Ft int
56.Fn archive_read_disk_gname "struct archive *" "gid_t"
57.Ft int
58.Fn archive_read_disk_uname "struct archive *" "uid_t"
59.Ft int
60.Fo archive_read_disk_set_gname_lookup
61.Fa "struct archive *"
62.Fa "void *"
63.Fa "const char *(*lookup)(void *, gid_t)"
64.Fa "void (*cleanup)(void *)"
65.Fc
66.Ft int
67.Fo archive_read_disk_set_uname_lookup
68.Fa "struct archive *"
69.Fa "void *"
70.Fa "const char *(*lookup)(void *, uid_t)"
71.Fa "void (*cleanup)(void *)"
72.Fc
73.Ft int
74.Fn archive_read_disk_set_standard_lookup "struct archive *"
75.Ft int
76.Fo archive_read_disk_entry_from_file
77.Fa "struct archive *"
78.Fa "struct archive_entry *"
79.Fa "int fd"
80.Fa "const struct stat *"
81.Fc
82.Ft int
83.Fn archive_read_close "struct archive *"
84.Ft int
85.Fn archive_read_finish "struct archive *"
86.Ft int
87.Fn archive_read_free "struct archive *"
88.Sh DESCRIPTION
89These functions provide an API for reading information about
90objects on disk.
91In particular, they provide an interface for populating
92.Tn struct archive_entry
93objects.
94.Bl -tag -width indent
95.It Fn archive_read_disk_new
96Allocates and initializes a
97.Tn struct archive
98object suitable for reading object information from disk.
99.It Xo
100.Fn archive_read_disk_set_symlink_logical ,
101.Fn archive_read_disk_set_symlink_physical ,
102.Fn archive_read_disk_set_symlink_hybrid
103.Xc
104This sets the mode used for handling symbolic links.
105The
106.Dq logical
107mode follows all symbolic links.
108The
109.Dq physical
110mode does not follow any symbolic links.
111The
112.Dq hybrid
113mode currently behaves identically to the
114.Dq logical
115mode.
116.It Xo
117.Fn archive_read_disk_gname ,
118.Fn archive_read_disk_uname
119.Xc
120Returns a user or group name given a gid or uid value.
121By default, these always return a NULL string.
122.It Xo
123.Fn archive_read_disk_set_gname_lookup ,
124.Fn archive_read_disk_set_uname_lookup
125.Xc
126These allow you to override the functions used for
127user and group name lookups.
128You may also provide a
129.Tn void *
130pointer to a private data structure and a cleanup function for
131that data.
132The cleanup function will be invoked when the
133.Tn struct archive
134object is destroyed or when new lookup functions are registered.
135.It Fn archive_read_disk_set_standard_lookup
136This convenience function installs a standard set of user
137and group name lookup functions.
138These functions use
139.Xr getpwuid 3
140and
141.Xr getgrgid 3
142to convert ids to names, defaulting to NULL if the names cannot
143be looked up.
144These functions also implement a simple memory cache to reduce
145the number of calls to
146.Xr getpwuid 3
147and
148.Xr getgrgid 3 .
149.It Fn archive_read_disk_entry_from_file
150Populates a
151.Tn struct archive_entry
152object with information about a particular file.
153The
154.Tn archive_entry
155object must have already been created with
156.Xr archive_entry_new 3
157and at least one of the source path or path fields must already be set.
158(If both are set, the source path will be used.)
159.Pp
160Information is read from disk using the path name from the
161.Tn struct archive_entry
162object.
163If a file descriptor is provided, some information will be obtained using
164that file descriptor, on platforms that support the appropriate
165system calls.
166.Pp
167If a pointer to a
168.Tn struct stat
169is provided, information from that structure will be used instead
170of reading from the disk where appropriate.
171This can provide performance benefits in scenarios where
172.Tn struct stat
173information has already been read from the disk as a side effect
174of some other operation.
175(For example, directory traversal libraries often provide this information.)
176.Pp
177Where necessary, user and group ids are converted to user and group names
178using the currently registered lookup functions above.
179This affects the file ownership fields and ACL values in the
180.Tn struct archive_entry
181object.
182.It Fn archive_read_close
183Does nothing for
184.Tn archive_read_disk
185handles.
186.It Fn archive_read_finish
187This is a deprecated synonym for
188.Fn archive_read_free .
189.It Fn archive_read_free
190Invokes
191.Fn archive_read_close
192if it was not invoked manually, then releases all resources.
193.El
194More information about the
195.Va struct archive
196object and the overall design of the library can be found in the
197.Xr libarchive 3
198overview.
199.Sh EXAMPLE
200The following illustrates basic usage of the library by
201showing how to use it to copy an item on disk into an archive.
202.Bd -literal -offset indent
203void
204file_to_archive(struct archive *a, const char *name)
205{
206  char buff[8192];
207  size_t bytes_read;
208  struct archive *ard;
209  struct archive_entry *entry;
210  int fd;
211
212  ard = archive_read_disk_new();
213  archive_read_disk_set_standard_lookup(ard);
214  entry = archive_entry_new();
215  fd = open(name, O_RDONLY);
216  if (fd < 0)
217     return;
218  archive_entry_copy_pathname(entry, name);
219  archive_read_disk_entry_from_file(ard, entry, fd, NULL);
220  archive_write_header(a, entry);
221  while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
222    archive_write_data(a, buff, bytes_read);
223  archive_write_finish_entry(a);
224  archive_read_free(ard);
225  archive_entry_free(entry);
226}
227.Ed
228.Sh RETURN VALUES
229Most functions return
230.Cm ARCHIVE_OK
231(zero) on success, or one of several negative
232error codes for errors.
233Specific error codes include:
234.Cm ARCHIVE_RETRY
235for operations that might succeed if retried,
236.Cm ARCHIVE_WARN
237for unusual conditions that do not prevent further operations, and
238.Cm ARCHIVE_FATAL
239for serious errors that make remaining operations impossible.
240.Pp
241.Fn archive_read_disk_new
242returns a pointer to a newly-allocated
243.Tn struct archive
244object or NULL if the allocation failed for any reason.
245.Pp
246.Fn archive_read_disk_gname
247and
248.Fn archive_read_disk_uname
249return
250.Tn const char *
251pointers to the textual name or NULL if the lookup failed for any reason.
252The returned pointer points to internal storage that
253may be reused on the next call to either of these functions;
254callers should copy the string if they need to continue accessing it.
255.\"
256.Sh ERRORS
257Detailed error codes and textual descriptions are available from the
258.Fn archive_errno
259and
260.Fn archive_error_string
261functions.
262.\"
263.Sh SEE ALSO
264.Xr archive_read 3 ,
265.Xr archive_util 3 ,
266.Xr archive_write 3 ,
267.Xr archive_write_disk 3 ,
268.Xr tar 1 ,
269.Xr libarchive 3
270.Sh HISTORY
271The
272.Nm libarchive
273library first appeared in
274.Fx 5.3 .
275The
276.Nm archive_read_disk
277interface was added to
278.Nm libarchive 2.6
279and first appeared in
280.Fx 8.0 .
281.Sh AUTHORS
282.An -nosplit
283The
284.Nm libarchive
285library was written by
286.An Tim Kientzle Aq kientzle@FreeBSD.org .
287.Sh BUGS
288The
289.Dq standard
290user name and group name lookup functions are not the defaults because
291.Xr getgrgid 3
292and
293.Xr getpwuid 3
294are sometimes too large for particular applications.
295The current design allows the application author to use a more
296compact implementation when appropriate.
297.Pp
298The full list of metadata read from disk by
299.Fn archive_read_disk_entry_from_file
300is necessarily system-dependent.
301.Pp
302The
303.Fn archive_read_disk_entry_from_file
304function reads as much information as it can from disk.
305Some method should be provided to limit this so that clients who
306do not need ACLs, for instance, can avoid the extra work needed
307to look up such information.
308.Pp
309This API should provide a set of methods for walking a directory tree.
310That would make it a direct parallel of the
311.Xr archive_read 3
312API.
313When such methods are implemented, the
314.Dq hybrid
315symbolic link mode will make sense.
316