1 .\" Copyright (c) 2003-2010 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
28 .Dt ARCHIVE_WRITE_OPTIONS 3
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
37 Streaming Archive Library (libarchive, -larchive)
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"
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"
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"
62 .Fo archive_write_set_options
63 .Fa "struct archive *"
64 .Fa "const char *options"
67 These functions provide a way for libarchive clients to configure
68 specific write modules.
69 .Bl -tag -width indent
71 .Fn archive_write_set_filter_option ,
72 .Fn archive_write_set_format_option
74 Specifies an option that will be passed to the currently-registered
75 filters (including decompression filters) or format readers.
83 these functions will do nothing and
92 is not, these functions will do nothing and
103 will be provided to the filter or reader named
105 The return value will be either
107 if the option was successfully handled or
109 if the option was unrecognized by the module or could otherwise
111 If there is no such module,
122 will be provided to every registered module.
123 If any module returns
125 this value will be returned immediately.
128 will be returned if any module accepts the option, and
132 .It Fn archive_write_set_option
134 .Fn archive_write_set_format_option ,
136 .Fn archive_write_set_filter_option .
137 If either function returns
142 Otherwise, the greater of the two values will be returned.
144 .It Fn archive_write_set_options
146 is a comma-separated list of options.
153 will be returned immediately.
155 Individual options have one of the following forms:
156 .Bl -tag -compact -width indent
158 The option/value pair will be provided to every module.
159 Modules that do not accept an option with this name will ignore it.
161 The option will be provided to every module with a value of
164 The option will be provided to every module with a NULL value.
165 .It Ar module:option=value , Ar module:option , Ar module:!option
166 As above, but the corresponding option and value will be provided
167 only to modules whose name matches
173 .Bl -tag -compact -width indent
175 .Bl -tag -compact -width indent
177 The value is interpreted as octal digits specifying the file mode.
179 The value specifies the file name.
182 .Bl -tag -compact -width indent
183 .It Cm compression-level
184 The value is interpreted as a decimal integer specifying the
185 bzip2 compression level. Supported values are from 1 to 9.
188 .Bl -tag -compact -width indent
189 .It Cm compression-level
190 The value is interpreted as a decimal integer specifying the
191 gzip compression level. Supported values are from 0 to 9.
193 Store timestamp. This is enabled by default.
196 .Bl -tag -compact -width indent
197 .It Cm compression Ns = Ns Ar type
200 as compression method.
208 .Pq best, extremely slow .
209 .It Cm compression-level
210 The value is interpreted as a decimal integer specifying the
211 lrzip compression level. Supported values are from 1 to 9.
214 .Bl -tag -compact -width indent
215 .It Cm compression-level
216 The value is interpreted as a decimal integer specifying the
217 lz4 compression level. Supported values are from 0 to 9.
218 .It Cm stream-checksum
219 Enable stream checksum. This is enabled by default.
220 .It Cm block-checksum
221 Enable block checksum. This is disabled by default.
223 The value is interpreted as a decimal integer specifying the
224 lz4 compression block size. Supported values are from 4 to 7
226 .It Cm block-dependence
227 Use the previous block of the block being compressed for
228 a compression dictionary to improve compression ratio.
229 This is disabled by default.
232 .Bl -tag -compact -width indent
233 .It Cm compression-level
234 The value is interpreted as a decimal integer specifying the
235 lzop compression level. Supported values are from 1 to 9.
238 .Bl -tag -compact -width indent
240 The value is interpreted as octal digits specifying the file mode.
242 The value specifies the file name.
245 .Bl -tag -compact -width indent
246 .It Cm compression-level
247 The value is interpreted as a decimal integer specifying the
248 compression level. Supported values are from 0 to 9.
250 The value is interpreted as a decimal integer specifying the
251 number of threads for multi-threaded lzma compression.
252 If supported, the default value is read from
253 .Fn lzma_cputhreads .
256 .Bl -tag -compact -width indent
257 .It Cm compression-level
258 The value is interpreted as a decimal integer specifying the
259 compression level. Supported values depend on the library version,
260 common values are from 1 to 22.
263 .Bl -tag -compact -width indent
273 to indicate how the following entries should be compressed.
274 Note that this setting is ignored for directories, symbolic links,
275 and other special entries.
276 .It Cm compression-level
277 The value is interpreted as a decimal integer specifying the
279 Values between 0 and 9 are supported.
280 The interpretation of the compression level depends on the chosen
284 .Bl -tag -compact -width indent
286 The value is used as a character set name that will be
287 used when translating file names.
290 .Bl -tag -compact -width indent
292 The value is used as a character set name that will be
293 used when translating file, group and user names.
295 .It Format iso9660 - volume metadata
296 These options are used to set standard ISO9660 metadata.
297 .Bl -tag -compact -width indent
298 .It Cm abstract-file Ns = Ns Ar filename
299 The file with the specified name will be identified in the ISO9660 metadata
300 as holding the abstract for this volume.
302 .It Cm application-id Ns = Ns Ar filename
303 The file with the specified name will be identified in the ISO9660 metadata
304 as holding the application identifier for this volume.
306 .It Cm biblio-file Ns = Ns Ar filename
307 The file with the specified name will be identified in the ISO9660 metadata
308 as holding the bibliography for this volume.
310 .It Cm copyright-file Ns = Ns Ar filename
311 The file with the specified name will be identified in the ISO9660 metadata
312 as holding the copyright for this volume.
314 .It Cm publisher Ns = Ns Ar filename
315 The file with the specified name will be identified in the ISO9660 metadata
316 as holding the publisher information for this volume.
318 .It Cm volume-id Ns = Ns Ar string
319 The specified string will be used as the Volume Identifier in the ISO9660 metadata.
320 It is limited to 32 bytes.
323 .It Format iso9660 - boot support
324 These options are used to make an ISO9660 image that can be directly
325 booted on various systems.
326 .Bl -tag -compact -width indent
327 .It Cm boot Ns = Ns Ar filename
328 The file matching this name will be used as the El Torito boot image file.
329 .It Cm boot-catalog Ns = Ns Ar name
330 The name that will be used for the El Torito boot catalog.
333 .It Cm boot-info-table
334 The boot image file provided by the
335 .Cm boot Ns = Ns Ar filename
336 option will be edited with appropriate boot information in bytes 8 through 64.
338 .It Cm boot-load-seg Ns = Ns Ar hexadecimal-number
339 The load segment for a no-emulation boot image.
340 .It Cm boot-load-size Ns = Ns Ar decimal-number
341 The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image.
342 Some very old BIOSes can only load very small images, setting this
343 value to 4 will often allow such BIOSes to load the first part of
344 the boot image (which will then need to be intelligent enough to
345 load the rest of itself).
346 This should not be needed unless you are trying to support systems with very old BIOSes.
347 This defaults to the full size of the image.
348 .It Cm boot-type Ns = Ns Ar value
349 Specifies the boot semantics used by the El Torito boot image:
354 then the boot image is assumed to be a bootable floppy image.
359 then the boot image is assumed to be a bootable hard disk image.
364 the boot image is used without floppy or hard disk emulation.
365 If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then
368 otherwise the default is
371 .It Format iso9660 - filename and size extensions
372 Various extensions to the base ISO9660 format.
373 .Bl -tag -compact -width indent
375 If enabled, allows filenames to begin with a leading period.
376 If disabled, filenames that begin with a leading period will have
377 that period replaced by an underscore character in the standard ISO9660
379 This does not impact names stored in the Rockridge or Joliet extension area.
381 .It Cm allow-lowercase
382 If enabled, allows filenames to contain lowercase characters.
383 If disabled, filenames will be forced to uppercase.
384 This does not impact names stored in the Rockridge or Joliet extension area.
386 .It Cm allow-multidot
387 If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification.
388 If disabled, additional periods will be converted to underscore characters.
389 This does not impact names stored in the Rockridge or Joliet extension area.
392 If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification.
393 If disabled, trailing periods will be converted to underscore characters.
394 This does not impact names stored in the Rockridge or Joliet extension area.
396 .It Cm allow-pvd-lowercase
397 If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification.
398 If disabled, characters will be converted to uppercase ASCII.
400 .It Cm allow-sharp-tilde
401 If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification.
402 If disabled, such characters will be converted to underscore characters.
405 If enabled, version numbers will be included with files.
406 If disabled, version numbers will be suppressed, in violation of the ISO9660 standard.
407 This does not impact names stored in the Rockridge or Joliet extension area.
410 This enables support for file size and file name extensions in the
412 The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas.
413 .Bl -tag -compact -width indent
415 The most compliant form of ISO9660 image.
416 Filenames are limited to 8.3 uppercase format,
417 directory names are limited to 8 uppercase characters,
418 files are limited to 4 GiB,
419 the complete ISO9660 image cannot exceed 4 GiB.
421 Filenames are limited to 30 uppercase characters with a 30-character extension,
422 directory names are limited to 30 characters,
423 files are limited to 4 GiB.
427 except that files may exceed 4 GiB.
431 except that filenames may be up to 193 characters
432 and may include arbitrary 8-bit characters.
435 Microsoft's Joliet extensions store a completely separate set of directory information about each file.
436 In particular, this information includes Unicode filenames of up to 255 characters.
439 If enabled, libarchive will use directory relocation records to ensure that
440 no pathname exceeds the ISO9660 limit of 8 directory levels.
441 If disabled, no relocation will occur.
444 If enabled, libarchive will cause an error if there are more than
446 If disabled, there is no limit on the number of directories.
449 If enabled, 300 kiB of zero bytes will be appended to the end of the archive.
451 .It Cm relaxed-filenames
452 If enabled, all 7-bit ASCII characters are permitted in filenames
453 (except lowercase characters unless
456 This violates ISO9660 standards.
457 This does not impact names stored in the Rockridge or Joliet extension area.
460 The Rockridge extensions store an additional set of POSIX-style file
461 information with each file, including mtime, atime, ctime, permissions,
462 and long filenames with arbitrary 8-bit characters.
463 These extensions also support symbolic links and other POSIX file types.
466 .It Format iso9660 - zisofs support
467 The zisofs extensions permit each file to be independently compressed
468 using a gzip-compatible compression.
469 This can provide significant size savings, but requires the reading
470 system to have support for these extensions.
471 These extensions are disabled by default.
472 .Bl -tag -compact -width indent
473 .It Cm compression-level Ns = Ns number
474 The compression level used by the deflate compressor.
475 Ranges from 0 (least effort) to 9 (most effort).
481 Compress each file in the archive.
483 .Cm zisofs=indirect ,
484 this is handled entirely within libarchive and does not require a
486 For best results, libarchive tests each file and will store
487 the file uncompressed if the compression does not actually save any space.
488 In particular, files under 2k will never be compressed.
489 Note that boot image files are never compressed.
490 .It Cm zisofs=indirect
491 Recognizes files that have already been compressed with the
493 utility and sets up the necessary file metadata so that
494 readers will correctly identify these as zisofs-compressed files.
495 .It Cm zisofs-exclude Ns = Ns Ar filename
496 Specifies a filename that should not be compressed when using
498 This option can be provided multiple times to suppress compression
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
504 Enable a particular keyword in the mtree output.
505 Prefix with an exclamation mark to disable the corresponding keyword.
506 The default is equivalent to
507 .Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname .
509 Enables all of the above keywords.
511 Enables generation of
513 lines that specify default values for the following files and/or directories.
515 XXX needs explanation XXX
518 .Bl -tag -compact -width indent
520 The value is used as a character set name that will be
521 used when translating file names.
524 .Bl -tag -compact -width indent
526 The value is used as a character set name that will be
527 used when translating file names.
530 .Bl -tag -compact -width indent
532 The value is used as a character set name that will be
533 used when translating file names.
536 .Bl -tag -compact -width indent
538 The value is used as a character set name that will be
539 used when translating file, group and user names.
546 there is no character conversion, with
548 names are converted to UTF-8.
550 When storing extended attributes, this option configures which
551 headers should be written. The value is one of
563 .Bl -tag -compact -width indent
565 The value is used as a character set name that will be
566 used when translating file, group and user names.
569 .Bl -tag -compact -width indent
571 The value is used as a character set name that will be
572 used when translating file, group and user names.
575 .Bl -tag -compact -width indent
579 to disable output of the warcinfo record.
582 .Bl -tag -compact -width indent
583 .It Cm checksum Ns = Ns Ar type
586 as file checksum method.
593 .It Cm compression Ns = Ns Ar type
596 as compression method.
605 .It Cm compression_level
606 The value is a decimal integer from 1 to 9 specifying the compression level.
607 .It Cm toc-checksum Ns = Ns Ar type
610 as table of contents checksum method.
619 .Bl -tag -compact -width indent
625 to indicate how the following entries should be compressed.
626 Note that this setting is ignored for directories, symbolic links,
627 and other special entries.
628 .It Cm compression-level
629 The value is interpreted as a decimal integer specifying the
631 Values between 0 and 9 are supported.
632 A compression level of 0 switches the compression method to
634 other values will enable
636 compression with the given level.
638 Enable encryption using traditional zip encryption.
639 .It Cm encryption Ns = Ns Ar type
645 .Pq traditional zip encryption ,
647 .Pq WinZip AES-128 encryption
650 .Pq WinZip AES-256 encryption .
652 This boolean option enables or disables experimental Zip features
653 that may not be compatible with other Zip implementations.
655 This boolean option disables CRC calculations.
656 All CRC fields are set to zero.
657 It should not be used except for testing purposes.
659 The value is used as a character set name that will be
660 used when translating file names.
662 Zip64 extensions provide additional file size information
663 for entries larger than 4 GiB.
664 They also provide extended file offset and archive size information
665 when archives exceed 4 GiB.
666 By default, the Zip writer selectively enables these extensions only as needed.
667 In particular, if the file size is unknown, the Zip writer will
668 include Zip64 extensions to guard against the possibility that the
669 file might be larger than 4 GiB.
671 Setting this boolean option will force the writer to use Zip64 extensions
672 even for small files that would not otherwise require them.
673 This is primarily useful for testing.
675 Disabling this option with
677 will force the Zip writer to avoid Zip64 extensions:
678 It will reject files with size greater than 4 GiB,
679 it will reject any new entries once the total archive size reaches 4 GiB,
680 and it will not use Zip64 extensions for files with unknown size.
681 In particular, this can improve compatibility when generating archives
682 where the entry sizes are not known in advance.
686 The following example creates an archive write handle to
687 create a gzip-compressed ISO9660 format image.
688 The two options here specify that the ISO9660 archive will use
690 as the boot image for El Torito booting, and that the gzip
691 compressor should use the maximum compression level.
692 .Bd -literal -offset indent
693 a = archive_write_new();
694 archive_write_add_filter_gzip(a);
695 archive_write_set_format_iso9660(a);
696 archive_write_set_options(a, "boot=kernel.img,compression=9");
697 archive_write_open_filename(a, filename, blocksize);
701 More detailed error codes and textual descriptions are available from the
704 .Fn archive_error_string
709 .Xr archive_read_set_options 3 ,
710 .Xr archive_write 3 ,
715 library first appeared in
719 The options support for libarchive was originally implemented by
720 .An Michihiro NAKAJIMA .