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