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 April 13, 2009
  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 SYNOPSIS
  38 .Ft int
  39 .Fo archive_read_set_filter_option
  40 .Fa "struct archive *"
  41 .Fa "const char *module"
  42 .Fa "const char *option"
  43 .Fa "const char *value"
  44 .Fc
  45 .Ft int
  46 .Fo archive_read_set_format_option
  47 .Fa "struct archive *"
  48 .Fa "const char *module"
  49 .Fa "const char *option"
  50 .Fa "const char *value"
  51 .Fc
  52 .Ft int
  53 .Fo archive_read_set_option
  54 .Fa "struct archive *"
  55 .Fa "const char *module"
  56 .Fa "const char *option"
  57 .Fa "const char *value"
  58 .Fc
  59 .Ft int
  60 .Fo archive_read_set_options
  61 .Fa "struct archive *"
  62 .Fa "const char *options"
  63 .Fc
  64 .Sh DESCRIPTION
  65 These functions provide a way for libarchive clients to configure
  66 specific read modules.
  67 .Bl -tag -width indent
  68 .It Xo
  69 .Fn archive_read_set_filter_option ,
  70 .Fn archive_read_set_format_option
  71 .Xc
  72 Specifies an option that will be passed to currently-registered
  73 filters (including decompression filters) or format readers.
  74 .Pp
  75 If
  76 .Ar option
  77 and
  78 .Ar value
  79 are both
  80 .Dv NULL ,
  81 these functions will do nothing and
  82 .Cm ARCHIVE_OK
  83 will be returned.
  84 If
  85 .Ar option
  86 is
  87 .Dv NULL
  88 but
  89 .Ar value
  90 is not, these functions will do nothing and
  91 .Cm ARCHIVE_FAILED
  92 will be returned.
  93 .Pp
  94 If
  95 .Ar module
  96 is not
  97 .Dv NULL ,
  98 .Ar option
  99 and
 100 .Ar value
 101 will be provided to the filter or reader named
 102 .Ar module .
 103 The return value will be that of the module.
 104 If there is no such module,
 105 .Cm ARCHIVE_FAILED
 106 will be returned.
 107 .Pp
 108 If
 109 .Ar module
 110 is
 111 .Dv NULL ,
 112 .Ar option
 113 and
 114 .Ar value
 115 will be provided to every registered module.
 116 If any module returns
 117 .Cm ARCHIVE_FATAL ,
 118 this value will be returned immediately.
 119 Otherwise,
 120 .Cm ARCHIVE_OK
 121 will be returned if any module accepts the option, and
 122 .Cm ARCHIVE_FAILED
 123 in all other cases.
 124 .\"
 125 .It Xo
 126 .Fn archive_read_set_option
 127 .Xc
 128 Calls
 129 .Fn archive_read_set_format_option ,
 130 then
 131 .Fn archive_read_set_filter_option .
 132 If either function returns
 133 .Cm ARCHIVE_FATAL ,
 134 .Cm ARCHIVE_FATAL
 135 will be returned
 136 immediately.
 137 Otherwise, greater of the two values will be returned.
 138 .\"
 139 .It Xo
 140 .Fn archive_read_set_options
 141 .Xc
 142 .Ar options
 143 is a comma-separated list of options.
 144 If
 145 .Ar options
 146 is
 147 .Dv NULL
 148 or empty,
 149 .Cm ARCHIVE_OK
 150 will be returned immediately.
 151 .Pp
 152 Calls
 153 .Fn archive_read_set_option
 154 with each option in turn.
 155 If any
 156 .Fn archive_read_set_option
 157 call returns
 158 .Cm ARCHIVE_FATAL ,
 159 .Cm ARCHIVE_FATAL
 160 will be returned immediately.
 161 .Pp
 162 Individual options have one of the following forms:
 163 .Bl -tag -compact -width indent
 164 .It Ar option=value
 165 The option/value pair will be provided to every module.
 166 Modules that do not accept an option with this name will ignore it.
 167 .It Ar option
 168 The option will be provided to every module with a value of
 169 .Dq 1 .
 170 .It Ar !option
 171 The option will be provided to every module with a NULL value.
 172 .It Ar module:option=value , Ar module:option , Ar module:!option
 173 As above, but the corresponding option and value will be provided
 174 only to modules whose name matches
 175 .Ar module .
 176 .El
 177 .El
 178 .\"
 179 .Sh OPTIONS
 180 .Bl -tag -compact -width indent
 181 .It Format iso9660
 182 .Bl -tag -compact -width indent
 183 .It Cm joliet
 184 Support Joliet extensions.
 185 Defaults to enabled, use
 186 .Cm !joliet
 187 to disable.
 188 .It Cm rockridge
 189 Support RockRidge extensions.
 190 Defaults to enabled, use
 191 .Cm !rockridge
 192 to disable.
 193 .El
 194 .El
 195 .\"
 196 .Sh ERRORS
 197 Detailed error codes and textual descriptions are available from the
 198 .Fn archive_errno
 199 and
 200 .Fn archive_error_string
 201 functions.
 202 .\"
 203 .Sh SEE ALSO
 204 .Xr tar 1 ,
 205 .Xr libarchive 3 ,
 206 .Xr archive_write_set_options 3 ,
 207 .Xr archive_read 3