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