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