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