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