contrib/libarchive-1.3.1/libarchive/archive_read.3

   1 .\" Copyright (c) 2003-2006 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_read.3,v 1.24 2006/09/05 05:59:45 kientzle Exp $
  26 .\"
  27 .Dd August 19, 2006
  28 .Dt archive_read 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_read_new ,
  32 .Nm archive_read_set_bytes_per_block ,
  33 .Nm archive_read_support_compression_all ,
  34 .Nm archive_read_support_compression_bzip2 ,
  35 .Nm archive_read_support_compression_compress ,
  36 .Nm archive_read_support_compression_gzip ,
  37 .Nm archive_read_support_compression_none ,
  38 .Nm archive_read_support_format_all ,
  39 .Nm archive_read_support_format_cpio ,
  40 .Nm archive_read_support_format_iso9660 ,
  41 .Nm archive_read_support_format_tar ,
  42 .Nm archive_read_support_format_zip ,
  43 .Nm archive_read_open ,
  44 .Nm archive_read_open2 ,
  45 .Nm archive_read_open_fd ,
  46 .Nm archive_read_open_FILE ,
  47 .Nm archive_read_open_filename ,
  48 .Nm archive_read_open_memory ,
  49 .Nm archive_read_next_header ,
  50 .Nm archive_read_data ,
  51 .Nm archive_read_data_block ,
  52 .Nm archive_read_data_skip ,
  53 .Nm archive_read_data_into_buffer ,
  54 .Nm archive_read_data_into_fd ,
  55 .Nm archive_read_extract ,
  56 .Nm archive_read_extract_set_progress_callback ,
  57 .Nm archive_read_close ,
  58 .Nm archive_read_finish
  59 .Nd functions for reading streaming archives
  60 .Sh SYNOPSIS
  61 .In archive.h
  62 .Ft struct archive *
  63 .Fn archive_read_new "void"
  64 .Ft int
  65 .Fn archive_read_set_bytes_per_block "struct archive *" "int"
  66 .Ft int
  67 .Fn archive_read_support_compression_all "struct archive *"
  68 .Ft int
  69 .Fn archive_read_support_compression_bzip2 "struct archive *"
  70 .Ft int
  71 .Fn archive_read_support_compression_compress "struct archive *"
  72 .Ft int
  73 .Fn archive_read_support_compression_gzip "struct archive *"
  74 .Ft int
  75 .Fn archive_read_support_compression_none "struct archive *"
  76 .Ft int
  77 .Fn archive_read_support_format_all "struct archive *"
  78 .Ft int
  79 .Fn archive_read_support_format_cpio "struct archive *"
  80 .Ft int
  81 .Fn archive_read_support_format_iso9660 "struct archive *"
  82 .Ft int
  83 .Fn archive_read_support_format_tar "struct archive *"
  84 .Ft int
  85 .Fn archive_read_support_format_zip "struct archive *"
  86 .Ft int
  87 .Fn archive_read_open "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_close_callback *"
  88 .Ft int
  89 .Fn archive_read_open2 "struct archive *" "void *client_data" "archive_open_callback *" "archive_read_callback *" "archive_skip_callback *" "archive_close_callback *"
  90 .Ft int
  91 .Fn archive_read_open_FILE "struct archive *" "FILE *file"
  92 .Ft int
  93 .Fn archive_read_open_fd "struct archive *" "int fd" "size_t block_size"
  94 .Ft int
  95 .Fn archive_read_open_filename "struct archive *" "const char *filename" "size_t block_size"
  96 .Ft int
  97 .Fn archive_read_open_memory "struct archive *" "void *buff" "size_t size"
  98 .Ft int
  99 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
 100 .Ft ssize_t
 101 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
 102 .Ft int
 103 .Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"
 104 .Ft int
 105 .Fn archive_read_data_skip "struct archive *"
 106 .Ft int
 107 .Fn archive_read_data_into_buffer "struct archive *" "void *" "ssize_t len"
 108 .Ft int
 109 .Fn archive_read_data_into_fd "struct archive *" "int fd"
 110 .Ft int
 111 .Fn archive_read_extract "struct archive *" "struct archive_entry *" "int flags"
 112 .Ft void
 113 .Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"
 114 .Ft int
 115 .Fn archive_read_close "struct archive *"
 116 .Ft int
 117 .Fn archive_read_finish "struct archive *"
 118 .Sh DESCRIPTION
 119 These functions provide a complete API for reading streaming archives.
 120 The general process is to first create the
 121 .Tn struct archive
 122 object, set options, initialize the reader, iterate over the archive
 123 headers and associated data, then close the archive and release all
 124 resources.
 125 The following summary describes the functions in approximately the
 126 order they would be used:
 127 .Bl -tag -compact -width indent
 128 .It Fn archive_read_new
 129 Allocates and initializes a
 130 .Tn struct archive
 131 object suitable for reading from an archive.
 132 .It Fn archive_read_set_bytes_per_block
 133 Sets the block size used for reading the archive data.
 134 This controls the size that will be used when invoking the read
 135 callback function.
 136 The default is 20 records or 10240 bytes for tar formats.
 137 .It Fn archive_read_support_compression_all , Fn archive_read_support_compression_bzip2 , Fn archive_read_support_compression_compress , Fn archive_read_support_compression_gzip , Fn archive_read_support_compression_none
 138 Enables auto-detection code and decompression support for the
 139 specified compression.
 140 Note that
 141 .Dq none
 142 is always enabled by default.
 143 For convenience,
 144 .Fn archive_read_support_compression_all
 145 enables all available decompression code.
 146 .It Fn archive_read_support_format_all , Fn archive_read_support_format_cpio , Fn archive_read_support_format_iso9660 , Fn archive_read_support_format_tar, Fn archive_read_support_format_zip
 147 Enables support---including auto-detection code---for the
 148 specified archive format.
 149 For example,
 150 .Fn archive_read_support_format_tar
 151 enables support for a variety of standard tar formats, old-style tar,
 152 ustar, pax interchange format, and many common variants.
 153 For convenience,
 154 .Fn archive_read_support_format_all
 155 enables support for all available formats.
 156 Note that there is no default.
 157 .It Fn archive_read_open
 158 The same as
 159 .Fn archive_read_open2 ,
 160 except that the skip callback is assumed to be
 161 .Dv NULL .
 162 .It Fn archive_read_open2
 163 Freeze the settings, open the archive, and prepare for reading entries.
 164 This is the most generic version of this call, which accepts
 165 four callback functions.
 166 Most clients will want to use
 167 .Fn archive_read_open_filename ,
 168 .Fn archive_read_open_FILE ,
 169 .Fn archive_read_open_fd ,
 170 or
 171 .Fn archive_read_open_memory
 172 instead.
 173 The library invokes the client-provided functions to obtain
 174 raw bytes from the archive.
 175 .It Fn archive_read_open_FILE
 176 Like
 177 .Fn archive_read_open ,
 178 except that it accepts a
 179 .Ft "FILE *"
 180 pointer.
 181 This function should not be used with tape drives or other devices
 182 that require strict I/O blocking.
 183 .It Fn archive_read_open_fd
 184 Like
 185 .Fn archive_read_open ,
 186 except that it accepts a file descriptor and block size rather than
 187 a set of function pointers.
 188 Note that the file descriptor will not be automatically closed at
 189 end-of-archive.
 190 This function is safe for use with tape drives or other blocked devices.
 191 .It Fn archive_read_open_file
 192 A deprecated synonym for
 193 .Fn archive_read_open_filename .
 194 .It Fn archive_read_open_filename
 195 Like
 196 .Fn archive_read_open ,
 197 except that it accepts a simple filename and a block size.
 198 A NULL filename represents standard input.
 199 This function is safe for use with tape drives or other blocked devices.
 200 .It Fn archive_read_open_memory
 201 Like
 202 .Fn archive_read_open ,
 203 except that it accepts a pointer and size of a block of
 204 memory containing the archive data.
 205 .It Fn archive_read_next_header
 206 Read the header for the next entry and return a pointer to
 207 a
 208 .Tn struct archive_entry .
 209 .It Fn archive_read_data
 210 Read data associated with the header just read.
 211 Internally, this is a convenience function that calls
 212 .Fn archive_read_data_block
 213 and fills any gaps with nulls so that callers see a single
 214 continuous stream of data.
 215 .It Fn archive_read_data_block
 216 Return the next available block of data for this entry.
 217 Unlike
 218 .Fn archive_read_data ,
 219 the
 220 .Fn archive_read_data_block
 221 function avoids copying data and allows you to correctly handle
 222 sparse files, as supported by some archive formats.
 223 The library guarantees that offsets will increase and that blocks
 224 will not overlap.
 225 Note that the blocks returned from this function can be much larger
 226 than the block size read from disk, due to compression
 227 and internal buffer optimizations.
 228 .It Fn archive_read_data_skip
 229 A convenience function that repeatedly calls
 230 .Fn archive_read_data_block
 231 to skip all of the data for this archive entry.
 232 .It Fn archive_read_data_into_buffer
 233 A convenience function that repeatedly calls
 234 .Fn archive_read_data_block
 235 to copy the entire entry into the client-supplied buffer.
 236 Note that the client is responsible for sizing the buffer appropriately.
 237 .It Fn archive_read_data_into_fd
 238 A convenience function that repeatedly calls
 239 .Fn archive_read_data_block
 240 to copy the entire entry to the provided file descriptor.
 241 .It Fn archive_read_extract_set_skip_file
 242 This function records the device and inode numbers
 243 of a file that should not be restored.
 244 This is a convenience that prevents
 245 .Fn archive_read_extract
 246 from restoring a file over the archive itself.
 247 .It Fn archive_read_extract
 248 A convenience function that recreates the specified object on
 249 disk and reads the entry data into that object.
 250 The filename, permissions, and other critical information
 251 are taken from the provided
 252 .Va archive_entry
 253 object.
 254 The
 255 .Va flags
 256 argument modifies how the object is recreated.
 257 It consists of a bitwise OR of one or more of the following values:
 258 .Bl -tag -compact -width "indent"
 259 .It Cm ARCHIVE_EXTRACT_OWNER
 260 The user and group IDs should be set on the restored file.
 261 By default, the user and group IDs are not restored.
 262 .It Cm ARCHIVE_EXTRACT_PERM
 263 The permissions (mode bits) should be restored for all objects.
 264 By default, permissions are only restored for regular files.
 265 .It Cm ARCHIVE_EXTRACT_TIME
 266 The timestamps (mtime, ctime, and atime) should be restored.
 267 By default, they are ignored.
 268 Note that restoring of atime is not currently supported.
 269 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
 270 Existing files on disk will not be overwritten.
 271 By default, existing regular files are truncated and overwritten;
 272 existing directories will have their permissions updated;
 273 other pre-existing objects are unlinked and recreated from scratch.
 274 .It Cm ARCHIVE_EXTRACT_UNLINK
 275 Existing files on disk will be unlinked and recreated from scratch.
 276 By default, existing files are truncated and rewritten, but
 277 the file is not recreated.
 278 In particular, the default behavior does not break existing hard links.
 279 .It Cm ARCHIVE_EXTRACT_ACL
 280 Attempt to restore ACLs.
 281 By default, extended ACLs are ignored.
 282 .It Cm ARCHIVE_EXTRACT_FFLAGS
 283 Attempt to restore extended file flags.
 284 By default, file flags are ignored.
 285 .El
 286 Note that not all attributes are set immediately;
 287 some attributes are cached in memory and written to disk only
 288 when the archive is closed.
 289 (For example, read-only directories are initially created
 290 writable so that files within those directories can be
 291 restored.
 292 The final permissions are set when the archive is closed.)
 293 .It Fn archive_read_extract_set_progress_callback
 294 Sets a pointer to a user-defined callback that can be used
 295 for updating progress displays during extraction.
 296 The progress function will be invoked during the extraction of large
 297 regular files.
 298 The progress function will be invoked with the pointer provided to this call.
 299 Generally, the data pointed to should include a reference to the archive
 300 object and the archive_entry object so that various statistics
 301 can be retrieved for the progress display.
 302 .It Fn archive_read_close
 303 Complete the archive and invoke the close callback.
 304 .It Fn archive_read_finish
 305 Invokes
 306 .Fn archive_read_close
 307 if it was not invoked manually, then release all resources.
 308 Note: In libarchive 1.x, this function was declared to return
 309 .Ft void ,
 310 which made it impossible to detect certain errors when
 311 .Fn archive_read_close
 312 was invoked implicitly from this function.
 313 The declaration is corrected beginning with libarchive 2.0.
 314 .El
 315 .Pp
 316 Note that the library determines most of the relevant information about
 317 the archive by inspection.
 318 In particular, it automatically detects
 319 .Xr gzip 1
 320 or
 321 .Xr bzip2 1
 322 compression and transparently performs the appropriate decompression.
 323 It also automatically detects the archive format.
 324 .Pp
 325 A complete description of the
 326 .Tn struct archive
 327 and
 328 .Tn struct archive_entry
 329 objects can be found in the overview manual page for
 330 .Xr libarchive 3 .
 331 .Sh CLIENT CALLBACKS
 332 The callback functions must match the following prototypes:
 333 .Bl -item -offset indent
 334 .It
 335 .Ft typedef ssize_t
 336 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
 337 .It
 338 .Ft typedef int
 339 .Fn archive_skip_callback "struct archive *" "void *client_data" "size_t request"
 340 .It
 341 .Ft typedef int
 342 .Fn archive_open_callback "struct archive *" "void *client_data"
 343 .It
 344 .Ft typedef int
 345 .Fn archive_close_callback "struct archive *" "void *client_data"
 346 .El
 347 .Pp
 348 The open callback is invoked by
 349 .Fn archive_open .
 350 It should return
 351 .Cm ARCHIVE_OK
 352 if the underlying file or data source is successfully
 353 opened.
 354 If the open fails, it should call
 355 .Fn archive_set_error
 356 to register an error code and message and return
 357 .Cm ARCHIVE_FATAL .
 358 .Pp
 359 The read callback is invoked whenever the library
 360 requires raw bytes from the archive.
 361 The read callback should read data into a buffer,
 362 set the
 363 .Li const void **buffer
 364 argument to point to the available data, and
 365 return a count of the number of bytes available.
 366 The library will invoke the read callback again
 367 only after it has consumed this data.
 368 The library imposes no constraints on the size
 369 of the data blocks returned.
 370 On end-of-file, the read callback should
 371 return zero.
 372 On error, the read callback should invoke
 373 .Fn archive_set_error
 374 to register an error code and message and
 375 return -1.
 376 .Pp
 377 The skip callback is invoked when the
 378 library wants to ignore a block of data.
 379 The return value is the number of bytes actually
 380 skipped, which may differ from the request.
 381 If the callback cannot skip data, it should return
 382 zero.
 383 If the skip callback is not provided (the
 384 function pointer is
 385 .Dv NULL ),
 386 the library will invoke the read function
 387 instead and simply discard the result.
 388 A skip callback can provide significant
 389 performance gains when reading uncompressed
 390 archives from slow disk drives or other media
 391 that can skip quickly.
 392 .Pp
 393 The close callback is invoked by archive_close when
 394 the archive processing is complete.
 395 The callback should return
 396 .Cm ARCHIVE_OK
 397 on success.
 398 On failure, the callback should invoke
 399 .Fn archive_set_error
 400 to register an error code and message and
 401 return
 402 .Cm ARCHIVE_FATAL.
 403 .Sh EXAMPLE
 404 The following illustrates basic usage of the library.
 405 In this example,
 406 the callback functions are simply wrappers around the standard
 407 .Xr open 2 ,
 408 .Xr read 2 ,
 409 and
 410 .Xr close 2
 411 system calls.
 412 .Bd -literal -offset indent
 413 void
 414 list_archive(const char *name)
 415 {
 416   struct mydata *mydata;
 417   struct archive *a;
 418   struct archive_entry *entry;
 419
 420   mydata = malloc(sizeof(struct mydata));
 421   a = archive_read_new();
 422   mydata->name = name;
 423   archive_read_support_compression_all(a);
 424   archive_read_support_format_all(a);
 425   archive_read_open(a, mydata, myopen, myread, myclose);
 426   while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
 427     printf("%s\\n",archive_entry_pathname(entry));
 428     archive_read_data_skip(a);
 429   }
 430   archive_read_finish(a);
 431   free(mydata);
 432 }
 433
 434 ssize_t
 435 myread(struct archive *a, void *client_data, const void **buff)
 436 {
 437   struct mydata *mydata = client_data;
 438
 439   *buff = mydata->buff;
 440   return (read(mydata->fd, mydata->buff, 10240));
 441 }
 442
 443 int
 444 myopen(struct archive *a, void *client_data)
 445 {
 446   struct mydata *mydata = client_data;
 447
 448   mydata->fd = open(mydata->name, O_RDONLY);
 449   return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
 450 }
 451
 452 int
 453 myclose(struct archive *a, void *client_data)
 454 {
 455   struct mydata *mydata = client_data;
 456
 457   if (mydata->fd > 0)
 458     close(mydata->fd);
 459   return (ARCHIVE_OK);
 460 }
 461 .Ed
 462 .Sh RETURN VALUES
 463 Most functions return zero on success, non-zero on error.
 464 The possible return codes include:
 465 .Cm ARCHIVE_OK
 466 (the operation succeeded),
 467 .Cm ARCHIVE_WARN
 468 (the operation succeeded but a non-critical error was encountered),
 469 .Cm ARCHIVE_EOF
 470 (end-of-archive was encountered),
 471 .Cm ARCHIVE_RETRY
 472 (the operation failed but can be retried),
 473 and
 474 .Cm ARCHIVE_FATAL
 475 (there was a fatal error; the archive should be closed immediately).
 476 Detailed error codes and textual descriptions are available from the
 477 .Fn archive_errno
 478 and
 479 .Fn archive_error_string
 480 functions.
 481 .Pp
 482 .Fn archive_read_new
 483 returns a pointer to a freshly allocated
 484 .Tn struct archive
 485 object.
 486 It returns
 487 .Dv NULL
 488 on error.
 489 .Pp
 490 .Fn archive_read_data
 491 returns a count of bytes actually read or zero at the end of the entry.
 492 On error, a value of
 493 .Cm ARCHIVE_FATAL ,
 494 .Cm ARCHIVE_WARN ,
 495 or
 496 .Cm ARCHIVE_RETRY
 497 is returned and an error code and textual description can be retrieved from the
 498 .Fn archive_errno
 499 and
 500 .Fn archive_error_string
 501 functions.
 502 .Pp
 503 The library expects the client callbacks to behave similarly.
 504 If there is an error, you can use
 505 .Fn archive_set_error
 506 to set an appropriate error code and description,
 507 then return one of the non-zero values above.
 508 (Note that the value eventually returned to the client may
 509 not be the same; many errors that are not critical at the level
 510 of basic I/O can prevent the archive from being properly read,
 511 thus most I/O errors eventually cause
 512 .Cm ARCHIVE_FATAL
 513 to be returned.)
 514 .\" .Sh ERRORS
 515 .Sh SEE ALSO
 516 .Xr tar 1 ,
 517 .Xr archive 3 ,
 518 .Xr archive_util 3 ,
 519 .Xr tar 5
 520 .Sh HISTORY
 521 The
 522 .Nm libarchive
 523 library first appeared in
 524 .Fx 5.3 .
 525 .Sh AUTHORS
 526 .An -nosplit
 527 The
 528 .Nm libarchive
 529 library was written by
 530 .An Tim Kientzle Aq kientzle@acm.org .
 531 .Sh BUGS
 532 Directories are actually extracted in two distinct phases.
 533 Directories are created during
 534 .Fn archive_read_extract ,
 535 but final permissions are not set until
 536 .Fn archive_read_close .
 537 This separation is necessary to correctly handle borderline
 538 cases such as a non-writable directory containing
 539 files, but can cause unexpected results.
 540 In particular, directory permissions are not fully
 541 restored until the archive is closed.
 542 If you use
 543 .Xr chdir 2
 544 to change the current directory between calls to
 545 .Fn archive_read_extract
 546 or before calling
 547 .Fn archive_read_close ,
 548 you may confuse the permission-setting logic with
 549 the result that directory permissions are restored
 550 incorrectly.