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