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