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