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