contrib/libarchive/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 February 2, 2012
  28 .Dt ARCHIVE_READ 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_read
  32 .Nd functions for reading streaming archives
  33 .Sh LIBRARY
  34 Streaming Archive Library (libarchive, -larchive)
  35 .Sh SYNOPSIS
  36 .In archive.h
  37 .Sh DESCRIPTION
  38 These functions provide a complete API for reading streaming archives.
  39 The general process is to first create the
  40 .Tn struct archive
  41 object, set options, initialize the reader, iterate over the archive
  42 headers and associated data, then close the archive and release all
  43 resources.
  44 .\"
  45 .Ss Create archive object
  46 See
  47 .Xr archive_read_new 3 .
  48 .Pp
  49 To read an archive, you must first obtain an initialized
  50 .Tn struct archive
  51 object from
  52 .Fn archive_read_new .
  53 .\"
  54 .Ss Enable filters and formats
  55 See
  56 .Xr archive_read_filter 3
  57 and
  58 .Xr archive_read_format 3 .
  59 .Pp
  60 You can then modify this object for the desired operations with the
  61 various
  62 .Fn archive_read_set_XXX
  63 and
  64 .Fn archive_read_support_XXX
  65 functions.
  66 In particular, you will need to invoke appropriate
  67 .Fn archive_read_support_XXX
  68 functions to enable the corresponding compression and format
  69 support.
  70 Note that these latter functions perform two distinct operations:
  71 they cause the corresponding support code to be linked into your
  72 program, and they enable the corresponding auto-detect code.
  73 Unless you have specific constraints, you will generally want
  74 to invoke
  75 .Fn archive_read_support_filter_all
  76 and
  77 .Fn archive_read_support_format_all
  78 to enable auto-detect for all formats and compression types
  79 currently supported by the library.
  80 .\"
  81 .Ss Set options
  82 See
  83 .Xr archive_read_set_options 3 .
  84 .\"
  85 .Ss Open archive
  86 See
  87 .Xr archive_read_open 3 .
  88 .Pp
  89 Once you have prepared the
  90 .Tn struct archive
  91 object, you call
  92 .Fn archive_read_open
  93 to actually open the archive and prepare it for reading.
  94 There are several variants of this function;
  95 the most basic expects you to provide pointers to several
  96 functions that can provide blocks of bytes from the archive.
  97 There are convenience forms that allow you to
  98 specify a filename, file descriptor,
  99 .Ft "FILE *"
 100 object, or a block of memory from which to read the archive data.
 101 Note that the core library makes no assumptions about the
 102 size of the blocks read;
 103 callback functions are free to read whatever block size is
 104 most appropriate for the medium.
 105 .\"
 106 .Ss Consume archive
 107 See
 108 .Xr archive_read_header 3 ,
 109 .Xr archive_read_data 3
 110 and
 111 .Xr archive_read_extract 3 .
 112 .Pp
 113 Each archive entry consists of a header followed by a certain
 114 amount of data.
 115 You can obtain the next header with
 116 .Fn archive_read_next_header ,
 117 which returns a pointer to an
 118 .Tn struct archive_entry
 119 structure with information about the current archive element.
 120 If the entry is a regular file, then the header will be followed
 121 by the file data.
 122 You can use
 123 .Fn archive_read_data
 124 (which works much like the
 125 .Xr read 2
 126 system call)
 127 to read this data from the archive, or
 128 .Fn archive_read_data_block
 129 which provides a slightly more efficient interface.
 130 You may prefer to use the higher-level
 131 .Fn archive_read_data_skip ,
 132 which reads and discards the data for this entry,
 133 .Fn archive_read_data_into_fd ,
 134 which copies the data to the provided file descriptor, or
 135 .Fn archive_read_extract ,
 136 which recreates the specified entry on disk and copies data
 137 from the archive.
 138 In particular, note that
 139 .Fn archive_read_extract
 140 uses the
 141 .Tn struct archive_entry
 142 structure that you provide it, which may differ from the
 143 entry just read from the archive.
 144 In particular, many applications will want to override the
 145 pathname, file permissions, or ownership.
 146 .\"
 147 .Ss Release resources
 148 See
 149 .Xr archive_read_free 3 .
 150 .Pp
 151 Once you have finished reading data from the archive, you
 152 should call
 153 .Fn archive_read_close
 154 to close the archive, then call
 155 .Fn archive_read_free
 156 to release all resources, including all memory allocated by the library.
 157 .\"
 158 .Sh EXAMPLE
 159 The following illustrates basic usage of the library.
 160 In this example,
 161 the callback functions are simply wrappers around the standard
 162 .Xr open 2 ,
 163 .Xr read 2 ,
 164 and
 165 .Xr close 2
 166 system calls.
 167 .Bd -literal -offset indent
 168 void
 169 list_archive(const char *name)
 170 {
 171   struct mydata *mydata;
 172   struct archive *a;
 173   struct archive_entry *entry;
 174
 175   mydata = malloc(sizeof(struct mydata));
 176   a = archive_read_new();
 177   mydata->name = name;
 178   archive_read_support_filter_all(a);
 179   archive_read_support_format_all(a);
 180   archive_read_open(a, mydata, myopen, myread, myclose);
 181   while (archive_read_next_header(a, &entry) == ARCHIVE_OK) {
 182     printf("%s\en",archive_entry_pathname(entry));
 183     archive_read_data_skip(a);
 184   }
 185   archive_read_free(a);
 186   free(mydata);
 187 }
 188
 189 la_ssize_t
 190 myread(struct archive *a, void *client_data, const void **buff)
 191 {
 192   struct mydata *mydata = client_data;
 193
 194   *buff = mydata->buff;
 195   return (read(mydata->fd, mydata->buff, 10240));
 196 }
 197
 198 int
 199 myopen(struct archive *a, void *client_data)
 200 {
 201   struct mydata *mydata = client_data;
 202
 203   mydata->fd = open(mydata->name, O_RDONLY);
 204   return (mydata->fd >= 0 ? ARCHIVE_OK : ARCHIVE_FATAL);
 205 }
 206
 207 int
 208 myclose(struct archive *a, void *client_data)
 209 {
 210   struct mydata *mydata = client_data;
 211
 212   if (mydata->fd > 0)
 213     close(mydata->fd);
 214   return (ARCHIVE_OK);
 215 }
 216 .Ed
 217 .\" .Sh ERRORS
 218 .Sh SEE ALSO
 219 .Xr tar 1 ,
 220 .Xr libarchive 3 ,
 221 .Xr archive_read_new 3 ,
 222 .Xr archive_read_data 3 ,
 223 .Xr archive_read_extract 3 ,
 224 .Xr archive_read_filter 3 ,
 225 .Xr archive_read_format 3 ,
 226 .Xr archive_read_header 3 ,
 227 .Xr archive_read_open 3 ,
 228 .Xr archive_read_set_options 3 ,
 229 .Xr archive_util 3 ,
 230 .Xr tar 5
 231 .Sh HISTORY
 232 The
 233 .Nm libarchive
 234 library first appeared in
 235 .Fx 5.3 .
 236 .Sh AUTHORS
 237 .An -nosplit
 238 The
 239 .Nm libarchive
 240 library was written by
 241 .An Tim Kientzle Aq kientzle@acm.org .
 242 .Sh BUGS
 243 Many traditional archiver programs treat
 244 empty files as valid empty archives.
 245 For example, many implementations of
 246 .Xr tar 1
 247 allow you to append entries to an empty file.
 248 Of course, it is impossible to determine the format of an empty file
 249 by inspecting the contents, so this library treats empty files as
 250 having a special
 251 .Dq empty
 252 format.