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