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