lib/libarchive/archive_read.3

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