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