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