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