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 January 19, 2020 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. 117Restore metadata using 118.Xr copyfile 3 . 119By default, 120.Xr copyfile 3 121metadata is ignored. 122.It Cm ARCHIVE_EXTRACT_NO_OVERWRITE 123Existing files on disk will not be overwritten. 124By default, existing regular files are truncated and overwritten; 125existing directories will have their permissions updated; 126other pre-existing objects are unlinked and recreated from scratch. 127.It Cm ARCHIVE_EXTRACT_OWNER 128The user and group IDs should be set on the restored file. 129By default, the user and group IDs are not restored. 130.It Cm ARCHIVE_EXTRACT_PERM 131Full permissions (including SGID, SUID, and sticky bits) should 132be restored exactly as specified, without obeying the 133current umask. 134Note that SUID and SGID bits can only be restored if the 135user and group ID of the object on disk are correct. 136If 137.Cm ARCHIVE_EXTRACT_OWNER 138is not specified, then SUID and SGID bits will only be restored 139if the default user and group IDs of newly-created objects on disk 140happen to match those specified in the archive entry. 141By default, only basic permissions are restored, and umask is obeyed. 142.It Cm ARCHIVE_EXTRACT_SAFE_WRITES 143Extract files atomically, by first creating a unique temporary file and then 144renaming it to its required destination name. 145This avoids a race where an application might see a partial file (or no 146file) during extraction. 147.It Cm ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS 148Refuse to extract an absolute path. 149The default is to not refuse such paths. 150.It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT 151Refuse to extract a path that contains a 152.Pa .. 153element anywhere within it. 154The default is to not refuse such paths. 155Note that paths ending in 156.Pa .. 157always cause an error, regardless of this flag. 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_SPARSE 171Scan data for blocks of NUL bytes and try to recreate them with holes. 172This results in sparse files, independent of whether the archive format 173supports or uses them. 174.It Cm ARCHIVE_EXTRACT_TIME 175The timestamps (mtime, ctime, and atime) should be restored. 176By default, they are ignored. 177Note that restoring of atime is not currently supported. 178.It Cm ARCHIVE_EXTRACT_UNLINK 179Existing files on disk will be unlinked before any attempt to 180create them. 181In some cases, this can prove to be a significant performance improvement. 182By default, existing files are truncated and rewritten, but 183the file is not recreated. 184In particular, the default behavior does not break existing hard links. 185.It Cm ARCHIVE_EXTRACT_XATTR 186Attempt to restore extended file attributes. 187By default, they are ignored. 188See 189.Xr xattr 7 190.Pq Linux , 191.Xr xattr 2 192.Pq Mac OS X , 193or 194.Xr getextattr 8 195.Pq FreeBSD 196for more information on extended file attributes. 197.El 198.It Xo 199.Fn archive_write_disk_set_group_lookup , 200.Fn archive_write_disk_set_user_lookup 201.Xc 202The 203.Tn struct archive_entry 204objects contain both names and ids that can be used to identify users 205and groups. 206These names and ids describe the ownership of the file itself and 207also appear in ACL lists. 208By default, the library uses the ids and ignores the names, but 209this can be overridden by registering user and group lookup functions. 210To register, you must provide a lookup function which 211accepts both a name and id and returns a suitable id. 212You may also provide a 213.Tn void * 214pointer to a private data structure and a cleanup function for 215that data. 216The cleanup function will be invoked when the 217.Tn struct archive 218object is destroyed. 219.It Fn archive_write_disk_set_standard_lookup 220This convenience function installs a standard set of user 221and group lookup functions. 222These functions use 223.Xr getpwnam 3 224and 225.Xr getgrnam 3 226to convert names to ids, defaulting to the ids if the names cannot 227be looked up. 228These functions also implement a simple memory cache to reduce 229the number of calls to 230.Xr getpwnam 3 231and 232.Xr getgrnam 3 . 233.El 234More information about the 235.Va struct archive 236object and the overall design of the library can be found in the 237.Xr libarchive 3 238overview. 239Many of these functions are also documented under 240.Xr archive_write 3 . 241.Sh RETURN VALUES 242Most functions return 243.Cm ARCHIVE_OK 244(zero) on success, or one of several non-zero 245error codes for errors. 246Specific error codes include: 247.Cm ARCHIVE_RETRY 248for operations that might succeed if retried, 249.Cm ARCHIVE_WARN 250for unusual conditions that do not prevent further operations, and 251.Cm ARCHIVE_FATAL 252for serious errors that make remaining operations impossible. 253.Pp 254.Fn archive_write_disk_new 255returns a pointer to a newly-allocated 256.Tn struct archive 257object. 258.Pp 259.Fn archive_write_data 260returns a count of the number of bytes actually written, 261or 262.Li -1 263on error. 264.\" 265.Sh ERRORS 266Detailed error codes and textual descriptions are available from the 267.Fn archive_errno 268and 269.Fn archive_error_string 270functions. 271.\" 272.Sh SEE ALSO 273.Xr tar 1 , 274.Xr archive_read 3 , 275.Xr archive_write 3 , 276.Xr libarchive 3 277.Sh HISTORY 278The 279.Nm libarchive 280library first appeared in 281.Fx 5.3 . 282The 283.Nm archive_write_disk 284interface was added to 285.Nm libarchive 2.0 286and first appeared in 287.Fx 6.3 . 288.Sh AUTHORS 289.An -nosplit 290The 291.Nm libarchive 292library was written by 293.An Tim Kientzle Aq kientzle@acm.org . 294.Sh BUGS 295Directories are actually extracted in two distinct phases. 296Directories are created during 297.Fn archive_write_header , 298but final permissions are not set until 299.Fn archive_write_close . 300This separation is necessary to correctly handle borderline 301cases such as a non-writable directory containing 302files, but can cause unexpected results. 303In particular, directory permissions are not fully 304restored until the archive is closed. 305If you use 306.Xr chdir 2 307to change the current directory between calls to 308.Fn archive_read_extract 309or before calling 310.Fn archive_read_close , 311you may confuse the permission-setting logic with 312the result that directory permissions are restored 313incorrectly. 314.Pp 315The library attempts to create objects with filenames longer than 316.Cm PATH_MAX 317by creating prefixes of the full path and changing the current directory. 318Currently, this logic is limited in scope; the fixup pass does 319not work correctly for such objects and the symlink security check 320option disables the support for very long pathnames. 321.Pp 322Restoring the path 323.Pa aa/../bb 324does create each intermediate directory. 325In particular, the directory 326.Pa aa 327is created as well as the final object 328.Pa bb . 329In theory, this can be exploited to create an entire directory hierarchy 330with a single request. 331Of course, this does not work if the 332.Cm ARCHIVE_EXTRACT_NODOTDOT 333option is specified. 334.Pp 335Implicit directories are always created obeying the current umask. 336Explicit objects are created obeying the current umask unless 337.Cm ARCHIVE_EXTRACT_PERM 338is specified, in which case they current umask is ignored. 339.Pp 340SGID and SUID bits are restored only if the correct user and 341group could be set. 342If 343.Cm ARCHIVE_EXTRACT_OWNER 344is not specified, then no attempt is made to set the ownership. 345In this case, SGID and SUID bits are restored only if the 346user and group of the final object happen to match those specified 347in the entry. 348.Pp 349The 350.Dq standard 351user-id and group-id lookup functions are not the defaults because 352.Xr getgrnam 3 353and 354.Xr getpwnam 3 355are sometimes too large for particular applications. 356The current design allows the application author to use a more 357compact implementation when appropriate. 358.Pp 359There should be a corresponding 360.Nm archive_read_disk 361interface that walks a directory hierarchy and returns archive 362entry objects. 363