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