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 January 31, 2020 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 the 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, the 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 b64encode 174.Bl -tag -compact -width indent 175.It Cm mode 176The value is interpreted as octal digits specifying the file mode. 177.It Cm name 178The value specifies the file name. 179.El 180.It Filter bzip2 181.Bl -tag -compact -width indent 182.It Cm compression-level 183The value is interpreted as a decimal integer specifying the 184bzip2 compression level. Supported values are from 1 to 9. 185.El 186.It Filter gzip 187.Bl -tag -compact -width indent 188.It Cm compression-level 189The value is interpreted as a decimal integer specifying the 190gzip compression level. Supported values are from 0 to 9. 191.It Cm timestamp 192Store timestamp. This is enabled by default. 193.El 194.It Filter lrzip 195.Bl -tag -compact -width indent 196.It Cm compression Ns = Ns Ar type 197Use 198.Ar type 199as compression method. 200Supported values are 201.Dq bzip2 , 202.Dq gzipi , 203.Dq lzo 204.Pq ultra fast , 205and 206.Dq zpaq 207.Pq best, extremely slow . 208.It Cm compression-level 209The value is interpreted as a decimal integer specifying the 210lrzip compression level. Supported values are from 1 to 9. 211.El 212.It Filter lz4 213.Bl -tag -compact -width indent 214.It Cm compression-level 215The value is interpreted as a decimal integer specifying the 216lz4 compression level. Supported values are from 0 to 9. 217.It Cm stream-checksum 218Enable stream checksum. This is enabled by default. 219.It Cm block-checksum 220Enable block checksum. This is disabled by default. 221.It Cm block-size 222The value is interpreted as a decimal integer specifying the 223lz4 compression block size. Supported values are from 4 to 7 224.Pq default . 225.It Cm block-dependence 226Use the previous block of the block being compressed for 227a compression dictionary to improve compression ratio. 228This is disabled by default. 229.El 230.It Filter lzop 231.Bl -tag -compact -width indent 232.It Cm compression-level 233The value is interpreted as a decimal integer specifying the 234lzop compression level. Supported values are from 1 to 9. 235.El 236.It Filter uuencode 237.Bl -tag -compact -width indent 238.It Cm mode 239The value is interpreted as octal digits specifying the file mode. 240.It Cm name 241The value specifies the file name. 242.El 243.It Filter xz 244.Bl -tag -compact -width indent 245.It Cm compression-level 246The value is interpreted as a decimal integer specifying the 247compression level. Supported values are from 0 to 9. 248.It Cm threads 249The value is interpreted as a decimal integer specifying the 250number of threads for multi-threaded lzma compression. 251If supported, the default value is read from 252.Fn lzma_cputhreads . 253.El 254.It Filter zstd 255.Bl -tag -compact -width indent 256.It Cm compression-level 257The value is interpreted as a decimal integer specifying the 258compression level. Supported values depend on the library version, 259common values are from 1 to 22. 260.El 261.It Format 7zip 262.Bl -tag -compact -width indent 263.It Cm compression 264The value is one of 265.Dq store , 266.Dq deflate , 267.Dq bzip2 , 268.Dq lzma1 , 269.Dq lzma2 270or 271.Dq ppmd 272to indicate how the following entries should be compressed. 273Note that this setting is ignored for directories, symbolic links, 274and other special entries. 275.It Cm compression-level 276The value is interpreted as a decimal integer specifying the 277compression level. 278Values between 0 and 9 are supported. 279The interpretation of the compression level depends on the chosen 280compression method. 281.El 282.It Format bin 283.Bl -tag -compact -width indent 284.It Cm hdrcharset 285The value is used as a character set name that will be 286used when translating file names. 287.El 288.It Format gnutar 289.Bl -tag -compact -width indent 290.It Cm hdrcharset 291The value is used as a character set name that will be 292used when translating file, group and user names. 293.El 294.It Format iso9660 - volume metadata 295These options are used to set standard ISO9660 metadata. 296.Bl -tag -compact -width indent 297.It Cm abstract-file Ns = Ns Ar filename 298The file with the specified name will be identified in the ISO9660 metadata 299as holding the abstract for this volume. 300Default: none. 301.It Cm application-id Ns = Ns Ar filename 302The file with the specified name will be identified in the ISO9660 metadata 303as holding the application identifier for this volume. 304Default: none. 305.It Cm biblio-file Ns = Ns Ar filename 306The file with the specified name will be identified in the ISO9660 metadata 307as holding the bibliography for this volume. 308Default: none. 309.It Cm copyright-file Ns = Ns Ar filename 310The file with the specified name will be identified in the ISO9660 metadata 311as holding the copyright for this volume. 312Default: none. 313.It Cm publisher Ns = Ns Ar filename 314The file with the specified name will be identified in the ISO9660 metadata 315as holding the publisher information for this volume. 316Default: none. 317.It Cm volume-id Ns = Ns Ar string 318The specified string will be used as the Volume Identifier in the ISO9660 metadata. 319It is limited to 32 bytes. 320Default: none. 321.El 322.It Format iso9660 - boot support 323These options are used to make an ISO9660 image that can be directly 324booted on various systems. 325.Bl -tag -compact -width indent 326.It Cm boot Ns = Ns Ar filename 327The file matching this name will be used as the El Torito boot image file. 328.It Cm boot-catalog Ns = Ns Ar name 329The name that will be used for the El Torito boot catalog. 330Default: 331.Ar boot.catalog 332.It Cm boot-info-table 333The boot image file provided by the 334.Cm boot Ns = Ns Ar filename 335option will be edited with appropriate boot information in bytes 8 through 64. 336Default: disabled 337.It Cm boot-load-seg Ns = Ns Ar hexadecimal-number 338The load segment for a no-emulation boot image. 339.It Cm boot-load-size Ns = Ns Ar decimal-number 340The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image. 341Some very old BIOSes can only load very small images, setting this 342value to 4 will often allow such BIOSes to load the first part of 343the boot image (which will then need to be intelligent enough to 344load the rest of itself). 345This should not be needed unless you are trying to support systems with very old BIOSes. 346This defaults to the full size of the image. 347.It Cm boot-type Ns = Ns Ar value 348Specifies the boot semantics used by the El Torito boot image: 349If the 350.Ar value 351is 352.Cm fd , 353then the boot image is assumed to be a bootable floppy image. 354If the 355.Ar value 356is 357.Cm hd , 358then the boot image is assumed to be a bootable hard disk image. 359If the 360.Ar value 361is 362.Cm no-emulation , 363the boot image is used without floppy or hard disk emulation. 364If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then 365the default is 366.Cm fd , 367otherwise the default is 368.Cm no-emulation . 369.El 370.It Format iso9660 - filename and size extensions 371Various extensions to the base ISO9660 format. 372.Bl -tag -compact -width indent 373.It Cm allow-ldots 374If enabled, allows filenames to begin with a leading period. 375If disabled, filenames that begin with a leading period will have 376that period replaced by an underscore character in the standard ISO9660 377namespace. 378This does not impact names stored in the Rockridge or Joliet extension area. 379Default: disabled. 380.It Cm allow-lowercase 381If enabled, allows filenames to contain lowercase characters. 382If disabled, filenames will be forced to uppercase. 383This does not impact names stored in the Rockridge or Joliet extension area. 384Default: disabled. 385.It Cm allow-multidot 386If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification. 387If disabled, additional periods will be converted to underscore characters. 388This does not impact names stored in the Rockridge or Joliet extension area. 389Default: disabled. 390.It Cm allow-period 391If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification. 392If disabled, trailing periods will be converted to underscore characters. 393This does not impact names stored in the Rockridge or Joliet extension area. 394Default: disabled. 395.It Cm allow-pvd-lowercase 396If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification. 397If disabled, characters will be converted to uppercase ASCII. 398Default: disabled. 399.It Cm allow-sharp-tilde 400If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification. 401If disabled, such characters will be converted to underscore characters. 402Default: disabled. 403.It Cm allow-vernum 404If enabled, version numbers will be included with files. 405If disabled, version numbers will be suppressed, in violation of the ISO9660 standard. 406This does not impact names stored in the Rockridge or Joliet extension area. 407Default: enabled. 408.It Cm iso-level 409This enables support for file size and file name extensions in the 410core ISO9660 area. 411The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas. 412.Bl -tag -compact -width indent 413.It Cm iso-level=1 414The most compliant form of ISO9660 image. 415Filenames are limited to 8.3 uppercase format, 416directory names are limited to 8 uppercase characters, 417files are limited to 4 GiB, 418the complete ISO9660 image cannot exceed 4 GiB. 419.It Cm iso-level=2 420Filenames are limited to 30 uppercase characters with a 30-character extension, 421directory names are limited to 30 characters, 422files are limited to 4 GiB. 423.It Cm iso-level=3 424As with 425.Cm iso-level=2 , 426except that files may exceed 4 GiB. 427.It Cm iso-level=4 428As with 429.Cm iso-level=3 , 430except that filenames may be up to 193 characters 431and may include arbitrary 8-bit characters. 432.El 433.It Cm joliet 434Microsoft's Joliet extensions store a completely separate set of directory information about each file. 435In particular, this information includes Unicode filenames of up to 255 characters. 436Default: enabled. 437.It Cm limit-depth 438If enabled, libarchive will use directory relocation records to ensure that 439no pathname exceeds the ISO9660 limit of 8 directory levels. 440If disabled, no relocation will occur. 441Default: enabled. 442.It Cm limit-dirs 443If enabled, libarchive will cause an error if there are more than 44465536 directories. 445If disabled, there is no limit on the number of directories. 446Default: enabled 447.It Cm pad 448If enabled, 300 kiB of zero bytes will be appended to the end of the archive. 449Default: enabled 450.It Cm relaxed-filenames 451If enabled, all 7-bit ASCII characters are permitted in filenames 452(except lowercase characters unless 453.Cm allow-lowercase 454is also specified). 455This violates ISO9660 standards. 456This does not impact names stored in the Rockridge or Joliet extension area. 457Default: disabled. 458.It Cm rockridge 459The Rockridge extensions store an additional set of POSIX-style file 460information with each file, including mtime, atime, ctime, permissions, 461and long filenames with arbitrary 8-bit characters. 462These extensions also support symbolic links and other POSIX file types. 463Default: enabled. 464.El 465.It Format iso9660 - zisofs support 466The zisofs extensions permit each file to be independently compressed 467using a gzip-compatible compression. 468This can provide significant size savings, but requires the reading 469system to have support for these extensions. 470These extensions are disabled by default. 471.Bl -tag -compact -width indent 472.It Cm compression-level Ns = Ns number 473The compression level used by the deflate compressor. 474Ranges from 0 (least effort) to 9 (most effort). 475Default: 6 476.It Cm zisofs 477Synonym for 478.Cm zisofs=direct . 479.It Cm zisofs=direct 480Compress each file in the archive. 481Unlike 482.Cm zisofs=indirect , 483this is handled entirely within libarchive and does not require a 484separate utility. 485For best results, libarchive tests each file and will store 486the file uncompressed if the compression does not actually save any space. 487In particular, files under 2k will never be compressed. 488Note that boot image files are never compressed. 489.It Cm zisofs=indirect 490Recognizes files that have already been compressed with the 491.Cm mkzftree 492utility and sets up the necessary file metadata so that 493readers will correctly identify these as zisofs-compressed files. 494.It Cm zisofs-exclude Ns = Ns Ar filename 495Specifies a filename that should not be compressed when using 496.Cm zisofs=direct . 497This option can be provided multiple times to suppress compression 498on many files. 499.El 500.It Format mtree 501.Bl -tag -compact -width indent 502.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 503Enable a particular keyword in the mtree output. 504Prefix with an exclamation mark to disable the corresponding keyword. 505The default is equivalent to 506.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . 507.It Cm all 508Enables all of the above keywords. 509.It Cm use-set 510Enables generation of 511.Cm /set 512lines that specify default values for the following files and/or directories. 513.It Cm indent 514XXX needs explanation XXX 515.El 516.It Format newc 517.Bl -tag -compact -width indent 518.It Cm hdrcharset 519The value is used as a character set name that will be 520used when translating file names. 521.El 522.It Format odc 523.Bl -tag -compact -width indent 524.It Cm hdrcharset 525The value is used as a character set name that will be 526used when translating file names. 527.El 528.It Format pwb 529.Bl -tag -compact -width indent 530.It Cm hdrcharset 531The value is used as a character set name that will be 532used when translating file names. 533.El 534.It Format pax 535.Bl -tag -compact -width indent 536.It Cm hdrcharset 537The value is used as a character set name that will be 538used when translating file, group and user names. 539The value is one of 540.Dq BINARY 541or 542.Dq UTF-8 . 543With 544.Dq BINARY 545there is no character conversion, with 546.Dq UTF-8 547names are converted to UTF-8. 548.It Cm xattrheader 549When storing extended attributes, this option configures which 550headers should be written. The value is one of 551.Dq all , 552.Dq LIBARCHIVE , 553or 554.Dq SCHILY . 555By default, both 556.Dq LIBARCHIVE.xattr 557and 558.Dq SCHILY.xattr 559headers are written. 560.El 561.It Format ustar 562.Bl -tag -compact -width indent 563.It Cm hdrcharset 564The value is used as a character set name that will be 565used when translating file, group and user names. 566.El 567.It Format v7tar 568.Bl -tag -compact -width indent 569.It Cm hdrcharset 570The value is used as a character set name that will be 571used when translating file, group and user names. 572.El 573.It Format warc 574.Bl -tag -compact -width indent 575.It Cm omit-warcinfo 576Set to 577.Dq true 578to disable output of the warcinfo record. 579.El 580.It Format xar 581.Bl -tag -compact -width indent 582.It Cm checksum Ns = Ns Ar type 583Use 584.Ar type 585as file checksum method. 586Supported values are 587.Dq none , 588.Dq md5 , 589and 590.Dq sha1 591.Pq default . 592.It Cm compression Ns = Ns Ar type 593Use 594.Ar type 595as compression method. 596Supported values are 597.Dq none , 598.Dq bzip2 , 599.Dq gzip 600.Pq default , 601.Dq lzma 602and 603.Dq xz . 604.It Cm compression_level 605The value is a decimal integer from 1 to 9 specifying the compression level. 606.It Cm toc-checksum Ns = Ns Ar type 607Use 608.Ar type 609as table of contents checksum method. 610Supported values are 611.Dq none , 612.Dq md5 613and 614.Dq sha1 615.Pq default . 616.El 617.It Format zip 618.Bl -tag -compact -width indent 619.It Cm compression 620The value is either 621.Dq store 622or 623.Dq deflate 624to indicate how the following entries should be compressed. 625Note that this setting is ignored for directories, symbolic links, 626and other special entries. 627.It Cm compression-level 628The value is interpreted as a decimal integer specifying the 629compression level. 630Values between 0 and 9 are supported. 631A compression level of 0 switches the compression method to 632.Dq store , 633other values will enable 634.Dq deflate 635compression with the given level. 636.It Cm encryption 637Enable encryption using traditional zip encryption. 638.It Cm encryption Ns = Ns Ar type 639Use 640.Ar type 641as encryption type. 642Supported values are 643.Dq zipcrypt 644.Pq traditional zip encryption , 645.Dq aes128 646.Pq WinZip AES-128 encryption 647and 648.Dq aes256 649.Pq WinZip AES-256 encryption . 650.It Cm experimental 651This boolean option enables or disables experimental Zip features 652that may not be compatible with other Zip implementations. 653.It Cm fakecrc32 654This boolean option disables CRC calculations. 655All CRC fields are set to zero. 656It should not be used except for testing purposes. 657.It Cm hdrcharset 658The value is used as a character set name that will be 659used when translating file names. 660.It Cm zip64 661Zip64 extensions provide additional file size information 662for entries larger than 4 GiB. 663They also provide extended file offset and archive size information 664when archives exceed 4 GiB. 665By default, the Zip writer selectively enables these extensions only as needed. 666In particular, if the file size is unknown, the Zip writer will 667include Zip64 extensions to guard against the possibility that the 668file might be larger than 4 GiB. 669.Pp 670Setting this boolean option will force the writer to use Zip64 extensions 671even for small files that would not otherwise require them. 672This is primarily useful for testing. 673.Pp 674Disabling this option with 675.Cm !zip64 676will force the Zip writer to avoid Zip64 extensions: 677It will reject files with size greater than 4 GiB, 678it will reject any new entries once the total archive size reaches 4 GiB, 679and it will not use Zip64 extensions for files with unknown size. 680In particular, this can improve compatibility when generating archives 681where the entry sizes are not known in advance. 682.El 683.El 684.Sh EXAMPLES 685The following example creates an archive write handle to 686create a gzip-compressed ISO9660 format image. 687The two options here specify that the ISO9660 archive will use 688.Ar kernel.img 689as the boot image for El Torito booting, and that the gzip 690compressor should use the maximum compression level. 691.Bd -literal -offset indent 692a = archive_write_new(); 693archive_write_add_filter_gzip(a); 694archive_write_set_format_iso9660(a); 695archive_write_set_options(a, "boot=kernel.img,compression=9"); 696archive_write_open_filename(a, filename, blocksize); 697.Ed 698.\" 699.Sh ERRORS 700More detailed error codes and textual descriptions are available from the 701.Fn archive_errno 702and 703.Fn archive_error_string 704functions. 705.\" 706.Sh SEE ALSO 707.Xr tar 1 , 708.Xr archive_read_set_options 3 , 709.Xr archive_write 3 , 710.Xr libarchive 3 711.Sh HISTORY 712The 713.Nm libarchive 714library first appeared in 715.Fx 5.3 . 716.Sh AUTHORS 717.An -nosplit 718The options support for libarchive was originally implemented by 719.An Michihiro NAKAJIMA . 720.Sh BUGS 721