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