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