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 writing 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 either 105.Cm ARCHIVE_OK 106if the option was successfully handled or 107.Cm ARCHIVE_WARN 108if the option was unrecognized by the module or could otherwise 109not be handled. 110If there is no such module, 111.Cm ARCHIVE_FAILED 112will be returned. 113.Pp 114If 115.Ar module 116is 117.Dv NULL , 118.Ar option 119and 120.Ar value 121will be provided to every registered module. 122If any module returns 123.Cm ARCHIVE_FATAL , 124this value will be returned immediately. 125Otherwise, 126.Cm ARCHIVE_OK 127will be returned if any module accepts the option, and 128.Cm ARCHIVE_FAILED 129in all other cases. 130.\" 131.It Fn archive_write_set_option 132Calls 133.Fn archive_write_set_format_option , 134then 135.Fn archive_write_set_filter_option . 136If either function returns 137.Cm ARCHIVE_FATAL , 138.Cm ARCHIVE_FATAL 139will be returned 140immediately. 141Otherwise, greater of the two values will be returned. 142.\" 143.It Fn archive_write_set_options 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 154Individual options have one of the following forms: 155.Bl -tag -compact -width indent 156.It Ar option=value 157The option/value pair will be provided to every module. 158Modules that do not accept an option with this name will ignore it. 159.It Ar option 160The option will be provided to every module with a value of 161.Dq 1 . 162.It Ar !option 163The option will be provided to every module with a NULL value. 164.It Ar module:option=value , Ar module:option , Ar module:!option 165As above, but the corresponding option and value will be provided 166only to modules whose name matches 167.Ar module . 168.El 169.El 170.\" 171.Sh OPTIONS 172.Bl -tag -compact -width indent 173.It Filter gzip 174.Bl -tag -compact -width indent 175.It Cm compression-level 176The value is interpreted as a decimal integer specifying the 177gzip compression level. 178.El 179.It Filter xz 180.Bl -tag -compact -width indent 181.It Cm compression-level 182The value is interpreted as a decimal integer specifying the 183compression level. 184.El 185.It Format mtree 186.Bl -tag -compact -width indent 187.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 188Enable a particular keyword in the mtree output. 189Prefix with an exclamation mark to disable the corresponding keyword. 190The default is equivalent to 191.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . 192.It Cm all 193Enables all of the above keywords. 194.It Cm use-set 195Enables generation of 196.Cm /set 197lines that specify default values for the following files and/or directories. 198.It Cm indent 199XXX needs explanation XXX 200.El 201.It Format iso9660 - volume metadata 202These options are used to set standard ISO9660 metadata. 203.Bl -tag -compact -width indent 204.It Cm abstract-file Ns = Ns Ar filename 205The file with the specified name will be identified in the ISO9660 metadata 206as holding the abstract for this volume. Default: none. 207.It Cm application-id Ns = Ns Ar filename 208The file with the specified name will be identified in the ISO9660 metadata 209as holding the application identifier for this volume. Default: none. 210.It Cm biblio-file Ns = Ns Ar filename 211The file with the specified name will be identified in the ISO9660 metadata 212as holding the bibliography for this volume. Default: none. 213.It Cm copyright-file Ns = Ns Ar filename 214The file with the specified name will be identified in the ISO9660 metadata 215as holding the copyright for this volume. Default: none. 216.It Cm publisher Ns = Ns Ar filename 217The file with the specified name will be identified in the ISO9660 metadata 218as holding the publisher information for this volume. Default: none. 219.It Cm volume-id Ns = Ns Ar string 220The specified string will be used as the Volume Identifier in the ISO9660 metadata. 221It is limited to 32 bytes. Default: none. 222.El 223.It Format iso9660 - boot support 224These options are used to make an ISO9660 image that can be directly 225booted on various systems. 226.Bl -tag -compact -width indent 227.It Cm boot Ns = Ns Ar filename 228The file matching this name will be used as the El Torito boot image file. 229.It Cm boot-catalog Ns = Ns Ar name 230The name that will be used for the El Torito boot catalog. 231Default: 232.Ar boot.catalog 233.It Cm boot-info-table 234The boot image file provided by the 235.Cm boot Ns = Ns Ar filename 236option will be edited with appropriate boot information in bytes 8 through 64. 237Default: disabled 238.It Cm boot-load-seg Ns = Ns Ar hexadecimal-number 239The load segment for a no-emulation boot image. 240.It Cm boot-load-size Ns = Ns Ar decimal-number 241The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image. 242Some very old BIOSes can only load very small images, setting this 243value to 4 will often allow such BIOSes to load the first part of 244the boot image (which will then need to be intelligent enough to 245load the rest of itself). 246This should not be needed unless you are trying to support systems with very old BIOSes. 247This defaults to the full size of the image. 248.It Cm boot-type Ns = Ns Ar value 249Specifies the boot semantics used by the El Torito boot image: 250If the 251.Ar value 252is 253.Cm fd , 254then the boot image is assumed to be a bootable floppy image. 255If the 256.Ar value 257is 258.Cm hd , 259then the boot image is assumed to be a bootable hard disk image. 260If the 261.Ar value 262is 263.Cm no-emulation , 264the boot image is used without floppy or hard disk emulation. 265If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then 266the default is 267.Cm fd , 268otherwise the default is 269.Cm no-emulation. 270.El 271.It Format iso9660 - filename and size extensions 272Various extensions to the base ISO9660 format. 273.Bl -tag -compact -width indent 274.It Cm allow-ldots 275If enabled, allows filenames to begin with a leading period. 276If disabled, filenames that begin with a leading period will have 277that period replaced by an underscore character in the standard ISO9660 278namespace. 279This does not impact names stored in the Rockridge or Joliet extension area. 280Default: disabled. 281.It Cm allow-lowercase 282If enabled, allows filenames to contain lowercase characters. 283If disabled, filenames will be forced to uppercase. 284This does not impact names stored in the Rockridge or Joliet extension area. 285Default: disabled. 286.It Cm allow-multidot 287If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification. 288If disabled, additional periods will be converted to underscore characters. 289This does not impact names stored in the Rockridge or Joliet extension area. 290Default: disabled. 291.It Cm allow-period 292If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification. 293If disabled,trailing periods will be converted to underscore characters. 294This does not impact names stored in the Rockridge or Joliet extension area. 295Default: disabled. 296.It Cm allow-pvd-lowercase 297If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification. 298If disabled, characters will be converted to uppercase ASCII. 299Default: disabled. 300.It Cm allow-sharp-tilde 301If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification. 302If disabled, such characters will be converted to underscore characters. 303Default: disabled. 304.It Cm allow-vernum 305If enabled, version numbers will be included with files. 306If disabled, version numbers will be suppressed, in violation of the ISO9660 standard. 307This does not impact names stored in the Rockridge or Joliet extension area. 308Default: enabled. 309.It Cm iso-level 310This enables support for file size and file name extensions in the 311core ISO9660 area. 312The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas. 313.Bl -tag -compact -width indent 314.It Cm iso-level=1 315The most compliant form of ISO9660 image. 316Filenames are limited to 8.3 uppercase format, 317directory names are limited to 8 uppercase characters, 318files are limited to 4 GiB, 319the complete ISO9660 image cannot exceed 4 GiB. 320.It Cm iso-level=2 321Filenames are limited to 30 uppercase characters with a 30-character extension, 322directory names are limited to 30 characters, 323files are limited to 4 GiB. 324.It Cm iso-level=3 325As with 326.Cm iso-level=2 , 327except that files may exceed 4 GiB. 328.It Cm iso-level=4 329As with 330.Cm iso-level=3 , 331except that filenames may be up to 193 characters 332and may include arbitrary 8-bit characters. 333.El 334.It Cm joliet 335Microsoft's Joliet extensions store a completely separate set of directory information about each file. 336In particular, this information includes Unicode filenames of up to 255 characters. 337Default: enabled. 338.It Cm limit-depth 339If enabled, libarchive will use directory relocation records to ensure that 340no pathname exceeds the ISO9660 limit of 8 directory levels. 341If disabled, no relocation will occur. 342Default: enabled. 343.It Cm limit-dirs 344If enabled, libarchive will cause an error if there are more than 34565536 directories. 346If disabled, there is no limit on the number of directories. 347Default: enabled 348.It Cm pad 349If enabled, 300 kiB of zero bytes will be appended to the end of the archive. 350Default: enabled 351.It Cm relaxed-filenames 352If enabled, all 7-bit ASCII characters are permitted in filenames 353(except lowercase characters unless 354.Cm allow-lowercase 355is also specified). 356This violates ISO9660 standards. 357This does not impact names stored in the Rockridge or Joliet extension area. 358Default: disabled. 359.It Cm rockridge 360The Rockridge extensions store an additional set of POSIX-style file 361information with each file, including mtime, atime, ctime, permissions, 362and long filenames with arbitrary 8-bit characters. 363These extensions also support symbolic links and other POSIX file types. 364Default: enabled. 365.El 366.It Format iso9660 - zisofs support 367The zisofs extensions permit each file to be independently compressed 368using a gzip-compatible compression. 369This can provide significant size savings, but requires the reading 370system to have support for these extensions. 371These extensions are disabled by default. 372.Bl -tag -compact -width indent 373.It Cm compression-level Ns = Ns number 374The compression level used by the deflate compressor. 375Ranges from 0 (least effort) to 9 (most effort). 376Default: 6 377.It Cm zisofs 378Synonym for 379.Cm zisofs=direct . 380.It Cm zisofs=direct 381Compress each file in the archive. 382Unlike 383.Cm zisofs=indirect , 384this is handled entirely within libarchive and does not require a 385separate utility. 386For best results, libarchive tests each file and will store 387the file uncompressed if the compression does not actually save any space. 388In particular, files under 2k will never be compressed. 389Note that boot image files are never compressed. 390.It Cm zisofs=indirect 391Recognizes files that have already been compressed with the 392.Cm mkzftree 393utility and sets up the necessary file metadata so that 394readers will correctly identify these as zisofs-compressed files. 395.It Cm zisofs-exclude Ns = Ns Ar filename 396Specifies a filename that should not be compressed when using 397.Cm zisofs=direct . 398This option can be provided multiple times to suppress compression 399on many files. 400.El 401.It Format zip 402.Bl -tag -compact -width indent 403.It Cm compression 404The value is either 405.Dq store 406or 407.Dq deflate 408to indicate how the following entries should be compressed. 409Note that this setting is ignored for directories, symbolic links, 410and other special entries. 411.It Cm experimental 412This boolean option enables or disables experimental Zip features 413that may not be compatible with other Zip implementations. 414.It Cm fakecrc32 415This boolean option disables CRC calculations. 416All CRC fields are set to zero. 417It should not be used except for testing purposes. 418.It Cm hdrcharset 419This sets the character set used for filenames. 420.It Cm zip64 421Zip64 extensions provide additional file size information 422for entries larger than 4 GiB. 423They also provide extended file offset and archive size information 424when archives exceed 4 GiB. 425By default, the Zip writer selectively enables these extensions only as needed. 426In particular, if the file size is unknown, the Zip writer will 427include Zip64 extensions to guard against the possibility that the 428file might be larger than 4 GiB. 429.Pp 430Setting this boolean option will force the writer to use Zip64 extensions 431even for small files that would not otherwise require them. 432This is primarily useful for testing. 433.Pp 434Disabling this option with 435.Cm !zip64 436will force the Zip writer to avoid Zip64 extensions: 437It will reject files with size greater than 4 GiB, 438it will reject any new entries once the total archive size reaches 4 GiB, 439and it will not use Zip64 extensions for files with unknown size. 440In particular, this can improve compatibility when generating archives 441where the entry sizes are not known in advance. 442.El 443.El 444.Sh EXAMPLES 445The following example creates an archive write handle to 446create a gzip-compressed ISO9660 format image. 447The two options here specify that the ISO9660 archive will use 448.Ar kernel.img 449as the boot image for El Torito booting, and that the gzip 450compressor should use the maximum compression level. 451.Bd -literal -offset indent 452a = archive_write_new(); 453archive_write_add_filter_gzip(a); 454archive_write_set_format_iso9660(a); 455archive_write_set_options(a, "boot=kernel.img,compression=9"); 456archive_write_open_filename(a, filename, blocksize); 457.Ed 458.\" 459.Sh ERRORS 460More detailed error codes and textual descriptions are available from the 461.Fn archive_errno 462and 463.Fn archive_error_string 464functions. 465.\" 466.Sh SEE ALSO 467.Xr tar 1 , 468.Xr libarchive 3 , 469.Xr archive_read_set_options 3 , 470.Xr archive_write 3 471.Sh HISTORY 472The 473.Nm libarchive 474library first appeared in 475.Fx 5.3 . 476.Sh AUTHORS 477.An -nosplit 478The options support for libarchive was originally implemented by 479.An Michihiro NAKAJIMA . 480.Sh BUGS 481