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 April 3, 2017
28.Dt ARCHIVE_READ_DISK 3
29.Os
30.Sh NAME
31.Nm archive_read_disk_new ,
32.Nm archive_read_disk_set_behavior ,
33.Nm archive_read_disk_set_symlink_logical ,
34.Nm archive_read_disk_set_symlink_physical ,
35.Nm archive_read_disk_set_symlink_hybrid ,
36.Nm archive_read_disk_entry_from_file ,
37.Nm archive_read_disk_gname ,
38.Nm archive_read_disk_uname ,
39.Nm archive_read_disk_set_uname_lookup ,
40.Nm archive_read_disk_set_gname_lookup ,
41.Nm archive_read_disk_set_standard_lookup
42.Nd functions for reading objects from disk
43.Sh LIBRARY
44Streaming Archive Library (libarchive, -larchive)
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_behavior "struct archive *" "int"
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 const char *
58.Fn archive_read_disk_gname "struct archive *" "gid_t"
59.Ft const char *
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.Sh DESCRIPTION
85These functions provide an API for reading information about
86objects on disk.
87In particular, they provide an interface for populating
88.Tn struct archive_entry
89objects.
90.Bl -tag -width indent
91.It Fn archive_read_disk_new
92Allocates and initializes a
93.Tn struct archive
94object suitable for reading object information from disk.
95.It Fn archive_read_disk_set_behavior
96Configures various behavior options when reading entries from disk.
97The flags field consists of a bitwise OR of one or more of the
98following values:
99.Bl -tag -compact -width "indent"
100.It Cm ARCHIVE_READDISK_HONOR_NODUMP
101Skip files and directories with the nodump file attribute (file flag) set.
102By default, the nodump file attribute is ignored.
103.It Cm ARCHIVE_READDISK_MAC_COPYFILE
104Mac OS X specific.
105Read metadata (ACLs and extended attributes) with
106.Xr copyfile 3 .
107By default, metadata is read using
108.Xr copyfile 3 .
109.It Cm ARCHIVE_READDISK_NO_ACL
110Do not read Access Control Lists.
111By default, ACLs are read from disk.
112.It Cm ARCHIVE_READDISK_NO_FFLAGS
113Do not read file attributes (file flags).
114By default, file attributes are read from disk.
115See
116.Xr chattr 1
117.Pq Linux
118or
119.Xr chflags 1
120.Pq FreeBSD, Mac OS X
121for more information on file attributes.
122.It Cm ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS
123Do not traverse mount points.
124By default, mount points are traversed.
125.It Cm ARCHIVE_READDISK_NO_XATTR
126Do not read extended file attributes (xattrs).
127By default, extended file attributes are read from disk.
128See
129.Xr xattr 7
130.Pq Linux ,
131.Xr xattr 2
132.Pq Mac OS X ,
133or
134.Xr getextattr 8
135.Pq FreeBSD
136for more information on extended file attributes.
137.It Cm ARCHIVE_READDISK_RESTORE_ATIME
138Restore access time of traversed files.
139By default, access time of traversed files is not restored.
140.El
141.It Xo
142.Fn archive_read_disk_set_symlink_logical ,
143.Fn archive_read_disk_set_symlink_physical ,
144.Fn archive_read_disk_set_symlink_hybrid
145.Xc
146This sets the mode used for handling symbolic links.
147The
148.Dq logical
149mode follows all symbolic links.
150The
151.Dq physical
152mode does not follow any symbolic links.
153The
154.Dq hybrid
155mode currently behaves identically to the
156.Dq logical
157mode.
158.It Xo
159.Fn archive_read_disk_gname ,
160.Fn archive_read_disk_uname
161.Xc
162Returns a user or group name given a gid or uid value.
163By default, these always return a NULL string.
164.It Xo
165.Fn archive_read_disk_set_gname_lookup ,
166.Fn archive_read_disk_set_uname_lookup
167.Xc
168These allow you to override the functions used for
169user and group name lookups.
170You may also provide a
171.Tn void *
172pointer to a private data structure and a cleanup function for
173that data.
174The cleanup function will be invoked when the
175.Tn struct archive
176object is destroyed or when new lookup functions are registered.
177.It Fn archive_read_disk_set_standard_lookup
178This convenience function installs a standard set of user
179and group name lookup functions.
180These functions use
181.Xr getpwuid 3
182and
183.Xr getgrgid 3
184to convert ids to names, defaulting to NULL if the names cannot
185be looked up.
186These functions also implement a simple memory cache to reduce
187the number of calls to
188.Xr getpwuid 3
189and
190.Xr getgrgid 3 .
191.It Fn archive_read_disk_entry_from_file
192Populates a
193.Tn struct archive_entry
194object with information about a particular file.
195The
196.Tn archive_entry
197object must have already been created with
198.Xr archive_entry_new 3
199and at least one of the source path or path fields must already be set.
200(If both are set, the source path will be used.)
201.Pp
202Information is read from disk using the path name from the
203.Tn struct archive_entry
204object.
205If a file descriptor is provided, some information will be obtained using
206that file descriptor, on platforms that support the appropriate
207system calls.
208.Pp
209If a pointer to a
210.Tn struct stat
211is provided, information from that structure will be used instead
212of reading from the disk where appropriate.
213This can provide performance benefits in scenarios where
214.Tn struct stat
215information has already been read from the disk as a side effect
216of some other operation.
217(For example, directory traversal libraries often provide this information.)
218.Pp
219Where necessary, user and group ids are converted to user and group names
220using the currently-registered lookup functions above.
221This affects the file ownership fields and ACL values in the
222.Tn struct archive_entry
223object.
224.El
225More information about the
226.Va struct archive
227object and the overall design of the library can be found in the
228.Xr libarchive 3
229overview.
230.Sh EXAMPLES
231The following illustrates basic usage of the library by
232showing how to use it to copy an item on disk into an archive.
233.Bd -literal -offset indent
234void
235file_to_archive(struct archive *a, const char *name)
236{
237  char buff[8192];
238  size_t bytes_read;
239  struct archive *ard;
240  struct archive_entry *entry;
241  int fd;
242
243  ard = archive_read_disk_new();
244  archive_read_disk_set_standard_lookup(ard);
245  entry = archive_entry_new();
246  fd = open(name, O_RDONLY);
247  if (fd < 0)
248     return;
249  archive_entry_copy_pathname(entry, name);
250  archive_read_disk_entry_from_file(ard, entry, fd, NULL);
251  archive_write_header(a, entry);
252  while ((bytes_read = read(fd, buff, sizeof(buff))) > 0)
253    archive_write_data(a, buff, bytes_read);
254  archive_write_finish_entry(a);
255  archive_read_free(ard);
256  archive_entry_free(entry);
257}
258.Ed
259.Sh RETURN VALUES
260Most functions return
261.Cm ARCHIVE_OK
262(zero) on success, or one of several negative
263error codes for errors.
264Specific error codes include:
265.Cm ARCHIVE_RETRY
266for operations that might succeed if retried,
267.Cm ARCHIVE_WARN
268for unusual conditions that do not prevent further operations, and
269.Cm ARCHIVE_FATAL
270for serious errors that make remaining operations impossible.
271.Pp
272.Fn archive_read_disk_new
273returns a pointer to a newly-allocated
274.Tn struct archive
275object or NULL if the allocation failed for any reason.
276.Pp
277.Fn archive_read_disk_gname
278and
279.Fn archive_read_disk_uname
280return
281.Tn const char *
282pointers to the textual name or NULL if the lookup failed for any reason.
283The returned pointer points to internal storage that
284may be reused on the next call to either of these functions;
285callers should copy the string if they need to continue accessing it.
286.\"
287.Sh ERRORS
288Detailed error codes and textual descriptions are available from the
289.Fn archive_errno
290and
291.Fn archive_error_string
292functions.
293.\"
294.Sh SEE ALSO
295.Xr tar 1 ,
296.Xr archive_read 3 ,
297.Xr archive_util 3 ,
298.Xr archive_write 3 ,
299.Xr archive_write_disk 3 ,
300.Xr libarchive 3
301.Sh HISTORY
302The
303.Nm libarchive
304library first appeared in
305.Fx 5.3 .
306The
307.Nm archive_read_disk
308interface was added to
309.Nm libarchive 2.6
310and first appeared in
311.Fx 8.0 .
312.Sh AUTHORS
313.An -nosplit
314The
315.Nm libarchive
316library was written by
317.An Tim Kientzle Aq kientzle@FreeBSD.org .
318.Sh BUGS
319The
320.Dq standard
321user name and group name lookup functions are not the defaults because
322.Xr getgrgid 3
323and
324.Xr getpwuid 3
325are sometimes too large for particular applications.
326The current design allows the application author to use a more
327compact implementation when appropriate.
328.Pp
329The full list of metadata read from disk by
330.Fn archive_read_disk_entry_from_file
331is necessarily system-dependent.
332.Pp
333The
334.Fn archive_read_disk_entry_from_file
335function reads as much information as it can from disk.
336Some method should be provided to limit this so that clients who
337do not need ACLs, for instance, can avoid the extra work needed
338to look up such information.
339.Pp
340This API should provide a set of methods for walking a directory tree.
341That would make it a direct parallel of the
342.Xr archive_read 3
343API.
344When such methods are implemented, the
345.Dq hybrid
346symbolic link mode will make sense.
347