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