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