1.\" Copyright (c) 2003-2007 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: src/lib/libarchive/archive_write_disk.3,v 1.4 2008/09/04 05:22:00 kientzle Exp $ 26.\" 27.Dd August 5, 2008 28.Dt archive_write_disk 3 29.Os 30.Sh NAME 31.Nm archive_write_disk_new , 32.Nm archive_write_disk_set_options , 33.Nm archive_write_disk_set_skip_file , 34.Nm archive_write_disk_set_group_lookup , 35.Nm archive_write_disk_set_standard_lookup , 36.Nm archive_write_disk_set_user_lookup , 37.Nm archive_write_header , 38.Nm archive_write_data , 39.Nm archive_write_finish_entry , 40.Nm archive_write_close , 41.Nm archive_write_finish 42.Nd functions for creating objects on disk 43.Sh SYNOPSIS 44.In archive.h 45.Ft struct archive * 46.Fn archive_write_disk_new "void" 47.Ft int 48.Fn archive_write_disk_set_options "struct archive *" "int flags" 49.Ft int 50.Fn archive_write_disk_set_skip_file "struct archive *" "dev_t" "ino_t" 51.Ft int 52.Fo archive_write_disk_set_group_lookup 53.Fa "struct archive *" 54.Fa "void *" 55.Fa "gid_t (*)(void *, const char *gname, gid_t gid)" 56.Fa "void (*cleanup)(void *)" 57.Fc 58.Ft int 59.Fn archive_write_disk_set_standard_lookup "struct archive *" 60.Ft int 61.Fo archive_write_disk_set_user_lookup 62.Fa "struct archive *" 63.Fa "void *" 64.Fa "uid_t (*)(void *, const char *uname, uid_t uid)" 65.Fa "void (*cleanup)(void *)" 66.Fc 67.Ft int 68.Fn archive_write_header "struct archive *" "struct archive_entry *" 69.Ft ssize_t 70.Fn archive_write_data "struct archive *" "const void *" "size_t" 71.Ft int 72.Fn archive_write_finish_entry "struct archive *" 73.Ft int 74.Fn archive_write_close "struct archive *" 75.Ft int 76.Fn archive_write_finish "struct archive *" 77.Sh DESCRIPTION 78These functions provide a complete API for creating objects on 79disk from 80.Tn struct archive_entry 81descriptions. 82They are most naturally used when extracting objects from an archive 83using the 84.Fn archive_read 85interface. 86The general process is to read 87.Tn struct archive_entry 88objects from an archive, then write those objects to a 89.Tn struct archive 90object created using the 91.Fn archive_write_disk 92family functions. 93This interface is deliberately very similar to the 94.Fn archive_write 95interface used to write objects to a streaming archive. 96.Bl -tag -width indent 97.It Fn archive_write_disk_new 98Allocates and initializes a 99.Tn struct archive 100object suitable for writing objects to disk. 101.It Fn archive_write_disk_set_skip_file 102Records the device and inode numbers of a file that should not be 103overwritten. 104This is typically used to ensure that an extraction process does not 105overwrite the archive from which objects are being read. 106This capability is technically unnecessary but can be a significant 107performance optimization in practice. 108.It Fn archive_write_disk_set_options 109The options field consists of a bitwise OR of one or more of the 110following values: 111.Bl -tag -compact -width "indent" 112.It Cm ARCHIVE_EXTRACT_OWNER 113The user and group IDs should be set on the restored file. 114By default, the user and group IDs are not restored. 115.It Cm ARCHIVE_EXTRACT_PERM 116Full permissions (including SGID, SUID, and sticky bits) should 117be restored exactly as specified, without obeying the 118current umask. 119Note that SUID and SGID bits can only be restored if the 120user and group ID of the object on disk are correct. 121If 122.Cm ARCHIVE_EXTRACT_OWNER 123is not specified, then SUID and SGID bits will only be restored 124if the default user and group IDs of newly-created objects on disk 125happen to match those specified in the archive entry. 126By default, only basic permissions are restored, and umask is obeyed. 127.It Cm ARCHIVE_EXTRACT_TIME 128The timestamps (mtime, ctime, and atime) should be restored. 129By default, they are ignored. 130Note that restoring of atime is not currently supported. 131.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE 132Existing files on disk will not be overwritten. 133By default, existing regular files are truncated and overwritten; 134existing directories will have their permissions updated; 135other pre-existing objects are unlinked and recreated from scratch. 136.It Cm ARCHIVE_EXTRACT_UNLINK 137Existing files on disk will be unlinked before any attempt to 138create them. 139In some cases, this can prove to be a significant performance improvement. 140By default, existing files are truncated and rewritten, but 141the file is not recreated. 142In particular, the default behavior does not break existing hard links. 143.It Cm ARCHIVE_EXTRACT_ACL 144Attempt to restore ACLs. 145By default, extended ACLs are ignored. 146.It Cm ARCHIVE_EXTRACT_FFLAGS 147Attempt to restore extended file flags. 148By default, file flags are ignored. 149.It Cm ARCHIVE_EXTRACT_XATTR 150Attempt to restore POSIX.1e extended attributes. 151By default, they are ignored. 152.It Cm ARCHIVE_EXTRACT_SECURE_SYMLINKS 153Refuse to extract any object whose final location would be altered 154by a symlink on disk. 155This is intended to help guard against a variety of mischief 156caused by archives that (deliberately or otherwise) extract 157files outside of the current directory. 158The default is not to perform this check. 159If 160.Cm ARCHIVE_EXTRACT_UNLINK 161is specified together with this option, the library will 162remove any intermediate symlinks it finds and return an 163error only if such symlink could not be removed. 164.It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT 165Refuse to extract a path that contains a 166.Pa .. 167element anywhere within it. 168The default is to not refuse such paths. 169Note that paths ending in 170.Pa .. 171always cause an error, regardless of this flag. 172.It Cm ARCHIVE_EXTRACT_SPARSE 173Scan data for blocks of NUL bytes and try to recreate them with holes. 174This results in sparse files, independent of whether the archive format 175supports or uses them. 176.El 177.It Fn archive_write_disk_set_group_lookup , \ 178Fn archive_write_disk_set_user_lookup 179The 180.Tn struct archive_entry 181objects contain both names and ids that can be used to identify users 182and groups. 183These names and ids describe the ownership of the file itself and 184also appear in ACL lists. 185By default, the library uses the ids and ignores the names, but 186this can be overridden by registering user and group lookup functions. 187To register, you must provide a lookup function which 188accepts both a name and id and returns a suitable id. 189You may also provide a 190.Tn void * 191pointer to a private data structure and a cleanup function for 192that data. 193The cleanup function will be invoked when the 194.Tn struct archive 195object is destroyed. 196.It Fn archive_write_disk_set_standard_lookup 197This convenience function installs a standard set of user 198and group lookup functions. 199These functions use 200.Xr getpwnam 3 201and 202.Xr getgrnam 3 203to convert names to ids, defaulting to the ids if the names cannot 204be looked up. 205These functions also implement a simple memory cache to reduce 206the number of calls to 207.Xr getpwnam 3 208and 209.Xr getgrnam 3 . 210.It Fn archive_write_header 211Build and write a header using the data in the provided 212.Tn struct archive_entry 213structure. 214See 215.Xr archive_entry 3 216for information on creating and populating 217.Tn struct archive_entry 218objects. 219.It Fn archive_write_data 220Write data corresponding to the header just written. 221Returns number of bytes written or -1 on error. 222.It Fn archive_write_finish_entry 223Close out the entry just written. 224Ordinarily, clients never need to call this, as it 225is called automatically by 226.Fn archive_write_next_header 227and 228.Fn archive_write_close 229as needed. 230.It Fn archive_write_close 231Set any attributes that could not be set during the initial restore. 232For example, directory timestamps are not restored initially because 233restoring a subsequent file would alter that timestamp. 234Similarly, non-writable directories are initially created with 235write permissions (so that their contents can be restored). 236The 237.Nm 238library maintains a list of all such deferred attributes and 239sets them when this function is invoked. 240.It Fn archive_write_finish 241Invokes 242.Fn archive_write_close 243if it was not invoked manually, then releases all resources. 244.El 245More information about the 246.Va struct archive 247object and the overall design of the library can be found in the 248.Xr libarchive 3 249overview. 250Many of these functions are also documented under 251.Xr archive_write 3 . 252.Sh RETURN VALUES 253Most functions return 254.Cm ARCHIVE_OK 255(zero) on success, or one of several non-zero 256error codes for errors. 257Specific error codes include: 258.Cm ARCHIVE_RETRY 259for operations that might succeed if retried, 260.Cm ARCHIVE_WARN 261for unusual conditions that do not prevent further operations, and 262.Cm ARCHIVE_FATAL 263for serious errors that make remaining operations impossible. 264The 265.Fn archive_errno 266and 267.Fn archive_error_string 268functions can be used to retrieve an appropriate error code and a 269textual error message. 270.Pp 271.Fn archive_write_disk_new 272returns a pointer to a newly-allocated 273.Tn struct archive 274object. 275.Pp 276.Fn archive_write_data 277returns a count of the number of bytes actually written. 278On error, -1 is returned and the 279.Fn archive_errno 280and 281.Fn archive_error_string 282functions will return appropriate values. 283.Sh SEE ALSO 284.Xr archive_read 3 , 285.Xr archive_write 3 , 286.Xr tar 1 , 287.Xr libarchive 3 288.Sh HISTORY 289The 290.Nm libarchive 291library first appeared in 292.Fx 5.3 . 293The 294.Nm archive_write_disk 295interface was added to 296.Nm libarchive 2.0 297and first appeared in 298.Fx 6.3 . 299.Sh AUTHORS 300.An -nosplit 301The 302.Nm libarchive 303library was written by 304.An Tim Kientzle Aq Mt kientzle@acm.org . 305.Sh BUGS 306Directories are actually extracted in two distinct phases. 307Directories are created during 308.Fn archive_write_header , 309but final permissions are not set until 310.Fn archive_write_close . 311This separation is necessary to correctly handle borderline 312cases such as a non-writable directory containing 313files, but can cause unexpected results. 314In particular, directory permissions are not fully 315restored until the archive is closed. 316If you use 317.Xr chdir 2 318to change the current directory between calls to 319.Fn archive_read_extract 320or before calling 321.Fn archive_read_close , 322you may confuse the permission-setting logic with 323the result that directory permissions are restored 324incorrectly. 325.Pp 326The library attempts to create objects with filenames longer than 327.Cm PATH_MAX 328by creating prefixes of the full path and changing the current directory. 329Currently, this logic is limited in scope; the fixup pass does 330not work correctly for such objects and the symlink security check 331option disables the support for very long pathnames. 332.Pp 333Restoring the path 334.Pa aa/../bb 335does create each intermediate directory. 336In particular, the directory 337.Pa aa 338is created as well as the final object 339.Pa bb . 340In theory, this can be exploited to create an entire directory heirarchy 341with a single request. 342Of course, this does not work if the 343.Cm ARCHIVE_EXTRACT_NODOTDOT 344option is specified. 345.Pp 346Implicit directories are always created obeying the current umask. 347Explicit objects are created obeying the current umask unless 348.Cm ARCHIVE_EXTRACT_PERM 349is specified, in which case they current umask is ignored. 350.Pp 351SGID and SUID bits are restored only if the correct user and 352group could be set. 353If 354.Cm ARCHIVE_EXTRACT_OWNER 355is not specified, then no attempt is made to set the ownership. 356In this case, SGID and SUID bits are restored only if the 357user and group of the final object happen to match those specified 358in the entry. 359.Pp 360The 361.Dq standard 362user-id and group-id lookup functions are not the defaults because 363.Xr getgrnam 3 364and 365.Xr getpwnam 3 366are sometimes too large for particular applications. 367The current design allows the application author to use a more 368compact implementation when appropriate. 369.Pp 370There should be a corresponding 371.Nm archive_read_disk 372interface that walks a directory heirarchy and returns archive 373entry objects.