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