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 ssize_t
  74 .Fn archive_write_data "struct archive *" "const void *" "size_t"
  75 .Ft 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 .El
 188 .It Xo
 189 .Fn archive_write_disk_set_group_lookup ,
 190 .Fn archive_write_disk_set_user_lookup
 191 .Xc
 192 The
 193 .Tn struct archive_entry
 194 objects contain both names and ids that can be used to identify users
 195 and groups.
 196 These names and ids describe the ownership of the file itself and
 197 also appear in ACL lists.
 198 By default, the library uses the ids and ignores the names, but
 199 this can be overridden by registering user and group lookup functions.
 200 To register, you must provide a lookup function which
 201 accepts both a name and id and returns a suitable id.
 202 You may also provide a
 203 .Tn void *
 204 pointer to a private data structure and a cleanup function for
 205 that data.
 206 The cleanup function will be invoked when the
 207 .Tn struct archive
 208 object is destroyed.
 209 .It Fn archive_write_disk_set_standard_lookup
 210 This convenience function installs a standard set of user
 211 and group lookup functions.
 212 These functions use
 213 .Xr getpwnam 3
 214 and
 215 .Xr getgrnam 3
 216 to convert names to ids, defaulting to the ids if the names cannot
 217 be looked up.
 218 These functions also implement a simple memory cache to reduce
 219 the number of calls to
 220 .Xr getpwnam 3
 221 and
 222 .Xr getgrnam 3 .
 223 .It Fn archive_write_header
 224 Build and write a header using the data in the provided
 225 .Tn struct archive_entry
 226 structure.
 227 See
 228 .Xr archive_entry 3
 229 for information on creating and populating
 230 .Tn struct archive_entry
 231 objects.
 232 .It Fn archive_write_data
 233 Write data corresponding to the header just written.
 234 Returns number of bytes written or -1 on error.
 235 .It Fn archive_write_data_block
 236 Write data corresponding to the header just written.
 237 This is like
 238 .Fn archive_write_data
 239 except that it performs a seek on the file being
 240 written to the specified offset before writing the data.
 241 This is useful when restoring sparse files from archive
 242 formats that support sparse files.
 243 Returns number of bytes written or -1 on error.
 244 (Note: This is currently not supported for
 245 .Tn archive_write
 246 handles, only for
 247 .Tn archive_write_disk
 248 handles.)
 249 .It Fn archive_write_finish_entry
 250 Close out the entry just written.
 251 Ordinarily, clients never need to call this, as it
 252 is called automatically by
 253 .Fn archive_write_next_header
 254 and
 255 .Fn archive_write_close
 256 as needed.
 257 However, some file attributes are written to disk only
 258 after the file is closed, so this can be necessary
 259 if you need to work with the file on disk right away.
 260 .It Fn archive_write_close
 261 Set any attributes that could not be set during the initial restore.
 262 For example, directory timestamps are not restored initially because
 263 restoring a subsequent file would alter that timestamp.
 264 Similarly, non-writable directories are initially created with
 265 write permissions (so that their contents can be restored).
 266 The
 267 .Nm
 268 library maintains a list of all such deferred attributes and
 269 sets them when this function is invoked.
 270 .It Fn archive_write_finish
 271 This is a deprecated synonym for
 272 .Fn archive_write_free .
 273 .It Fn archive_write_free
 274 Invokes
 275 .Fn archive_write_close
 276 if it was not invoked manually, then releases all resources.
 277 .El
 278 More information about the
 279 .Va struct archive
 280 object and the overall design of the library can be found in the
 281 .Xr libarchive 3
 282 overview.
 283 Many of these functions are also documented under
 284 .Xr archive_write 3 .
 285 .Sh RETURN VALUES
 286 Most functions return
 287 .Cm ARCHIVE_OK
 288 (zero) on success, or one of several non-zero
 289 error codes for errors.
 290 Specific error codes include:
 291 .Cm ARCHIVE_RETRY
 292 for operations that might succeed if retried,
 293 .Cm ARCHIVE_WARN
 294 for unusual conditions that do not prevent further operations, and
 295 .Cm ARCHIVE_FATAL
 296 for serious errors that make remaining operations impossible.
 297 .Pp
 298 .Fn archive_write_disk_new
 299 returns a pointer to a newly-allocated
 300 .Tn struct archive
 301 object.
 302 .Pp
 303 .Fn archive_write_data
 304 returns a count of the number of bytes actually written,
 305 or
 306 .Li -1
 307 on error.
 308 .\"
 309 .Sh ERRORS
 310 Detailed error codes and textual descriptions are available from the
 311 .Fn archive_errno
 312 and
 313 .Fn archive_error_string
 314 functions.
 315 .\"
 316 .Sh SEE ALSO
 317 .Xr archive_read 3 ,
 318 .Xr archive_write 3 ,
 319 .Xr tar 1 ,
 320 .Xr libarchive 3
 321 .Sh HISTORY
 322 The
 323 .Nm libarchive
 324 library first appeared in
 325 .Fx 5.3 .
 326 The
 327 .Nm archive_write_disk
 328 interface was added to
 329 .Nm libarchive 2.0
 330 and first appeared in
 331 .Fx 6.3 .
 332 .Sh AUTHORS
 333 .An -nosplit
 334 The
 335 .Nm libarchive
 336 library was written by
 337 .An Tim Kientzle Aq kientzle@acm.org .
 338 .Sh BUGS
 339 Directories are actually extracted in two distinct phases.
 340 Directories are created during
 341 .Fn archive_write_header ,
 342 but final permissions are not set until
 343 .Fn archive_write_close .
 344 This separation is necessary to correctly handle borderline
 345 cases such as a non-writable directory containing
 346 files, but can cause unexpected results.
 347 In particular, directory permissions are not fully
 348 restored until the archive is closed.
 349 If you use
 350 .Xr chdir 2
 351 to change the current directory between calls to
 352 .Fn archive_read_extract
 353 or before calling
 354 .Fn archive_read_close ,
 355 you may confuse the permission-setting logic with
 356 the result that directory permissions are restored
 357 incorrectly.
 358 .Pp
 359 The library attempts to create objects with filenames longer than
 360 .Cm PATH_MAX
 361 by creating prefixes of the full path and changing the current directory.
 362 Currently, this logic is limited in scope; the fixup pass does
 363 not work correctly for such objects and the symlink security check
 364 option disables the support for very long pathnames.
 365 .Pp
 366 Restoring the path
 367 .Pa aa/../bb
 368 does create each intermediate directory.
 369 In particular, the directory
 370 .Pa aa
 371 is created as well as the final object
 372 .Pa bb .
 373 In theory, this can be exploited to create an entire directory hierarchy
 374 with a single request.
 375 Of course, this does not work if the
 376 .Cm ARCHIVE_EXTRACT_NODOTDOT
 377 option is specified.
 378 .Pp
 379 Implicit directories are always created obeying the current umask.
 380 Explicit objects are created obeying the current umask unless
 381 .Cm ARCHIVE_EXTRACT_PERM
 382 is specified, in which case they current umask is ignored.
 383 .Pp
 384 SGID and SUID bits are restored only if the correct user and
 385 group could be set.
 386 If
 387 .Cm ARCHIVE_EXTRACT_OWNER
 388 is not specified, then no attempt is made to set the ownership.
 389 In this case, SGID and SUID bits are restored only if the
 390 user and group of the final object happen to match those specified
 391 in the entry.
 392 .Pp
 393 The
 394 .Dq standard
 395 user-id and group-id lookup functions are not the defaults because
 396 .Xr getgrnam 3
 397 and
 398 .Xr getpwnam 3
 399 are sometimes too large for particular applications.
 400 The current design allows the application author to use a more
 401 compact implementation when appropriate.
 402 .Pp
 403 There should be a corresponding
 404 .Nm archive_read_disk
 405 interface that walks a directory hierarchy and returns archive
 406 entry objects.