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