1<!-- Creator : groff version 1.22.4 --> 2<!-- CreationDate: Sun Aug 22 23:03:25 2021 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; vertical-align: top } 12 pre { margin-top: 0; margin-bottom: 0; vertical-align: top } 13 table { margin-top: 0; margin-bottom: 0; vertical-align: top } 14 h1 { text-align: center } 15</style> 16<title></title> 17</head> 18<body> 19 20<hr> 21 22 23<p>ARCHIVE_READ_DISK(3) BSD Library Functions Manual 24ARCHIVE_READ_DISK(3)</p> 25 26<p style="margin-top: 1em"><b>NAME</b></p> 27 28<p style="margin-left:6%;"><b>archive_read_disk_new</b>, 29<b>archive_read_disk_set_behavior</b>, 30<b>archive_read_disk_set_symlink_logical</b>, 31<b>archive_read_disk_set_symlink_physical</b>, 32<b>archive_read_disk_set_symlink_hybrid</b>, 33<b>archive_read_disk_entry_from_file</b>, 34<b>archive_read_disk_gname</b>, 35<b>archive_read_disk_uname</b>, 36<b>archive_read_disk_set_uname_lookup</b>, 37<b>archive_read_disk_set_gname_lookup</b>, 38<b>archive_read_disk_set_standard_lookup</b> — 39functions for reading objects from disk</p> 40 41<p style="margin-top: 1em"><b>LIBRARY</b></p> 42 43<p style="margin-left:6%;">Streaming Archive Library 44(libarchive, -larchive)</p> 45 46<p style="margin-top: 1em"><b>SYNOPSIS</b></p> 47 48<p style="margin-left:6%;"><b>#include 49<archive.h></b></p> 50 51<p style="margin-left:6%; margin-top: 1em"><i>struct 52archive *</i></p> 53 54 55<p style="margin-left:12%;"><b>archive_read_disk_new</b>(<i>void</i>);</p> 56 57<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 58 59 60<p style="margin-left:12%;"><b>archive_read_disk_set_behavior</b>(<i>struct archive *</i>, 61<i>int</i>);</p> 62 63<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 64 65 66<p style="margin-left:12%;"><b>archive_read_disk_set_symlink_logical</b>(<i>struct archive *</i>);</p> 67 68<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 69 70 71<p style="margin-left:12%;"><b>archive_read_disk_set_symlink_physical</b>(<i>struct archive *</i>);</p> 72 73<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 74 75 76<p style="margin-left:12%;"><b>archive_read_disk_set_symlink_hybrid</b>(<i>struct archive *</i>);</p> 77 78<p style="margin-left:6%; margin-top: 1em"><i>const char 79*</i></p> 80 81 82<p style="margin-left:12%;"><b>archive_read_disk_gname</b>(<i>struct archive *</i>, 83<i>gid_t</i>);</p> 84 85<p style="margin-left:6%; margin-top: 1em"><i>const char 86*</i></p> 87 88 89<p style="margin-left:12%;"><b>archive_read_disk_uname</b>(<i>struct archive *</i>, 90<i>uid_t</i>);</p> 91 92<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 93 94 95<p><b>archive_read_disk_set_gname_lookup</b>(<i>struct archive *</i>, 96<i>void *</i>, 97<i>const char *(*lookup)(void *, gid_t)</i>, 98<i>void (*cleanup)(void *)</i>);</p> 99 100<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 101 102 103<p><b>archive_read_disk_set_uname_lookup</b>(<i>struct archive *</i>, 104<i>void *</i>, 105<i>const char *(*lookup)(void *, uid_t)</i>, 106<i>void (*cleanup)(void *)</i>);</p> 107 108<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 109 110 111<p style="margin-left:12%;"><b>archive_read_disk_set_standard_lookup</b>(<i>struct archive *</i>);</p> 112 113<p style="margin-left:6%; margin-top: 1em"><i>int</i></p> 114 115 116<p><b>archive_read_disk_entry_from_file</b>(<i>struct archive *</i>, 117<i>struct archive_entry *</i>, <i>int fd</i>, 118<i>const struct stat *</i>);</p> 119 120<p style="margin-top: 1em"><b>DESCRIPTION</b></p> 121 122<p style="margin-left:6%;">These functions provide an API 123for reading information about objects on disk. In 124particular, they provide an interface for populating struct 125archive_entry objects.</p> 126 127 128<p style="margin-top: 1em"><b>archive_read_disk_new</b>()</p> 129 130<p style="margin-left:17%;">Allocates and initializes a 131struct archive object suitable for reading object 132information from disk.</p> 133 134 135<p style="margin-top: 1em"><b>archive_read_disk_set_behavior</b>()</p> 136 137<p style="margin-left:17%;">Configures various behavior 138options when reading entries from disk. The flags field 139consists of a bitwise OR of one or more of the following 140values:</p> 141 142<p><b>ARCHIVE_READDISK_HONOR_NODUMP</b></p> 143 144<p style="margin-left:27%;">Skip files and directories with 145the nodump file attribute (file flag) set. By default, the 146nodump file attribute is ignored.</p> 147 148<p><b>ARCHIVE_READDISK_MAC_COPYFILE</b></p> 149 150<p style="margin-left:27%;">Mac OS X specific. Read 151metadata (ACLs and extended attributes) with copyfile(3). By 152default, metadata is read using copyfile(3).</p> 153 154<p><b>ARCHIVE_READDISK_NO_ACL</b></p> 155 156<p style="margin-left:27%;">Do not read Access Control 157Lists. By default, ACLs are read from disk.</p> 158 159<p><b>ARCHIVE_READDISK_NO_FFLAGS</b></p> 160 161<p style="margin-left:27%;">Do not read file attributes 162(file flags). By default, file attributes are read from 163disk. See chattr(1) (Linux) or chflags(1) (FreeBSD, Mac OS 164X) for more information on file attributes.</p> 165 166<p><b>ARCHIVE_READDISK_NO_TRAVERSE_MOUNTS</b></p> 167 168<p style="margin-left:27%;">Do not traverse mount points. 169By default, mount points are traversed.</p> 170 171<p><b>ARCHIVE_READDISK_NO_XATTR</b></p> 172 173<p style="margin-left:27%;">Do not read extended file 174attributes (xattrs). By default, extended file attributes 175are read from disk. See xattr(7) (Linux), xattr(2) (Mac OS 176X), or getextattr(8) (FreeBSD) for more information on 177extended file attributes.</p> 178 179<p><b>ARCHIVE_READDISK_RESTORE_ATIME</b></p> 180 181<p style="margin-left:27%;">Restore access time of 182traversed files. By default, access time of traversed files 183is not restored.</p> 184 185 186<p style="margin-top: 1em"><b>archive_read_disk_set_symlink_logical</b>(), 187<b>archive_read_disk_set_symlink_physical</b>(), 188<b>archive_read_disk_set_symlink_hybrid</b>()</p> 189 190<p style="margin-left:17%;">This sets the mode used for 191handling symbolic links. The “logical” mode 192follows all symbolic links. The “physical” mode 193does not follow any symbolic links. The “hybrid” 194mode currently behaves identically to the 195“logical” mode.</p> 196 197 198<p style="margin-top: 1em"><b>archive_read_disk_gname</b>(), 199<b>archive_read_disk_uname</b>()</p> 200 201<p style="margin-left:17%;">Returns a user or group name 202given a gid or uid value. By default, these always return a 203NULL string.</p> 204 205 206<p style="margin-top: 1em"><b>archive_read_disk_set_gname_lookup</b>(), 207<b>archive_read_disk_set_uname_lookup</b>()</p> 208 209<p style="margin-left:17%;">These allow you to override the 210functions used for user and group name lookups. You may also 211provide a void * pointer to a private data structure and a 212cleanup function for that data. The cleanup function will be 213invoked when the struct archive object is destroyed or when 214new lookup functions are registered.</p> 215 216 217<p style="margin-top: 1em"><b>archive_read_disk_set_standard_lookup</b>()</p> 218 219<p style="margin-left:17%;">This convenience function 220installs a standard set of user and group name lookup 221functions. These functions use getpwuid(3) and getgrgid(3) 222to convert ids to names, defaulting to NULL if the names 223cannot be looked up. These functions also implement a simple 224memory cache to reduce the number of calls to getpwuid(3) 225and getgrgid(3).</p> 226 227 228<p style="margin-top: 1em"><b>archive_read_disk_entry_from_file</b>()</p> 229 230<p style="margin-left:17%;">Populates a struct 231archive_entry object with information about a particular 232file. The archive_entry object must have already been 233created with archive_entry_new(3) and at least one of the 234source path or path fields must already be set. (If both are 235set, the source path will be used.)</p> 236 237<p style="margin-left:17%; margin-top: 1em">Information is 238read from disk using the path name from the struct 239archive_entry object. If a file descriptor is provided, some 240information will be obtained using that file descriptor, on 241platforms that support the appropriate system calls.</p> 242 243<p style="margin-left:17%; margin-top: 1em">If a pointer to 244a struct stat is provided, information from that structure 245will be used instead of reading from the disk where 246appropriate. This can provide performance benefits in 247scenarios where struct stat information has already been 248read from the disk as a side effect of some other operation. 249(For example, directory traversal libraries often provide 250this information.)</p> 251 252<p style="margin-left:17%; margin-top: 1em">Where 253necessary, user and group ids are converted to user and 254group names using the currently-registered lookup functions 255above. This affects the file ownership fields and ACL values 256in the struct archive_entry object.</p> 257 258<p style="margin-left:6%;">More information about the 259<i>struct archive</i> object and the overall design of the 260library can be found in the libarchive(3) overview.</p> 261 262<p style="margin-top: 1em"><b>EXAMPLES</b></p> 263 264<p style="margin-left:6%;">The following illustrates basic 265usage of the library by showing how to use it to copy an 266item on disk into an archive.</p> 267 268<p style="margin-left:14%; margin-top: 1em">void <br> 269file_to_archive(struct archive *a, const char *name) <br> 270{ <br> 271char buff[8192]; <br> 272size_t bytes_read; <br> 273struct archive *ard; <br> 274struct archive_entry *entry; <br> 275int fd;</p> 276 277<p style="margin-left:14%; margin-top: 1em">ard = 278archive_read_disk_new(); <br> 279archive_read_disk_set_standard_lookup(ard); <br> 280entry = archive_entry_new(); <br> 281fd = open(name, O_RDONLY); <br> 282if (fd < 0) <br> 283return; <br> 284archive_entry_copy_pathname(entry, name); <br> 285archive_read_disk_entry_from_file(ard, entry, fd, NULL); 286<br> 287archive_write_header(a, entry); <br> 288while ((bytes_read = read(fd, buff, sizeof(buff))) > 0) 289<br> 290archive_write_data(a, buff, bytes_read); <br> 291archive_write_finish_entry(a); <br> 292archive_read_free(ard); <br> 293archive_entry_free(entry); <br> 294}</p> 295 296<p style="margin-top: 1em"><b>RETURN VALUES</b></p> 297 298<p style="margin-left:6%;">Most functions return 299<b>ARCHIVE_OK</b> (zero) on success, or one of several 300negative error codes for errors. Specific error codes 301include: <b>ARCHIVE_RETRY</b> for operations that might 302succeed if retried, <b>ARCHIVE_WARN</b> for unusual 303conditions that do not prevent further operations, and 304<b>ARCHIVE_FATAL</b> for serious errors that make remaining 305operations impossible.</p> 306 307 308<p style="margin-left:6%; margin-top: 1em"><b>archive_read_disk_new</b>() 309returns a pointer to a newly-allocated struct archive object 310or NULL if the allocation failed for any reason.</p> 311 312 313<p style="margin-left:6%; margin-top: 1em"><b>archive_read_disk_gname</b>() 314and <b>archive_read_disk_uname</b>() return const char * 315pointers to the textual name or NULL if the lookup failed 316for any reason. The returned pointer points to internal 317storage that may be reused on the next call to either of 318these functions; callers should copy the string if they need 319to continue accessing it.</p> 320 321<p style="margin-top: 1em"><b>ERRORS</b></p> 322 323<p style="margin-left:6%;">Detailed error codes and textual 324descriptions are available from the <b>archive_errno</b>() 325and <b>archive_error_string</b>() functions.</p> 326 327<p style="margin-top: 1em"><b>SEE ALSO</b></p> 328 329<p style="margin-left:6%;">tar(1), archive_read(3), 330archive_util(3), archive_write(3), archive_write_disk(3), 331libarchive(3)</p> 332 333<p style="margin-top: 1em"><b>HISTORY</b></p> 334 335<p style="margin-left:6%;">The <b>libarchive</b> library 336first appeared in FreeBSD 5.3. The 337<b>archive_read_disk</b> interface was added to 338<b>libarchive 2.6</b> and first appeared in 339FreeBSD 8.0.</p> 340 341<p style="margin-top: 1em"><b>AUTHORS</b></p> 342 343<p style="margin-left:6%;">The <b>libarchive</b> library 344was written by Tim Kientzle 345<kientzle@FreeBSD.org>.</p> 346 347<p style="margin-top: 1em"><b>BUGS</b></p> 348 349<p style="margin-left:6%;">The “standard” user 350name and group name lookup functions are not the defaults 351because getgrgid(3) and getpwuid(3) are sometimes too large 352for particular applications. The current design allows the 353application author to use a more compact implementation when 354appropriate.</p> 355 356<p style="margin-left:6%; margin-top: 1em">The full list of 357metadata read from disk by 358<b>archive_read_disk_entry_from_file</b>() is necessarily 359system-dependent.</p> 360 361<p style="margin-left:6%; margin-top: 1em">The 362<b>archive_read_disk_entry_from_file</b>() function reads as 363much information as it can from disk. Some method should be 364provided to limit this so that clients who do not need ACLs, 365for instance, can avoid the extra work needed to look up 366such information.</p> 367 368<p style="margin-left:6%; margin-top: 1em">This API should 369provide a set of methods for walking a directory tree. That 370would make it a direct parallel of the archive_read(3) API. 371When such methods are implemented, the “hybrid” 372symbolic link mode will make sense.</p> 373 374<p style="margin-left:6%; margin-top: 1em">BSD 375April 3, 2017 BSD</p> 376<hr> 377</body> 378</html> 379