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