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