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