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