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