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