contrib/libarchive/libarchive/libarchive.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: src/lib/libarchive/libarchive.3,v 1.11 2007/01/09 08:05:56 kientzle Exp $
  26 .\"
  27 .Dd February 6, 2010
  28 .Dt LIBARCHIVE 3
  29 .Os
  30 .Sh NAME
  31 .Nm libarchive
  32 .Nd functions for reading and writing streaming archives
  33 .Sh LIBRARY
  34 .Lb libarchive
  35 .Sh OVERVIEW
  36 The
  37 .Nm
  38 library provides a flexible interface for reading and writing
  39 archives in various formats such as tar and cpio.
  40 .Nm
  41 also supports reading and writing archives compressed using
  42 various compression filters such as gzip and bzip2.
  43 The library is inherently stream-oriented; readers serially iterate through
  44 the archive, writers serially add things to the archive.
  45 In particular, note that there is currently no built-in support for
  46 random access nor for in-place modification.
  47 .Pp
  48 When reading an archive, the library automatically detects the
  49 format and the compression.
  50 The library currently has read support for:
  51 .Bl -bullet -compact
  52 .It
  53 old-style tar archives,
  54 .It
  55 most variants of the POSIX
  56 .Dq ustar
  57 format,
  58 .It
  59 the POSIX
  60 .Dq pax interchange
  61 format,
  62 .It
  63 GNU-format tar archives,
  64 .It
  65 most common cpio archive formats,
  66 .It
  67 ISO9660 CD images (including RockRidge and Joliet extensions),
  68 .It
  69 Zip archives.
  70 .El
  71 The library automatically detects archives compressed with
  72 .Xr gzip 1 ,
  73 .Xr bzip2 1 ,
  74 .Xr xz 1 ,
  75 or
  76 .Xr compress 1
  77 and decompresses them transparently.
  78 .Pp
  79 When writing an archive, you can specify the compression
  80 to be used and the format to use.
  81 The library can write
  82 .Bl -bullet -compact
  83 .It
  84 POSIX-standard
  85 .Dq ustar
  86 archives,
  87 .It
  88 POSIX
  89 .Dq pax interchange format
  90 archives,
  91 .It
  92 POSIX octet-oriented cpio archives,
  93 .It
  94 Zip archive,
  95 .It
  96 two different variants of shar archives.
  97 .El
  98 Pax interchange format is an extension of the tar archive format that
  99 eliminates essentially all of the limitations of historic tar formats
 100 in a standard fashion that is supported
 101 by POSIX-compliant
 102 .Xr pax 1
 103 implementations on many systems as well as several newer implementations of
 104 .Xr tar 1 .
 105 Note that the default write format will suppress the pax extended
 106 attributes for most entries; explicitly requesting pax format will
 107 enable those attributes for all entries.
 108 .Pp
 109 The read and write APIs are accessed through the
 110 .Fn archive_read_XXX
 111 functions and the
 112 .Fn archive_write_XXX
 113 functions, respectively, and either can be used independently
 114 of the other.
 115 .Pp
 116 The rest of this manual page provides an overview of the library
 117 operation.
 118 More detailed information can be found in the individual manual
 119 pages for each API or utility function.
 120 .\"
 121 .Sh READING AN ARCHIVE
 122 See
 123 .Xr libarchive_read 3 .
 124 .\"
 125 .Sh WRITING AN ARCHIVE
 126 See
 127 .Xr libarchive_write 3 .
 128 .\"
 129 .Sh WRITING ENTRIES TO DISK
 130 The
 131 .Xr archive_write_disk 3
 132 API allows you to write
 133 .Xr archive_entry 3
 134 objects to disk using the same API used by
 135 .Xr archive_write 3 .
 136 The
 137 .Xr archive_write_disk 3
 138 API is used internally by
 139 .Fn archive_read_extract ;
 140 using it directly can provide greater control over how entries
 141 get written to disk.
 142 This API also makes it possible to share code between
 143 archive-to-archive copy and archive-to-disk extraction
 144 operations.
 145 .Sh READING ENTRIES FROM DISK
 146 The
 147 .Xr archive_read_disk 3
 148 provides some support for populating
 149 .Xr archive_entry 3
 150 objects from information in the filesystem.
 151 .Sh DESCRIPTION
 152 Detailed descriptions of each function are provided by the
 153 corresponding manual pages.
 154 .Pp
 155 All of the functions utilize an opaque
 156 .Tn struct archive
 157 datatype that provides access to the archive contents.
 158 .Pp
 159 The
 160 .Tn struct archive_entry
 161 structure contains a complete description of a single archive
 162 entry.
 163 It uses an opaque interface that is fully documented in
 164 .Xr archive_entry 3 .
 165 .Pp
 166 Users familiar with historic formats should be aware that the newer
 167 variants have eliminated most restrictions on the length of textual fields.
 168 Clients should not assume that filenames, link names, user names, or
 169 group names are limited in length.
 170 In particular, pax interchange format can easily accommodate pathnames
 171 in arbitrary character sets that exceed
 172 .Va PATH_MAX .
 173 .Sh RETURN VALUES
 174 Most functions return
 175 .Cm ARCHIVE_OK
 176 (zero) on success, non-zero on error.
 177 The return value indicates the general severity of the error, ranging
 178 from
 179 .Cm ARCHIVE_WARN ,
 180 which indicates a minor problem that should probably be reported
 181 to the user, to
 182 .Cm ARCHIVE_FATAL ,
 183 which indicates a serious problem that will prevent any further
 184 operations on this archive.
 185 On error, the
 186 .Fn archive_errno
 187 function can be used to retrieve a numeric error code (see
 188 .Xr errno 2 ) .
 189 The
 190 .Fn archive_error_string
 191 returns a textual error message suitable for display.
 192 .Pp
 193 .Fn archive_read_new
 194 and
 195 .Fn archive_write_new
 196 return pointers to an allocated and initialized
 197 .Tn struct archive
 198 object.
 199 .Pp
 200 .Fn archive_read_data
 201 and
 202 .Fn archive_write_data
 203 return a count of the number of bytes actually read or written.
 204 A value of zero indicates the end of the data for this entry.
 205 A negative value indicates an error, in which case the
 206 .Fn archive_errno
 207 and
 208 .Fn archive_error_string
 209 functions can be used to obtain more information.
 210 .Sh ENVIRONMENT
 211 There are character set conversions within the
 212 .Xr archive_entry 3
 213 functions that are impacted by the currently-selected locale.
 214 .Sh SEE ALSO
 215 .Xr tar 1 ,
 216 .Xr archive_entry 3 ,
 217 .Xr archive_read 3 ,
 218 .Xr archive_util 3 ,
 219 .Xr archive_write 3 ,
 220 .Xr tar 5
 221 .Sh HISTORY
 222 The
 223 .Nm libarchive
 224 library first appeared in
 225 .Fx 5.3 .
 226 .Sh AUTHORS
 227 .An -nosplit
 228 The
 229 .Nm libarchive
 230 library was written by
 231 .An Tim Kientzle Aq kientzle@acm.org .
 232 .Sh BUGS
 233 Some archive formats support information that is not supported by
 234 .Tn struct archive_entry .
 235 Such information cannot be fully archived or restored using this library.
 236 This includes, for example, comments, character sets,
 237 or the arbitrary key/value pairs that can appear in
 238 pax interchange format archives.
 239 .Pp
 240 Conversely, of course, not all of the information that can be
 241 stored in an
 242 .Tn struct archive_entry
 243 is supported by all formats.
 244 For example, cpio formats do not support nanosecond timestamps;
 245 old tar formats do not support large device numbers.
 246 .Pp
 247 The
 248 .Xr archive_read_disk 3
 249 API should support iterating over filesystems;
 250 that would make it possible to share code among
 251 disk-to-archive, archive-to-archive, archive-to-disk,
 252 and disk-to-disk operations.
 253 Currently, it only supports reading the
 254 information for a single file.
 255 (Which is still quite useful, as it hides a lot
 256 of system-specific details.)