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