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