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 April 3, 2017
  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. Restore metadata using
 117 .Xr copyfile 3 .
 118 By default,
 119 .Xr copyfile 3
 120 metadata is ignored.
 121 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
 122 Existing files on disk will not be overwritten.
 123 By default, existing regular files are truncated and overwritten;
 124 existing directories will have their permissions updated;
 125 other pre-existing objects are unlinked and recreated from scratch.
 126 .It Cm ARCHIVE_EXTRACT_OWNER
 127 The user and group IDs should be set on the restored file.
 128 By default, the user and group IDs are not restored.
 129 .It Cm ARCHIVE_EXTRACT_PERM
 130 Full permissions (including SGID, SUID, and sticky bits) should
 131 be restored exactly as specified, without obeying the
 132 current umask.
 133 Note that SUID and SGID bits can only be restored if the
 134 user and group ID of the object on disk are correct.
 135 If
 136 .Cm ARCHIVE_EXTRACT_OWNER
 137 is not specified, then SUID and SGID bits will only be restored
 138 if the default user and group IDs of newly-created objects on disk
 139 happen to match those specified in the archive entry.
 140 By default, only basic permissions are restored, and umask is obeyed.
 141 .It Cm ARCHIVE_EXTRACT_SECURE_NOABSOLUTEPATHS
 142 Refuse to extract an absolute path.
 143 The default is to not refuse such paths.
 144 .It Cm ARCHIVE_EXTRACT_SECURE_NODOTDOT
 145 Refuse to extract a path that contains a
 146 .Pa ..
 147 element anywhere within it.
 148 The default is to not refuse such paths.
 149 Note that paths ending in
 150 .Pa ..
 151 always cause an error, regardless of this flag.
 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 .It Cm ARCHIVE_EXTRACT_SPARSE
 161 Scan data for blocks of NUL bytes and try to recreate them with holes.
 162 This results in sparse files, independent of whether the archive format
 163 supports or uses them.
 164 .Cm ARCHIVE_EXTRACT_UNLINK
 165 is specified together with this option, the library will
 166 remove any intermediate symlinks it finds and return an
 167 error only if such symlink could not be removed.
 168 .It Cm ARCHIVE_EXTRACT_TIME
 169 The timestamps (mtime, ctime, and atime) should be restored.
 170 By default, they are ignored.
 171 Note that restoring of atime is not currently supported.
 172 .It Cm ARCHIVE_EXTRACT_UNLINK
 173 Existing files on disk will be unlinked before any attempt to
 174 create them.
 175 In some cases, this can prove to be a significant performance improvement.
 176 By default, existing files are truncated and rewritten, but
 177 the file is not recreated.
 178 In particular, the default behavior does not break existing hard links.
 179 .It Cm ARCHIVE_EXTRACT_XATTR
 180 Attempt to restore extended file attributes.
 181 By default, they are ignored.
 182 See
 183 .Xr xattr 7
 184 .Pq Linux ,
 185 .Xr xattr 2
 186 .Pq Mac OS X ,
 187 or
 188 .Xr getextattr 8
 189 .Pq FreeBSD
 190 for more information on extended file attributes.
 191 .El
 192 .It Xo
 193 .Fn archive_write_disk_set_group_lookup ,
 194 .Fn archive_write_disk_set_user_lookup
 195 .Xc
 196 The
 197 .Tn struct archive_entry
 198 objects contain both names and ids that can be used to identify users
 199 and groups.
 200 These names and ids describe the ownership of the file itself and
 201 also appear in ACL lists.
 202 By default, the library uses the ids and ignores the names, but
 203 this can be overridden by registering user and group lookup functions.
 204 To register, you must provide a lookup function which
 205 accepts both a name and id and returns a suitable id.
 206 You may also provide a
 207 .Tn void *
 208 pointer to a private data structure and a cleanup function for
 209 that data.
 210 The cleanup function will be invoked when the
 211 .Tn struct archive
 212 object is destroyed.
 213 .It Fn archive_write_disk_set_standard_lookup
 214 This convenience function installs a standard set of user
 215 and group lookup functions.
 216 These functions use
 217 .Xr getpwnam 3
 218 and
 219 .Xr getgrnam 3
 220 to convert names to ids, defaulting to the ids if the names cannot
 221 be looked up.
 222 These functions also implement a simple memory cache to reduce
 223 the number of calls to
 224 .Xr getpwnam 3
 225 and
 226 .Xr getgrnam 3 .
 227 .El
 228 More information about the
 229 .Va struct archive
 230 object and the overall design of the library can be found in the
 231 .Xr libarchive 3
 232 overview.
 233 Many of these functions are also documented under
 234 .Xr archive_write 3 .
 235 .Sh RETURN VALUES
 236 Most functions return
 237 .Cm ARCHIVE_OK
 238 (zero) on success, or one of several non-zero
 239 error codes for errors.
 240 Specific error codes include:
 241 .Cm ARCHIVE_RETRY
 242 for operations that might succeed if retried,
 243 .Cm ARCHIVE_WARN
 244 for unusual conditions that do not prevent further operations, and
 245 .Cm ARCHIVE_FATAL
 246 for serious errors that make remaining operations impossible.
 247 .Pp
 248 .Fn archive_write_disk_new
 249 returns a pointer to a newly-allocated
 250 .Tn struct archive
 251 object.
 252 .Pp
 253 .Fn archive_write_data
 254 returns a count of the number of bytes actually written,
 255 or
 256 .Li -1
 257 on error.
 258 .\"
 259 .Sh ERRORS
 260 Detailed error codes and textual descriptions are available from the
 261 .Fn archive_errno
 262 and
 263 .Fn archive_error_string
 264 functions.
 265 .\"
 266 .Sh SEE ALSO
 267 .Xr archive_read 3 ,
 268 .Xr archive_write 3 ,
 269 .Xr tar 1 ,
 270 .Xr libarchive 3
 271 .Sh HISTORY
 272 The
 273 .Nm libarchive
 274 library first appeared in
 275 .Fx 5.3 .
 276 The
 277 .Nm archive_write_disk
 278 interface was added to
 279 .Nm libarchive 2.0
 280 and first appeared in
 281 .Fx 6.3 .
 282 .Sh AUTHORS
 283 .An -nosplit
 284 The
 285 .Nm libarchive
 286 library was written by
 287 .An Tim Kientzle Aq kientzle@acm.org .
 288 .Sh BUGS
 289 Directories are actually extracted in two distinct phases.
 290 Directories are created during
 291 .Fn archive_write_header ,
 292 but final permissions are not set until
 293 .Fn archive_write_close .
 294 This separation is necessary to correctly handle borderline
 295 cases such as a non-writable directory containing
 296 files, but can cause unexpected results.
 297 In particular, directory permissions are not fully
 298 restored until the archive is closed.
 299 If you use
 300 .Xr chdir 2
 301 to change the current directory between calls to
 302 .Fn archive_read_extract
 303 or before calling
 304 .Fn archive_read_close ,
 305 you may confuse the permission-setting logic with
 306 the result that directory permissions are restored
 307 incorrectly.
 308 .Pp
 309 The library attempts to create objects with filenames longer than
 310 .Cm PATH_MAX
 311 by creating prefixes of the full path and changing the current directory.
 312 Currently, this logic is limited in scope; the fixup pass does
 313 not work correctly for such objects and the symlink security check
 314 option disables the support for very long pathnames.
 315 .Pp
 316 Restoring the path
 317 .Pa aa/../bb
 318 does create each intermediate directory.
 319 In particular, the directory
 320 .Pa aa
 321 is created as well as the final object
 322 .Pa bb .
 323 In theory, this can be exploited to create an entire directory hierarchy
 324 with a single request.
 325 Of course, this does not work if the
 326 .Cm ARCHIVE_EXTRACT_NODOTDOT
 327 option is specified.
 328 .Pp
 329 Implicit directories are always created obeying the current umask.
 330 Explicit objects are created obeying the current umask unless
 331 .Cm ARCHIVE_EXTRACT_PERM
 332 is specified, in which case they current umask is ignored.
 333 .Pp
 334 SGID and SUID bits are restored only if the correct user and
 335 group could be set.
 336 If
 337 .Cm ARCHIVE_EXTRACT_OWNER
 338 is not specified, then no attempt is made to set the ownership.
 339 In this case, SGID and SUID bits are restored only if the
 340 user and group of the final object happen to match those specified
 341 in the entry.
 342 .Pp
 343 The
 344 .Dq standard
 345 user-id and group-id lookup functions are not the defaults because
 346 .Xr getgrnam 3
 347 and
 348 .Xr getpwnam 3
 349 are sometimes too large for particular applications.
 350 The current design allows the application author to use a more
 351 compact implementation when appropriate.
 352 .Pp
 353 There should be a corresponding
 354 .Nm archive_read_disk
 355 interface that walks a directory hierarchy and returns archive
 356 entry objects.