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 hdrcharset
192The value is used as a character set name that will be
193used when translating file names.
194.El
195.It Format iso9660
196.Bl -tag -compact -width indent
197.It Cm joliet
198Support Joliet extensions.
199Defaults to enabled, use
200.Cm !joliet
201to disable.
202.It Cm rockridge
203Support RockRidge extensions.
204Defaults to enabled, use
205.Cm !rockridge
206to disable.
207.El
208.It Format lha
209.Bl -tag -compact -width indent
210.It Cm hdrcharset
211The value is used as a character set name that will be
212used when translating file names.
213.El
214.It Format mtree
215.Bl -tag -compact -width indent
216.It Cm checkfs
217Allow reading information missing from the mtree from the file system.
218Disabled by default.
219.El
220.It Format rar
221.Bl -tag -compact -width indent
222.It Cm hdrcharset
223The value is used as a character set name that will be
224used when translating file names.
225.El
226.It Format tar
227.Bl -tag -compact -width indent
228.It Cm compat-2x
229Libarchive 2.x incorrectly encoded Unicode filenames on
230some platforms.
231This option mimics the libarchive 2.x filename handling
232so that such archives can be read correctly.
233.It Cm hdrcharset
234The value is used as a character set name that will be
235used when translating file names.
236.It Cm mac-ext
237Support Mac OS metadata extension that records data in special
238files beginning with a period and underscore.
239Defaults to enabled on Mac OS, disabled on other platforms.
240Use
241.Cm !mac-ext
242to disable.
243.It Cm read_concatenated_archives
244Ignore zeroed blocks in the archive, which occurs when multiple tar archives
245have been concatenated together.
246Without this option, only the contents of
247the first concatenated archive would be read.
248.El
249.El
250.\"
251.Sh ERRORS
252Detailed error codes and textual descriptions are available from the
253.Fn archive_errno
254and
255.Fn archive_error_string
256functions.
257.\"
258.Sh SEE ALSO
259.Xr tar 1 ,
260.Xr archive_read 3 ,
261.Xr archive_write_set_options 3 ,
262.Xr libarchive 3
263