contrib/libarchive/archive_read.3

   1 .\" Copyright (c) 2003-2004 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.11 2004/08/07 19:22:50 kientzle Exp $
  26 .\"
  27 .Dd October 1, 2003
  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_tar ,
  39 .Nm archive_read_support_format_cpio ,
  40 .Nm archive_read_support_format_all ,
  41 .Nm archive_read_open ,
  42 .Nm archive_read_open_fd ,
  43 .Nm archive_read_open_file ,
  44 .Nm archive_read_next_header ,
  45 .Nm archive_read_data ,
  46 .Nm archive_read_data_block ,
  47 .Nm archive_read_data_skip ,
  48 .Nm archive_read_data_into_buffer ,
  49 .Nm archive_read_data_into_fd ,
  50 .Nm archive_read_extract ,
  51 .Nm archive_read_extract_set_progress_callback ,
  52 .Nm archive_read_close
  53 .Nm archive_read_finish
  54 .Nd functions for reading tar archives
  55 .Sh SYNOPSIS
  56 .In archive.h
  57 .Ft struct archive *
  58 .Fn archive_read_new "void"
  59 .Ft int
  60 .Fn archive_read_set_bytes_per_block "struct archive *" "int"
  61 .Ft int
  62 .Fn archive_read_support_compression_all "struct archive *"
  63 .Ft int
  64 .Fn archive_read_support_compression_bzip2 "struct archive *"
  65 .Ft int
  66 .Fn archive_read_support_compression_compress "struct archive *"
  67 .Ft int
  68 .Fn archive_read_support_compression_gzip "struct archive *"
  69 .Ft int
  70 .Fn archive_read_support_compression_none "struct archive *"
  71 .Ft int
  72 .Fn archive_read_support_format_tar "struct archive *"
  73 .Ft int
  74 .Fn archive_read_support_format_cpio "struct archive *"
  75 .Ft int
  76 .Fn archive_read_support_format_all "struct archive *"
  77 .Ft int
  78 .Fn archive_read_open "struct archive *" "void *client_data" "archive_read_archive_callback *" "archive_open_archive_callback *" "archive_close_archive_callback *"
  79 .Ft int
  80 .Fn archive_read_open_fd "struct archive *" "int fd"
  81 .Ft int
  82 .Fn archive_read_open_file "struct archive *" "const char *filename"
  83 .Ft int
  84 .Fn archive_read_next_header "struct archive *" "struct archive_entry **"
  85 .Ft ssize_t
  86 .Fn archive_read_data "struct archive *" "void *buff" "size_t len"
  87 .Ft int
  88 .Fn archive_read_data_block "struct archive *" "const void **buff" "size_t *len" "off_t *offset"
  89 .Ft int
  90 .Fn archive_read_data_skip "struct archive *"
  91 .Ft int
  92 .Fn archive_read_data_into_buffer "struct archive *" "void *"
  93 .Ft int
  94 .Fn archive_read_data_into_fd "struct archive *" "int fd"
  95 .Ft int
  96 .Fn archive_read_extract "struct archive *" "int flags"
  97 .Ft void
  98 .Fn archive_read_extract_set_progress_callback "struct archive *" "void (*func)(void *)" "void *user_data"
  99 .Ft int
 100 .Fn archive_read_close "struct archive *"
 101 .Ft void
 102 .Fn archive_read_finish "struct archive *"
 103 .Sh DESCRIPTION
 104 These functions provide a complete API for reading streaming archives.
 105 The general process is to first create the
 106 .Tn struct archive
 107 object, set options, initialize the reader, iterate over the archive
 108 headers and associated data, then close the archive and release all
 109 resources.
 110 The following summary describes the functions in approximately the
 111 order they would be used:
 112 .Bl -tag -compact -width indent
 113 .It Fn archive_read_new
 114 Allocates and initializes a
 115 .Tn struct archive
 116 object suitable for reading from an archive.
 117 .It Fn archive_read_set_bytes_per_block
 118 Sets the block size used for reading the archive data.
 119 This controls the size that will be used when invoking the read
 120 callback function.
 121 The default is 20 records or 10240 bytes for tar formats.
 122 .It Fn archive_read_support_compression_XXX
 123 Enables auto-detection code and decompression support for the
 124 specified compression.
 125 Note that
 126 .Dq none
 127 is always enabled by default.
 128 For convenience,
 129 .Fn archive_read_support_compression_all
 130 enables all available decompression code.
 131 .It Fn archive_read_support_format_XXX
 132 Enables support---including auto-detection code---for the
 133 specified archive format.
 134 In particular,
 135 .Fn archive_read_support_format_tar
 136 enables support for a variety of standard tar formats, old-style tar,
 137 ustar, pax interchange format, and many common variants.
 138 For convenience,
 139 .Fn archive_read_support_format_all
 140 enables support for all available formats.
 141 Note that there is no default.
 142 .It Fn archive_read_open
 143 Freeze the settings, open the archive, and prepare for reading entries.
 144 This is the most generic version of this call, which accepts
 145 three callback functions.
 146 The library invokes these client-provided functions to obtain
 147 raw bytes from the archive.
 148 Note: The API permits a decompression method to fork and invoke the
 149 callbacks from another process.
 150 Although none of the current decompression methods use this technique,
 151 future decompression methods may utilize this technique.
 152 If the decompressor forks, it will ensure that the open and close
 153 callbacks are invoked within the same process as the read callback.
 154 In particular, clients should not attempt to use shared variables to
 155 communicate between the open/read/close callbacks and the mainline code.
 156 .It Fn archive_read_open_fd
 157 Like
 158 .Fn archive_read_open ,
 159 except that it accepts a file descriptor rather than
 160 a trio of function pointers.
 161 Note that the file descriptor will not be automatically closed at
 162 end-of-archive.
 163 .It Fn archive_read_open_file
 164 Like
 165 .Fn archive_read_open ,
 166 except that it accepts a simple filename.
 167 A NULL filename represents standard input.
 168 .It Fn archive_read_next_header
 169 Read the header for the next entry and return a pointer to
 170 a
 171 .Tn struct archive_entry .
 172 .It Fn archive_read_data
 173 Read data associated with the header just read.
 174 Internally, this is a convenience function that calls
 175 .Fn archive_read_data_block
 176 and fills any gaps with nulls so that callers see a single
 177 continuous stream of data.
 178 .It Fn archive_read_data_block
 179 Return the next available block of data for this entry.
 180 Unlike
 181 .Fn archive_read_data ,
 182 the
 183 .Fn archive_read_data_block
 184 function avoids copying data and allows you to correctly handle
 185 sparse files, as supported by some archive formats.
 186 The library gaurantees that offsets will increase and that blocks
 187 will not overlap.
 188 .It Fn archive_read_data_skip
 189 A convenience function that repeatedly calls
 190 .Fn archive_read_data_block
 191 to skip all of the data for this archive entry.
 192 .It Fn archive_read_data_into_buffer
 193 A convenience function that repeatedly calls
 194 .Fn archive_read_data_block
 195 to copy the entire entry into the client-supplied buffer.
 196 Note that the client is responsible for sizing the buffer appropriately.
 197 .It Fn archive_read_data_into_fd
 198 A convenience function that repeatedly calls
 199 .Fn archive_read_data_block
 200 to copy the entire entry to the provided file descriptor.
 201 .It Fn archive_read_extract
 202 A convenience function that recreates the specified object on
 203 disk and reads the entry data into that object.
 204 The
 205 .Va flags
 206 argument modifies how the object is recreated.
 207 It consists of a bitwise OR of one or more of the following values:
 208 .Bl -tag -compact -width "indent"
 209 .It Cm ARCHIVE_EXTRACT_OWNER
 210 The user and group IDs should be set on the restored file.
 211 By default, the user and group IDs are not restored.
 212 .It Cm ARCHIVE_EXTRACT_PERM
 213 The permissions (mode bits) should be restored for all objects.
 214 By default, permissions are only restored for regular files.
 215 .It Cm ARCHIVE_EXTRACT_TIME
 216 The timestamps (mtime, ctime, and atime) should be restored.
 217 By default, they are ignored.
 218 Note that restoring of atime is not currently supported.
 219 .It Cm ARCHIVE_EXTRACT_NO_OVERWRITE
 220 Existing files on disk will not be overwritten.
 221 By default, existing files are unlinked before the new entry is written.
 222 .It Cm ARCHIVE_EXTRACT_UNLINK
 223 Existing files on disk will be unlinked and recreated from scratch.
 224 By default, existing files are truncated and rewritten, but
 225 the file is not recreated.
 226 In particular, the default behavior does not break existing hard links.
 227 .El
 228 .It Fn archive_read_extract_set_progress_callback
 229 Sets a pointer to a user-defined callback that can be used
 230 for updating progress displays during extraction.
 231 The progress function will be invoked during the extraction of large
 232 regular files.
 233 The progress function will be invoked with the pointer provided to this call.
 234 Generally, the data pointed to should include a reference to the archive
 235 object and the archive_entry object so that various statistics
 236 can be retrieved for the progress display.
 237 .It Fn archive_read_close
 238 Complete the archive and invoke the close callback.
 239 .It Fn archive_read_finish
 240 Invokes
 241 .Fn archive_read_close
 242 if it wasn't invoked maually, then release all resources.
 243 .El
 244 .Pp
 245 Note that the library determines most of the relevant information about
 246 the archive by inspection.
 247 In particular, it automatically detects
 248 .Xr gzip 1
 249 or
 250 .Xr bzip2 1
 251 compression and transparently performs the appropriate decompression.
 252 It also automatically detects the archive format.
 253 .Pp
 254 The callback functions must match the following prototypes:
 255 .Bl -item -offset indent
 256 .It
 257 .Ft typedef ssize_t
 258 .Fn archive_read_callback "struct archive *" "void *client_data" "const void **buffer"
 259 .It
 260 .Ft typedef int
 261 .Fn archive_open_callback "struct archive *" "void *client_data"
 262 .It
 263 .Ft typedef int
 264 .Fn archive_close_callback "struct archive *" "void *client_data"
 265 .El
 266 These callback functions are called whenever the library requires
 267 raw bytes from the archive.
 268 Note that it is the client's responsibility to correctly
 269 block the input.
 270 .Pp
 271 A complete description of the
 272 .Tn struct archive
 273 and
 274 .Tn struct archive_entry
 275 objects can be found in the overview manual page for
 276 .Xr libarchive 3 .
 277 .Sh EXAMPLE
 278 The following illustrates basic usage of the library.
 279 In this example,
 280 the callback functions are simply wrappers around the standard
 281 .Xr open 2 ,
 282 .Xr read 2 ,
 283 and
 284 .Xr close 2
 285 system calls.
 286 .Bd -literal -offset indent
 287 void
 288 list_archive(const char *name)
 289 {
 290   struct mydata *mydata;
 291   struct archive *a;
 292   struct archive_entry *entry;
 293
 294   mydata = malloc(sizeof(struct mydata));
 295   a = archive_read_new();
 296   mydata->name = name;
 297   archive_read_support_compression_all(a);
 298   archive_read_support_format_all(a);
 299   archive_read_open(a, mydata, myopen, myread, myclose);
 300   while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
 301     printf("%s\\n",archive_entry_pathname(entry));
 302     archive_read_data_skip(a);
 303   }
 304   archive_read_finish(a);
 305   free(mydata);
 306 }
 307
 308 ssize_t
 309 myread(struct archive *a, void *client_data, const void **buff)
 310 {
 311   struct mydata *mydata = client_data;
 312
 313   *buff = mydata->buff;
 314   return (read(mydata->fd, mydata->buff, 10240));
 315 }
 316
 317 int
 318 myopen(struct archive *a, void *client_data)
 319 {
 320   struct mydata *mydata = client_data;
 321
 322   mydata->fd = open(mydata->name, O_RDONLY);
 323   return (mydata->fd >= 0);
 324 }
 325
 326 int
 327 myclose(struct archive *a, void *client_data)
 328 {
 329   struct mydata *mydata = client_data;
 330
 331   if (mydata->fd > 0)
 332     close(mydata->fd);
 333   return (0);
 334 }
 335 .Ed
 336 .Sh RETURN VALUES
 337 Most functions return zero on success, non-zero on error.
 338 The possible return codes include:
 339 .Cm ARCHIVE_OK
 340 (the operation succeeded)
 341 .Cm ARCHIVE_WARN
 342 (the operation succeeded but a non-critical error was encountered)
 343 .Cm ARCHIVE_EOF
 344 (end-of-archive was encountered),
 345 .Cm ARCHIVE_RETRY
 346 (the operation failed but can be retried),
 347 and
 348 .Cm ARCHIVE_FATAL
 349 (there was a fatal error; the archive should be closed immediately).
 350 Detailed error codes and textual descriptions are available from the
 351 .Fn archive_errno
 352 and
 353 .Fn archive_error_string
 354 functions.
 355 .Pp
 356 .Fn archive_read_new
 357 returns a pointer to a freshly allocated
 358 .Tn struct archive
 359 object.
 360 It returns
 361 .Dv NULL
 362 on error.
 363 .Pp
 364 .Fn archive_read_data
 365 returns a count of bytes actually read or zero at the end of the entry.
 366 On error, a value of
 367 .Cm ARCHIVE_FATAL ,
 368 .Cm ARCHIVE_WARN ,
 369 or
 370 .Cm ARCHIVE_RETRY
 371 is returned and an error code and textual description can be retrieved from the
 372 .Fn archive_errno
 373 and
 374 .Fn archive_error_string
 375 functions.
 376 .Pp
 377 The library expects the client callbacks to behave similarly.
 378 If there is an error, you can use
 379 .Fn archive_set_error
 380 to set an appropriate error code and description,
 381 then return one of the non-zero values above.
 382 (Note that the value eventually returned to the client may
 383 not be the same; many errors that are not critical at the level
 384 of basic I/O can prevent the archive from being properly read,
 385 thus most I/O errors eventually cause
 386 .Cm ARCHIVE_FATAL
 387 to be returned.)
 388 .\" .Sh ERRORS
 389 .Sh SEE ALSO
 390 .Xr tar 1 ,
 391 .Xr archive 3 ,
 392 .Xr tar 5
 393 .Sh HISTORY
 394 The
 395 .Nm libarchive
 396 library first appeared in
 397 .Fx 5.3 .
 398 .Sh AUTHORS
 399 .An -nosplit
 400 The
 401 .Nm libarchive
 402 library was written by
 403 .An Tim Kientzle Aq kientzle@acm.org .
 404 .Sh BUGS