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