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