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 Xo 178.Fn archive_write_disk_set_group_lookup , 179.Fn archive_write_disk_set_user_lookup 180.Xc 181The 182.Tn struct archive_entry 183objects contain both names and ids that can be used to identify users 184and groups. 185These names and ids describe the ownership of the file itself and 186also appear in ACL lists. 187By default, the library uses the ids and ignores the names, but 188this can be overridden by registering user and group lookup functions. 189To register, you must provide a lookup function which 190accepts both a name and id and returns a suitable id. 191You may also provide a 192.Tn void * 193pointer to a private data structure and a cleanup function for 194that data. 195The cleanup function will be invoked when the 196.Tn struct archive 197object is destroyed. 198.It Fn archive_write_disk_set_standard_lookup 199This convenience function installs a standard set of user 200and group lookup functions. 201These functions use 202.Xr getpwnam 3 203and 204.Xr getgrnam 3 205to convert names to ids, defaulting to the ids if the names cannot 206be looked up. 207These functions also implement a simple memory cache to reduce 208the number of calls to 209.Xr getpwnam 3 210and 211.Xr getgrnam 3 . 212.It Fn archive_write_header 213Build and write a header using the data in the provided 214.Tn struct archive_entry 215structure. 216See 217.Xr archive_entry 3 218for information on creating and populating 219.Tn struct archive_entry 220objects. 221.It Fn archive_write_data 222Write data corresponding to the header just written. 223Returns number of bytes written or -1 on error. 224.It Fn archive_write_finish_entry 225Close out the entry just written. 226Ordinarily, clients never need to call this, as it 227is called automatically by 228.Fn archive_write_next_header 229and 230.Fn archive_write_close 231as needed. 232.It Fn archive_write_close 233Set any attributes that could not be set during the initial restore. 234For example, directory timestamps are not restored initially because 235restoring a subsequent file would alter that timestamp. 236Similarly, non-writable directories are initially created with 237write permissions (so that their contents can be restored). 238The 239.Nm 240library maintains a list of all such deferred attributes and 241sets them when this function is invoked. 242.It Fn archive_write_finish 243Invokes 244.Fn archive_write_close 245if it was not invoked manually, then releases all resources. 246.El 247More information about the 248.Va struct archive 249object and the overall design of the library can be found in the 250.Xr libarchive 3 251overview. 252Many of these functions are also documented under 253.Xr archive_write 3 . 254.Sh RETURN VALUES 255Most functions return 256.Cm ARCHIVE_OK 257(zero) on success, or one of several non-zero 258error codes for errors. 259Specific error codes include: 260.Cm ARCHIVE_RETRY 261for operations that might succeed if retried, 262.Cm ARCHIVE_WARN 263for unusual conditions that do not prevent further operations, and 264.Cm ARCHIVE_FATAL 265for serious errors that make remaining operations impossible. 266The 267.Fn archive_errno 268and 269.Fn archive_error_string 270functions can be used to retrieve an appropriate error code and a 271textual error message. 272.Pp 273.Fn archive_write_disk_new 274returns a pointer to a newly-allocated 275.Tn struct archive 276object. 277.Pp 278.Fn archive_write_data 279returns a count of the number of bytes actually written. 280On error, -1 is returned and the 281.Fn archive_errno 282and 283.Fn archive_error_string 284functions will return appropriate values. 285.Sh SEE ALSO 286.Xr archive_read 3 , 287.Xr archive_write 3 , 288.Xr tar 1 , 289.Xr libarchive 3 290.Sh HISTORY 291The 292.Nm libarchive 293library first appeared in 294.Fx 5.3 . 295The 296.Nm archive_write_disk 297interface was added to 298.Nm libarchive 2.0 299and first appeared in 300.Fx 6.3 . 301.Sh AUTHORS 302.An -nosplit 303The 304.Nm libarchive 305library was written by 306.An Tim Kientzle Aq kientzle@acm.org . 307.Sh BUGS 308Directories are actually extracted in two distinct phases. 309Directories are created during 310.Fn archive_write_header , 311but final permissions are not set until 312.Fn archive_write_close . 313This separation is necessary to correctly handle borderline 314cases such as a non-writable directory containing 315files, but can cause unexpected results. 316In particular, directory permissions are not fully 317restored until the archive is closed. 318If you use 319.Xr chdir 2 320to change the current directory between calls to 321.Fn archive_read_extract 322or before calling 323.Fn archive_read_close , 324you may confuse the permission-setting logic with 325the result that directory permissions are restored 326incorrectly. 327.Pp 328The library attempts to create objects with filenames longer than 329.Cm PATH_MAX 330by creating prefixes of the full path and changing the current directory. 331Currently, this logic is limited in scope; the fixup pass does 332not work correctly for such objects and the symlink security check 333option disables the support for very long pathnames. 334.Pp 335Restoring the path 336.Pa aa/../bb 337does create each intermediate directory. 338In particular, the directory 339.Pa aa 340is created as well as the final object 341.Pa bb . 342In theory, this can be exploited to create an entire directory heirarchy 343with a single request. 344Of course, this does not work if the 345.Cm ARCHIVE_EXTRACT_NODOTDOT 346option is specified. 347.Pp 348Implicit directories are always created obeying the current umask. 349Explicit objects are created obeying the current umask unless 350.Cm ARCHIVE_EXTRACT_PERM 351is specified, in which case they current umask is ignored. 352.Pp 353SGID and SUID bits are restored only if the correct user and 354group could be set. 355If 356.Cm ARCHIVE_EXTRACT_OWNER 357is not specified, then no attempt is made to set the ownership. 358In this case, SGID and SUID bits are restored only if the 359user and group of the final object happen to match those specified 360in the entry. 361.Pp 362The 363.Dq standard 364user-id and group-id lookup functions are not the defaults because 365.Xr getgrnam 3 366and 367.Xr getpwnam 3 368are sometimes too large for particular applications. 369The current design allows the application author to use a more 370compact implementation when appropriate. 371.Pp 372There should be a corresponding 373.Nm archive_read_disk 374interface that walks a directory heirarchy and returns archive 375entry objects.