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 February 2, 2012 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 iso9660 184.Bl -tag -compact -width indent 185.It Cm joliet 186Support Joliet extensions. 187Defaults to enabled, use 188.Cm !joliet 189to disable. 190.It Cm rockridge 191Support RockRidge extensions. 192Defaults to enabled, use 193.Cm !rockridge 194to disable. 195.El 196.El 197.\" 198.Sh ERRORS 199Detailed error codes and textual descriptions are available from the 200.Fn archive_errno 201and 202.Fn archive_error_string 203functions. 204.\" 205.Sh SEE ALSO 206.Xr tar 1 , 207.Xr libarchive 3 , 208.Xr archive_write_set_options 3 , 209.Xr archive_read 3 210