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