Import libarchive-3.0.4.
[dragonfly.git] / 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 .El
197 .\"
198 .Sh ERRORS
199 Detailed error codes and textual descriptions are available from the
200 .Fn archive_errno
201 and
202 .Fn archive_error_string
203 functions.
204 .\"
205 .Sh SEE ALSO
206 .Xr tar 1 ,
207 .Xr libarchive 3 ,
208 .Xr archive_write_set_options 3 ,
209 .Xr archive_read 3