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