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