1.\" Copyright (c) 2003-2010 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_WRITE_OPTIONS 3 29.Os 30.Sh NAME 31.Nm archive_write_set_filter_option , 32.Nm archive_write_set_format_option , 33.Nm archive_write_set_option , 34.Nm archive_write_set_options 35.Nd functions controlling options for reading archives 36.Sh LIBRARY 37Streaming Archive Library (libarchive, -larchive) 38.Sh SYNOPSIS 39.Ft int 40.Fo archive_write_set_filter_option 41.Fa "struct archive *" 42.Fa "const char *module" 43.Fa "const char *option" 44.Fa "const char *value" 45.Fc 46.Ft int 47.Fo archive_write_set_format_option 48.Fa "struct archive *" 49.Fa "const char *module" 50.Fa "const char *option" 51.Fa "const char *value" 52.Fc 53.Ft int 54.Fo archive_write_set_option 55.Fa "struct archive *" 56.Fa "const char *module" 57.Fa "const char *option" 58.Fa "const char *value" 59.Fc 60.Ft int 61.Fo archive_write_set_options 62.Fa "struct archive *" 63.Fa "const char *options" 64.Fc 65.Sh DESCRIPTION 66These functions provide a way for libarchive clients to configure 67specific write modules. 68.Bl -tag -width indent 69.It Xo 70.Fn archive_write_set_filter_option , 71.Fn archive_write_set_format_option 72.Xc 73Specifies an option that will be passed to currently-registered 74filters (including decompression filters) or format readers. 75.Pp 76If 77.Ar option 78and 79.Ar value 80are both 81.Dv NULL , 82these functions will do nothing and 83.Cm ARCHIVE_OK 84will be returned. 85If 86.Ar option 87is 88.Dv NULL 89but 90.Ar value 91is not, these functions will do nothing and 92.Cm ARCHIVE_FAILED 93will be returned. 94.Pp 95If 96.Ar module 97is not 98.Dv NULL , 99.Ar option 100and 101.Ar value 102will be provided to the filter or reader named 103.Ar module . 104The return value will be that of the module. 105If there is no such module, 106.Cm ARCHIVE_FAILED 107will be returned. 108.Pp 109If 110.Ar module 111is 112.Dv NULL , 113.Ar option 114and 115.Ar value 116will be provided to every registered module. 117If any module returns 118.Cm ARCHIVE_FATAL , 119this value will be returned immediately. 120Otherwise, 121.Cm ARCHIVE_OK 122will be returned if any module accepts the option, and 123.Cm ARCHIVE_FAILED 124in all other cases. 125.\" 126.It Xo 127.Fn archive_write_set_option 128.Xc 129Calls 130.Fn archive_write_set_format_option , 131then 132.Fn archive_write_set_filter_option . 133If either function returns 134.Cm ARCHIVE_FATAL , 135.Cm ARCHIVE_FATAL 136will be returned 137immediately. 138Otherwise, greater of the two values will be returned. 139.\" 140.It Xo 141.Fn archive_write_set_options 142.Xc 143.Ar options 144is a comma-separated list of options. 145If 146.Ar options 147is 148.Dv NULL 149or empty, 150.Cm ARCHIVE_OK 151will be returned immediately. 152.Pp 153Individual options have one of the following forms: 154.Bl -tag -compact -width indent 155.It Ar option=value 156The option/value pair will be provided to every module. 157Modules that do not accept an option with this name will ignore it. 158.It Ar option 159The option will be provided to every module with a value of 160.Dq 1 . 161.It Ar !option 162The option will be provided to every module with a NULL value. 163.It Ar module:option=value , Ar module:option , Ar module:!option 164As above, but the corresponding option and value will be provided 165only to modules whose name matches 166.Ar module . 167.El 168.El 169.\" 170.Sh OPTIONS 171.Bl -tag -compact -width indent 172.It Filter gzip 173.Bl -tag -compact -width indent 174.It Cm compression-level 175The value is interpreted as a decimal integer specifying the 176gzip compression level. 177.El 178.It Filter xz 179.Bl -tag -compact -width indent 180.It Cm compression-level 181The value is interpreted as a decimal integer specifying the 182compression level. 183.El 184.It Format mtree 185.Bl -tag -compact -width indent 186.It Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname 187Enable a particular keyword in the mtree output. 188Prefix with an exclamation mark to disable the corresponding keyword. 189The default is equivalent to 190.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . 191.It Cm all 192Enables all of the above keywords. 193.It Cm use-set 194Enables generation of 195.Cm /set 196lines that specify default values for the following files and/or directories. 197.It Cm indent 198XXX needs explanation XXX 199.El 200.It Format iso9660 - volume metadata 201These options are used to set standard ISO9660 metadata. 202.Bl -tag -compact -width indent 203.It Cm abstract-file Ns = Ns Ar filename 204The file with the specified name will be identified in the ISO9660 metadata 205as holding the abstract for this volume. Default: none. 206.It Cm application-id Ns = Ns Ar filename 207The file with the specified name will be identified in the ISO9660 metadata 208as holding the application identifier for this volume. Default: none. 209.It Cm biblio-file Ns = Ns Ar filename 210The file with the specified name will be identified in the ISO9660 metadata 211as holding the bibliography for this volume. Default: none. 212.It Cm copyright-file Ns = Ns Ar filename 213The file with the specified name will be identified in the ISO9660 metadata 214as holding the copyright for this volume. Default: none. 215.It Cm publisher Ns = Ns Ar filename 216The file with the specified name will be identified in the ISO9660 metadata 217as holding the publisher information for this volume. Default: none. 218.It Cm volume-id Ns = Ns Ar string 219The specified string will be used as the Volume Identifier in the ISO9660 metadata. 220It is limited to 32 bytes. Default: none. 221.El 222.It Format iso9660 - boot support 223These options are used to make an ISO9660 image that can be directly 224booted on various systems. 225.Bl -tag -compact -width indent 226.It Cm boot Ns = Ns Ar filename 227The file matching this name will be used as the El Torito boot image file. 228.It Cm boot-catalog Ns = Ns Ar name 229The name that will be used for the El Torito boot catalog. 230Default: 231.Ar boot.catalog 232.It Cm boot-info-table 233The boot image file provided by the 234.Cm boot Ns = Ns Ar filename 235option will be edited with appropriate boot information in bytes 8 through 64. 236Default: disabled 237.It Cm boot-load-seg Ns = Ns Ar hexadecimal-number 238The load segment for a no-emulation boot image. 239.It Cm boot-load-size Ns = Ns Ar decimal-number 240The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image. 241Some very old BIOSes can only load very small images, setting this 242value to 4 will often allow such BIOSes to load the first part of 243the boot image (which will then need to be intelligent enough to 244load the rest of itself). 245This should not be needed unless you are trying to support systems with very old BIOSes. 246This defaults to the full size of the image. 247.It Cm boot-type Ns = Ns Ar value 248Specifies the boot semantics used by the El Torito boot image: 249If the 250.Ar value 251is 252.Cm fd , 253then the boot image is assumed to be a bootable floppy image. 254If the 255.Ar value 256is 257.Cm hd , 258then the the boot image is assumed to be a bootable hard disk image. 259If the 260.Ar value 261is 262.Cm no-emulation , 263the boot image is used without floppy or hard disk emulation. 264If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then 265the default is 266.Cm fd , 267otherwise the default is 268.Cm no-emulation. 269.El 270.It Format iso9660 - filename and size extensions 271Various extensions to the base ISO9660 format. 272.Bl -tag -compact -width indent 273.It Cm allow-ldots 274If enabled, allows filenames to begin with a leading period. 275If disabled, filenames that begin with a leading period will have 276that period replaced by an underscore character in the standard ISO9660 277namespace. 278This does not impact names stored in the Rockridge or Joliet extension area. 279Default: disabled. 280.It Cm allow-lowercase 281If enabled, allows filenames to contain lowercase characters. 282If disabled, filenames will be forced to uppercase. 283This does not impact names stored in the Rockridge or Joliet extension area. 284Default: disabled. 285.It Cm allow-multidot 286If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification. 287If disabled, additional periods will be converted to underscore characters. 288This does not impact names stored in the Rockridge or Joliet extension area. 289Default: disabled. 290.It Cm allow-period 291If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification. 292If disabled,trailing periods will be converted to underscore characters. 293This does not impact names stored in the Rockridge or Joliet extension area. 294Default: disabled. 295.It Cm allow-pvd-lowercase 296If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification. 297If disabled, characters will be converted to uppercase ASCII. 298Default: disabled. 299.It Cm allow-sharp-tilde 300If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification. 301If disabled, such characters will be converted to underscore characters. 302Default: disabled. 303.It Cm allow-vernum 304If enabled, version numbers will be included with files. 305If disabled, version numbers will be suppressed, in violation of the ISO9660 standard. 306This does not impact names stored in the Rockridge or Joliet extension area. 307Default: enabled. 308.It Cm iso-level 309This enables support for file size and file name extensions in the 310core ISO9660 area. 311The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas. 312.Bl -tag -compact -width indent 313.It Cm iso-level=1 314The most compliant form of ISO9660 image. 315Filenames are limited to 8.3 uppercase format, 316directory names are limited to 8 uppercase characters, 317files are limited to 4 GiB, 318the complete ISO9660 image cannot exceed 4 GiB. 319.It Cm iso-level=2 320Filenames are limited to 30 uppercase characters with a 30-character extension, 321directory names are limited to 30 characters, 322files are limited to 4 GiB. 323.It Cm iso-level=3 324As with 325.Cm iso-level=2 , 326except that files may exceed 4 GiB. 327.It Cm iso-level=4 328As with 329.Cm iso-level=3 , 330except that filenames may be up to 193 characters 331and may include arbitrary 8-bit characters. 332.El 333.It Cm joliet 334Microsoft's Joliet extensions store a completely separate set of directory information about each file. 335In particular, this information includes Unicode filenames of up to 255 characters. 336Default: enabled. 337.It Cm limit-depth 338If enabled, libarchive will use directory relocation records to ensure that 339no pathname exceeds the ISO9660 limit of 8 directory levels. 340If disabled, no relocation will occur. 341Default: enabled. 342.It Cm limit-dirs 343If enabled, libarchive will cause an error if there are more than 34465536 directories. 345If disabled, there is no limit on the number of directories. 346Default: enabled 347.It Cm pad 348If enabled, 300 kiB of zero bytes will be appended to the end of the archive. 349Default: enabled 350.It Cm relaxed-filenames 351If enabled, all 7-bit ASCII characters are permitted in filenames 352(except lowercase characters unless 353.Cm allow-lowercase 354is also specified). 355This violates ISO9660 standards. 356This does not impact names stored in the Rockridge or Joliet extension area. 357Default: disabled. 358.It Cm rockridge 359The Rockridge extensions store an additional set of POSIX-style file 360information with each file, including mtime, atime, ctime, permissions, 361and long filenames with arbitrary 8-bit characters. 362These extensions also support symbolic links and other POSIX file types. 363Default: enabled. 364.El 365.It Format iso9660 - zisofs support 366The zisofs extensions permit each file to be independently compressed 367using a gzip-compatible compression. 368This can provide significant size savings, but requires the reading 369system to have support for these extensions. 370These extensions are disabled by default. 371.Bl -tag -compact -width indent 372.It Cm compression-level Ns = Ns number 373The compression level used by the deflate compressor. 374Ranges from 0 (least effort) to 9 (most effort). 375Default: 6 376.It Cm zisofs 377Synonym for 378.Cm zisofs=direct . 379.It Cm zisofs=direct 380Compress each file in the archive. 381Unlike 382.Cm zisofs=indirect , 383this is handled entirely within libarchive and does not require a 384separate utility. 385For best results, libarchive tests each file and will store 386the file uncompressed if the compression does not actually save any space. 387In particular, files under 2k will never be compressed. 388Note that boot image files are never compressed. 389.It Cm zisofs=indirect 390Recognizes files that have already been compressed with the 391.Cm mkzftree 392utility and sets up the necessary file metadata so that 393readers will correctly identify these as zisofs-compressed files. 394.It Cm zisofs-exclude Ns = Ns Ar filename 395Specifies a filename that should not be compressed when using 396.Cm zisofs=direct . 397This option can be provided multiple times to suppress compression 398on many files. 399.El 400.El 401.Sh EXAMPLES 402The following example creates an archive write handle to 403create a gzip-compressed ISO9660 format image. 404The two options here specify that the ISO9660 archive will use 405.Ar kernel.img 406as the boot image for El Torito booting, and that the gzip 407compressor should use the maximum compression level. 408.Bd -literal -offset indent 409a = archive_write_new(); 410archive_write_add_filter_gzip(a); 411archive_write_set_format_iso9660(a); 412archive_write_set_options(a, "boot=kernel.img,compression=9"); 413archive_write_open_filename(a, filename, blocksize); 414.Ed 415.\" 416.Sh ERRORS 417Detailed error codes and textual descriptions are available from the 418.Fn archive_errno 419and 420.Fn archive_error_string 421functions. 422.\" 423.Sh SEE ALSO 424.Xr tar 1 , 425.Xr libarchive 3 , 426.Xr archive_read_set_options 3 , 427.Xr archive_write 3 428.Sh HISTORY 429The 430.Nm libarchive 431library first appeared in 432.Fx 5.3 . 433.Sh AUTHORS 434.An -nosplit 435The options support for libarchive was originally implemented by 436.An Michihiro NAKAJIMA . 437.Sh BUGS 438