contrib/libarchive/libarchive/archive_read_set_options.3

   1 .\" Copyright (c) 2011 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_OPTIONS 3
  29 .Os
  30 .Sh NAME
  31 .Nm archive_read_set_filter_option ,
  32 .Nm archive_read_set_format_option ,
  33 .Nm archive_read_set_option ,
  34 .Nm archive_read_set_options
  35 .Nd functions controlling options for reading archives
  36 .\"
  37 .Sh LIBRARY
  38 Streaming Archive Library (libarchive, -larchive)
  39 .Sh SYNOPSIS
  40 .Ft int
  41 .Fo archive_read_set_filter_option
  42 .Fa "struct archive *"
  43 .Fa "const char *module"
  44 .Fa "const char *option"
  45 .Fa "const char *value"
  46 .Fc
  47 .Ft int
  48 .Fo archive_read_set_format_option
  49 .Fa "struct archive *"
  50 .Fa "const char *module"
  51 .Fa "const char *option"
  52 .Fa "const char *value"
  53 .Fc
  54 .Ft int
  55 .Fo archive_read_set_option
  56 .Fa "struct archive *"
  57 .Fa "const char *module"
  58 .Fa "const char *option"
  59 .Fa "const char *value"
  60 .Fc
  61 .Ft int
  62 .Fo archive_read_set_options
  63 .Fa "struct archive *"
  64 .Fa "const char *options"
  65 .Fc
  66 .Sh DESCRIPTION
  67 These functions provide a way for libarchive clients to configure
  68 specific read modules.
  69 .Bl -tag -width indent
  70 .It Xo
  71 .Fn archive_read_set_filter_option ,
  72 .Fn archive_read_set_format_option
  73 .Xc
  74 Specifies an option that will be passed to currently-registered
  75 filters (including decompression filters) or format readers.
  76 .Pp
  77 If
  78 .Ar option
  79 and
  80 .Ar value
  81 are both
  82 .Dv NULL ,
  83 these functions will do nothing and
  84 .Cm ARCHIVE_OK
  85 will be returned.
  86 If
  87 .Ar option
  88 is
  89 .Dv NULL
  90 but
  91 .Ar value
  92 is not, these functions will do nothing and
  93 .Cm ARCHIVE_FAILED
  94 will be returned.
  95 .Pp
  96 If
  97 .Ar module
  98 is not
  99 .Dv NULL ,
 100 .Ar option
 101 and
 102 .Ar value
 103 will be provided to the filter or reader named
 104 .Ar module .
 105 The return value will be that of the module.
 106 If there is no such module,
 107 .Cm ARCHIVE_FAILED
 108 will be returned.
 109 .Pp
 110 If
 111 .Ar module
 112 is
 113 .Dv NULL ,
 114 .Ar option
 115 and
 116 .Ar value
 117 will be provided to every registered module.
 118 If any module returns
 119 .Cm ARCHIVE_FATAL ,
 120 this value will be returned immediately.
 121 Otherwise,
 122 .Cm ARCHIVE_OK
 123 will be returned if any module accepts the option, and
 124 .Cm ARCHIVE_FAILED
 125 in all other cases.
 126 .\"
 127 .It Xo
 128 .Fn archive_read_set_option
 129 .Xc
 130 Calls
 131 .Fn archive_read_set_format_option ,
 132 then
 133 .Fn archive_read_set_filter_option .
 134 If either function returns
 135 .Cm ARCHIVE_FATAL ,
 136 .Cm ARCHIVE_FATAL
 137 will be returned
 138 immediately.
 139 Otherwise, greater of the two values will be returned.
 140 .\"
 141 .It Xo
 142 .Fn archive_read_set_options
 143 .Xc
 144 .Ar options
 145 is a comma-separated list of options.
 146 If
 147 .Ar options
 148 is
 149 .Dv NULL
 150 or empty,
 151 .Cm ARCHIVE_OK
 152 will be returned immediately.
 153 .Pp
 154 Calls
 155 .Fn archive_read_set_option
 156 with each option in turn.
 157 If any
 158 .Fn archive_read_set_option
 159 call returns
 160 .Cm ARCHIVE_FATAL ,
 161 .Cm ARCHIVE_FATAL
 162 will be returned immediately.
 163 .Pp
 164 Individual options have one of the following forms:
 165 .Bl -tag -compact -width indent
 166 .It Ar option=value
 167 The option/value pair will be provided to every module.
 168 Modules that do not accept an option with this name will ignore it.
 169 .It Ar option
 170 The option will be provided to every module with a value of
 171 .Dq 1 .
 172 .It Ar !option
 173 The option will be provided to every module with a NULL value.
 174 .It Ar module:option=value , Ar module:option , Ar module:!option
 175 As above, but the corresponding option and value will be provided
 176 only to modules whose name matches
 177 .Ar module .
 178 .El
 179 .El
 180 .\"
 181 .Sh OPTIONS
 182 .Bl -tag -compact -width indent
 183 .It Format iso9660
 184 .Bl -tag -compact -width indent
 185 .It Cm joliet
 186 Support Joliet extensions.
 187 Defaults to enabled, use
 188 .Cm !joliet
 189 to disable.
 190 .It Cm rockridge
 191 Support RockRidge extensions.
 192 Defaults to enabled, use
 193 .Cm !rockridge
 194 to disable.
 195 .El
 196 .It Format tar
 197 .Bl -tag -compact -width indent
 198 .It Cm compat-2x
 199 Libarchive 2.x incorrectly encoded Unicode filenames on
 200 some platforms.
 201 This option mimics the libarchive 2.x filename handling
 202 so that such archives can be read correctly.
 203 .It Cm hdrcharset
 204 The value is used as a character set name that will be
 205 used when translating filenames.
 206 .It Cm mac-ext
 207 Support Mac OS metadata extension that records data in special
 208 files beginning with a period and underscore.
 209 Defaults to enabled on Mac OS, disabled on other platforms.
 210 Use
 211 .Cm !mac-ext
 212 to disable.
 213 .It Cm read_concatenated_archives
 214 Ignore zeroed blocks in the archive, which occurs when multiple tar archives
 215 have been concatenated together.  Without this option, only the contents of
 216 the first concatenated archive would be read.
 217 .El
 218 .El
 219 .\"
 220 .Sh ERRORS
 221 Detailed error codes and textual descriptions are available from the
 222 .Fn archive_errno
 223 and
 224 .Fn archive_error_string
 225 functions.
 226 .\"
 227 .Sh SEE ALSO
 228 .Xr tar 1 ,
 229 .Xr libarchive 3 ,
 230 .Xr archive_write_set_options 3 ,
 231 .Xr archive_read 3