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 cpio 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 pax 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, group and user names. 527The value is one of 528.Dq BINARY 529or 530.Dq UTF-8 . 531With 532.Dq BINARY 533there is no character conversion, with 534.Dq UTF-8 535names are converted to UTF-8. 536.It Cm xattrheader 537When storing extended attributes, this option configures which 538headers should be written. The value is one of 539.Dq all , 540.Dq LIBARCHIVE , 541or 542.Dq SCHILY . 543By default, both 544.Dq LIBARCHIVE.xattr 545and 546.Dq SCHILY.xattr 547headers are written. 548.El 549.It Format ustar 550.Bl -tag -compact -width indent 551.It Cm hdrcharset 552The value is used as a character set name that will be 553used when translating file, group and user names. 554.El 555.It Format v7tar 556.Bl -tag -compact -width indent 557.It Cm hdrcharset 558The value is used as a character set name that will be 559used when translating file, group and user names. 560.El 561.It Format warc 562.Bl -tag -compact -width indent 563.It Cm omit-warcinfo 564Set to 565.Dq true 566to disable output of the warcinfo record. 567.El 568.It Format xar 569.Bl -tag -compact -width indent 570.It Cm checksum Ns = Ns Ar type 571Use 572.Ar type 573as file checksum method. 574Supported values are 575.Dq none , 576.Dq md5 , 577and 578.Dq sha1 579.Pq default . 580.It Cm compression Ns = Ns Ar type 581Use 582.Ar type 583as compression method. 584Supported values are 585.Dq none , 586.Dq bzip2 , 587.Dq gzip 588.Pq default , 589.Dq lzma 590and 591.Dq xz . 592.It Cm compression_level 593The value is a decimal integer from 1 to 9 specifying the compression level. 594.It Cm toc-checksum Ns = Ns Ar type 595Use 596.Ar type 597as table of contents checksum method. 598Supported values are 599.Dq none , 600.Dq md5 601and 602.Dq sha1 603.Pq default . 604.El 605.It Format zip 606.Bl -tag -compact -width indent 607.It Cm compression 608The value is either 609.Dq store 610or 611.Dq deflate 612to indicate how the following entries should be compressed. 613Note that this setting is ignored for directories, symbolic links, 614and other special entries. 615.It Cm compression-level 616The value is interpreted as a decimal integer specifying the 617compression level. 618Values between 0 and 9 are supported. 619A compression level of 0 switches the compression method to 620.Dq store , 621other values will enable 622.Dq deflate 623compression with the given level. 624.It Cm encryption 625Enable encryption using traditional zip encryption. 626.It Cm encryption Ns = Ns Ar type 627Use 628.Ar type 629as encryption type. 630Supported values are 631.Dq zipcrypt 632.Pq traditional zip encryption , 633.Dq aes128 634.Pq WinZip AES-128 encryption 635and 636.Dq aes256 637.Pq WinZip AES-256 encryption . 638.It Cm experimental 639This boolean option enables or disables experimental Zip features 640that may not be compatible with other Zip implementations. 641.It Cm fakecrc32 642This boolean option disables CRC calculations. 643All CRC fields are set to zero. 644It should not be used except for testing purposes. 645.It Cm hdrcharset 646The value is used as a character set name that will be 647used when translating file names. 648.It Cm zip64 649Zip64 extensions provide additional file size information 650for entries larger than 4 GiB. 651They also provide extended file offset and archive size information 652when archives exceed 4 GiB. 653By default, the Zip writer selectively enables these extensions only as needed. 654In particular, if the file size is unknown, the Zip writer will 655include Zip64 extensions to guard against the possibility that the 656file might be larger than 4 GiB. 657.Pp 658Setting this boolean option will force the writer to use Zip64 extensions 659even for small files that would not otherwise require them. 660This is primarily useful for testing. 661.Pp 662Disabling this option with 663.Cm !zip64 664will force the Zip writer to avoid Zip64 extensions: 665It will reject files with size greater than 4 GiB, 666it will reject any new entries once the total archive size reaches 4 GiB, 667and it will not use Zip64 extensions for files with unknown size. 668In particular, this can improve compatibility when generating archives 669where the entry sizes are not known in advance. 670.El 671.El 672.Sh EXAMPLES 673The following example creates an archive write handle to 674create a gzip-compressed ISO9660 format image. 675The two options here specify that the ISO9660 archive will use 676.Ar kernel.img 677as the boot image for El Torito booting, and that the gzip 678compressor should use the maximum compression level. 679.Bd -literal -offset indent 680a = archive_write_new(); 681archive_write_add_filter_gzip(a); 682archive_write_set_format_iso9660(a); 683archive_write_set_options(a, "boot=kernel.img,compression=9"); 684archive_write_open_filename(a, filename, blocksize); 685.Ed 686.\" 687.Sh ERRORS 688More detailed error codes and textual descriptions are available from the 689.Fn archive_errno 690and 691.Fn archive_error_string 692functions. 693.\" 694.Sh SEE ALSO 695.Xr tar 1 , 696.Xr archive_read_set_options 3 , 697.Xr archive_write 3 , 698.Xr libarchive 3 699.Sh HISTORY 700The 701.Nm libarchive 702library first appeared in 703.Fx 5.3 . 704.Sh AUTHORS 705.An -nosplit 706The options support for libarchive was originally implemented by 707.An Michihiro NAKAJIMA . 708.Sh BUGS 709