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