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