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