doc/html/libarchive.3.html

   1 <!-- Creator     : groff version 1.22.3 -->
   2 <!-- CreationDate: Sun Feb 19 09:11:19 2017 -->
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   4 "http://www.w3.org/TR/html4/loose.dtd">
   5 <html>
   6 <head>
   7 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   8 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   9 <meta name="Content-Style" content="text/css">
  10 <style type="text/css">
  11        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
  12        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
  13        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
  14        h1      { text-align: center }
  15 </style>
  16 <title></title>
  17 </head>
  18 <body>
  19
  20 <hr>
  21
  22
  23 <p>LIBARCHIVE(3) BSD Library Functions Manual
  24 LIBARCHIVE(3)</p>
  25
  26 <p style="margin-top: 1em"><b>NAME</b></p>
  27
  28 <p style="margin-left:6%;"><b>libarchive</b> &mdash;
  29 functions for reading and writing streaming archives</p>
  30
  31 <p style="margin-top: 1em"><b>OVERVIEW</b></p>
  32
  33 <p style="margin-left:6%;">The <b>libarchive</b> library
  34 provides a flexible interface for reading and writing
  35 archives in various formats such as tar and cpio.
  36 <b>libarchive</b> also supports reading and writing archives
  37 compressed using various compression filters such as gzip
  38 and bzip2. The library is inherently stream-oriented;
  39 readers serially iterate through the archive, writers
  40 serially add things to the archive. In particular, note that
  41 there is currently no built-in support for random access nor
  42 for in-place modification.</p>
  43
  44 <p style="margin-left:6%; margin-top: 1em">When reading an
  45 archive, the library automatically detects the format and
  46 the compression. The library currently has read support
  47 for:</p>
  48
  49 <p><b>&bull;</b></p>
  50
  51 <p style="margin-left:12%;">old-style tar archives,</p>
  52
  53 <p><b>&bull;</b></p>
  54
  55 <p style="margin-left:12%;">most variants of the POSIX
  56 &rsquo;&rsquo;ustar&rsquo;&rsquo; format,</p>
  57
  58 <p><b>&bull;</b></p>
  59
  60 <p style="margin-left:12%;">the POSIX &rsquo;&rsquo;pax
  61 interchange&rsquo;&rsquo; format,</p>
  62
  63 <p><b>&bull;</b></p>
  64
  65 <p style="margin-left:12%;">GNU-format tar archives,</p>
  66
  67 <p><b>&bull;</b></p>
  68
  69 <p style="margin-left:12%;">most common cpio archive
  70 formats,</p>
  71
  72 <p><b>&bull;</b></p>
  73
  74 <p style="margin-left:12%;">ISO9660 CD images (including
  75 RockRidge and Joliet extensions),</p>
  76
  77 <p><b>&bull;</b></p>
  78
  79 <p style="margin-left:12%;">Zip archives,</p>
  80
  81 <p><b>&bull;</b></p>
  82
  83 <p style="margin-left:12%;">ar archives (including GNU/SysV
  84 and BSD extensions),</p>
  85
  86 <p><b>&bull;</b></p>
  87
  88 <p style="margin-left:12%;">Microsoft CAB archives,</p>
  89
  90 <p><b>&bull;</b></p>
  91
  92 <p style="margin-left:12%;">LHA archives,</p>
  93
  94 <p><b>&bull;</b></p>
  95
  96 <p style="margin-left:12%;">mtree file tree
  97 descriptions,</p>
  98
  99 <p><b>&bull;</b></p>
 100
 101 <p style="margin-left:12%;">RAR archives,</p>
 102
 103 <p><b>&bull;</b></p>
 104
 105 <p style="margin-left:12%;">XAR archives.</p>
 106
 107 <p style="margin-left:6%;">The library automatically
 108 detects archives compressed with gzip(1), bzip2(1), xz(1),
 109 lzip(1), or compress(1) and decompresses them transparently.
 110 It can similarly detect and decode archives processed with
 111 uuencode(1) or which have an rpm(1) header.</p>
 112
 113 <p style="margin-left:6%; margin-top: 1em">When writing an
 114 archive, you can specify the compression to be used and the
 115 format to use. The library can write</p>
 116
 117 <p><b>&bull;</b></p>
 118
 119 <p style="margin-left:12%;">POSIX-standard
 120 &rsquo;&rsquo;ustar&rsquo;&rsquo; archives,</p>
 121
 122 <p><b>&bull;</b></p>
 123
 124 <p style="margin-left:12%;">POSIX &rsquo;&rsquo;pax
 125 interchange format&rsquo;&rsquo; archives,</p>
 126
 127 <p><b>&bull;</b></p>
 128
 129 <p style="margin-left:12%;">POSIX octet-oriented cpio
 130 archives,</p>
 131
 132 <p><b>&bull;</b></p>
 133
 134 <p style="margin-left:12%;">Zip archive,</p>
 135
 136 <p><b>&bull;</b></p>
 137
 138 <p style="margin-left:12%;">two different variants of shar
 139 archives,</p>
 140
 141 <p><b>&bull;</b></p>
 142
 143 <p style="margin-left:12%;">ISO9660 CD images,</p>
 144
 145 <p><b>&bull;</b></p>
 146
 147 <p style="margin-left:12%;">7-Zip archives,</p>
 148
 149 <p><b>&bull;</b></p>
 150
 151 <p style="margin-left:12%;">ar archives,</p>
 152
 153 <p><b>&bull;</b></p>
 154
 155 <p style="margin-left:12%;">mtree file tree
 156 descriptions,</p>
 157
 158 <p><b>&bull;</b></p>
 159
 160 <p style="margin-left:12%;">XAR archives.</p>
 161
 162 <p style="margin-left:6%;">Pax interchange format is an
 163 extension of the tar archive format that eliminates
 164 essentially all of the limitations of historic tar formats
 165 in a standard fashion that is supported by POSIX-compliant
 166 pax(1) implementations on many systems as well as several
 167 newer implementations of tar(1). Note that the default write
 168 format will suppress the pax extended attributes for most
 169 entries; explicitly requesting pax format will enable those
 170 attributes for all entries.</p>
 171
 172 <p style="margin-left:6%; margin-top: 1em">The read and
 173 write APIs are accessed through the
 174 <b>archive_read_XXX</b>() functions and the
 175 <b>archive_write_XXX</b>() functions, respectively, and
 176 either can be used independently of the other.</p>
 177
 178 <p style="margin-left:6%; margin-top: 1em">The rest of this
 179 manual page provides an overview of the library operation.
 180 More detailed information can be found in the individual
 181 manual pages for each API or utility function.</p>
 182
 183 <p style="margin-top: 1em"><b>READING AN ARCHIVE</b></p>
 184
 185 <p style="margin-left:6%;">See archive_read(3).</p>
 186
 187 <p style="margin-top: 1em"><b>WRITING AN ARCHIVE</b></p>
 188
 189 <p style="margin-left:6%;">See archive_write(3).</p>
 190
 191 <p style="margin-top: 1em"><b>WRITING ENTRIES TO
 192 DISK</b></p>
 193
 194 <p style="margin-left:6%;">The archive_write_disk(3) API
 195 allows you to write archive_entry(3) objects to disk using
 196 the same API used by archive_write(3). The
 197 archive_write_disk(3) API is used internally by
 198 <b>archive_read_extract</b>(); using it directly can provide
 199 greater control over how entries get written to disk. This
 200 API also makes it possible to share code between
 201 archive-to-archive copy and archive-to-disk extraction
 202 operations.</p>
 203
 204 <p style="margin-top: 1em"><b>READING ENTRIES FROM
 205 DISK</b></p>
 206
 207 <p style="margin-left:6%;">The archive_read_disk(3)
 208 supports for populating archive_entry(3) objects from
 209 information in the filesystem. This includes the information
 210 accessible from the stat(2) system call as well as ACLs,
 211 extended attributes, and other metadata. The
 212 archive_read_disk(3) API also supports iterating over
 213 directory trees, which allows directories of files to be
 214 read using an API compatible with the archive_read(3)
 215 API.</p>
 216
 217 <p style="margin-top: 1em"><b>DESCRIPTION</b></p>
 218
 219 <p style="margin-left:6%;">Detailed descriptions of each
 220 function are provided by the corresponding manual pages.</p>
 221
 222 <p style="margin-left:6%; margin-top: 1em">All of the
 223 functions utilize an opaque struct archive datatype that
 224 provides access to the archive contents.</p>
 225
 226 <p style="margin-left:6%; margin-top: 1em">The struct
 227 archive_entry structure contains a complete description of a
 228 single archive entry. It uses an opaque interface that is
 229 fully documented in archive_entry(3).</p>
 230
 231 <p style="margin-left:6%; margin-top: 1em">Users familiar
 232 with historic formats should be aware that the newer
 233 variants have eliminated most restrictions on the length of
 234 textual fields. Clients should not assume that filenames,
 235 link names, user names, or group names are limited in
 236 length. In particular, pax interchange format can easily
 237 accommodate pathnames in arbitrary character sets that
 238 exceed <i>PATH_MAX</i>.</p>
 239
 240 <p style="margin-top: 1em"><b>RETURN VALUES</b></p>
 241
 242 <p style="margin-left:6%;">Most functions return
 243 <b>ARCHIVE_OK</b> (zero) on success, non-zero on error. The
 244 return value indicates the general severity of the error,
 245 ranging from <b>ARCHIVE_WARN</b>, which indicates a minor
 246 problem that should probably be reported to the user, to
 247 <b>ARCHIVE_FATAL</b>, which indicates a serious problem that
 248 will prevent any further operations on this archive. On
 249 error, the <b>archive_errno</b>() function can be used to
 250 retrieve a numeric error code (see errno(2)). The
 251 <b>archive_error_string</b>() returns a textual error
 252 message suitable for display.</p>
 253
 254
 255 <p style="margin-left:6%; margin-top: 1em"><b>archive_read_new</b>()
 256 and <b>archive_write_new</b>() return pointers to an
 257 allocated and initialized struct archive object.</p>
 258
 259
 260 <p style="margin-left:6%; margin-top: 1em"><b>archive_read_data</b>()
 261 and <b>archive_write_data</b>() return a count of the number
 262 of bytes actually read or written. A value of zero indicates
 263 the end of the data for this entry. A negative value
 264 indicates an error, in which case the <b>archive_errno</b>()
 265 and <b>archive_error_string</b>() functions can be used to
 266 obtain more information.</p>
 267
 268 <p style="margin-top: 1em"><b>ENVIRONMENT</b></p>
 269
 270 <p style="margin-left:6%;">There are character set
 271 conversions within the archive_entry(3) functions that are
 272 impacted by the currently-selected locale.</p>
 273
 274 <p style="margin-top: 1em"><b>SEE ALSO</b></p>
 275
 276 <p style="margin-left:6%;">tar(1), archive_entry(3),
 277 archive_read(3), archive_util(3), archive_write(3),
 278 tar(5)</p>
 279
 280 <p style="margin-top: 1em"><b>HISTORY</b></p>
 281
 282 <p style="margin-left:6%;">The <b>libarchive</b> library
 283 first appeared in FreeBSD&nbsp;5.3.</p>
 284
 285 <p style="margin-top: 1em"><b>AUTHORS</b></p>
 286
 287 <p style="margin-left:6%;">The <b>libarchive</b> library
 288 was originally written by Tim Kientzle
 289 &lt;kientzle@acm.org&gt;.</p>
 290
 291 <p style="margin-top: 1em"><b>BUGS</b></p>
 292
 293 <p style="margin-left:6%;">Some archive formats support
 294 information that is not supported by struct archive_entry.
 295 Such information cannot be fully archived or restored using
 296 this library. This includes, for example, comments,
 297 character sets, or the arbitrary key/value pairs that can
 298 appear in pax interchange format archives.</p>
 299
 300 <p style="margin-left:6%; margin-top: 1em">Conversely, of
 301 course, not all of the information that can be stored in an
 302 struct archive_entry is supported by all formats. For
 303 example, cpio formats do not support nanosecond timestamps;
 304 old tar formats do not support large device numbers.</p>
 305
 306 <p style="margin-left:6%; margin-top: 1em">The ISO9660
 307 reader cannot yet read all ISO9660 images; it should learn
 308 how to seek.</p>
 309
 310 <p style="margin-left:6%; margin-top: 1em">The AR writer
 311 requires the client program to use two passes, unlike all
 312 other libarchive writers.</p>
 313
 314 <p style="margin-left:6%; margin-top: 1em">BSD
 315 March&nbsp;18, 2012 BSD</p>
 316 <hr>
 317 </body>
 318 </html>