doc/man/archive_write_set_options.3

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