contrib/libarchive/libarchive/archive_write_disk.3

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