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