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)
40 .Fo archive_write_set_filter_option
41 .Fa "struct archive *"
42 .Fa "const char *module"
43 .Fa "const char *option"
44 .Fa "const char *value"
47 .Fo archive_write_set_format_option
48 .Fa "struct archive *"
49 .Fa "const char *module"
50 .Fa "const char *option"
51 .Fa "const char *value"
54 .Fo archive_write_set_option
55 .Fa "struct archive *"
56 .Fa "const char *module"
57 .Fa "const char *option"
58 .Fa "const char *value"
61 .Fo archive_write_set_options
62 .Fa "struct archive *"
63 .Fa "const char *options"
66 These functions provide a way for libarchive clients to configure
67 specific write modules.
68 .Bl -tag -width indent
70 .Fn archive_write_set_filter_option ,
71 .Fn archive_write_set_format_option
73 Specifies an option that will be passed to the currently-registered
74 filters (including decompression filters) or format readers.
82 these functions will do nothing and
91 is not, these functions will do nothing and
102 will be provided to the filter or reader named
104 The return value will be either
106 if the option was successfully handled or
108 if the option was unrecognized by the module or could otherwise
110 If there is no such module,
121 will be provided to every registered module.
122 If any module returns
124 this value will be returned immediately.
127 will be returned if any module accepts the option, and
131 .It Fn archive_write_set_option
133 .Fn archive_write_set_format_option ,
135 .Fn archive_write_set_filter_option .
136 If either function returns
141 Otherwise, the greater of the two values will be returned.
143 .It Fn archive_write_set_options
145 is a comma-separated list of options.
152 will be returned immediately.
154 Individual options have one of the following forms:
155 .Bl -tag -compact -width indent
157 The option/value pair will be provided to every module.
158 Modules that do not accept an option with this name will ignore it.
160 The option will be provided to every module with a value of
163 The option will be provided to every module with a NULL value.
164 .It Ar module:option=value , Ar module:option , Ar module:!option
165 As above, but the corresponding option and value will be provided
166 only to modules whose name matches
172 .Bl -tag -compact -width indent
174 .Bl -tag -compact -width indent
176 The value is interpreted as octal digits specifying the file mode.
178 The value specifies the file name.
181 .Bl -tag -compact -width indent
182 .It Cm compression-level
183 The value is interpreted as a decimal integer specifying the
184 bzip2 compression level. Supported values are from 1 to 9.
187 .Bl -tag -compact -width indent
188 .It Cm compression-level
189 The value is interpreted as a decimal integer specifying the
190 gzip compression level. Supported values are from 0 to 9.
192 Store timestamp. This is enabled by default.
195 .Bl -tag -compact -width indent
196 .It Cm compression Ns = Ns Ar type
199 as compression method.
207 .Pq best, extremely slow .
208 .It Cm compression-level
209 The value is interpreted as a decimal integer specifying the
210 lrzip compression level. Supported values are from 1 to 9.
213 .Bl -tag -compact -width indent
214 .It Cm compression-level
215 The value is interpreted as a decimal integer specifying the
216 lz4 compression level. Supported values are from 0 to 9.
217 .It Cm stream-checksum
218 Enable stream checksum. This is enabled by default.
219 .It Cm block-checksum
220 Enable block checksum. This is disabled by default.
222 The value is interpreted as a decimal integer specifying the
223 lz4 compression block size. Supported values are from 4 to 7
225 .It Cm block-dependence
226 Use the previous block of the block being compressed for
227 a compression dictionary to improve compression ratio.
228 This is disabled by default.
231 .Bl -tag -compact -width indent
232 .It Cm compression-level
233 The value is interpreted as a decimal integer specifying the
234 lzop compression level. Supported values are from 1 to 9.
237 .Bl -tag -compact -width indent
239 The value is interpreted as octal digits specifying the file mode.
241 The value specifies the file name.
244 .Bl -tag -compact -width indent
245 .It Cm compression-level
246 The value is interpreted as a decimal integer specifying the
247 compression level. Supported values are from 0 to 9.
249 The value is interpreted as a decimal integer specifying the
250 number of threads for multi-threaded lzma compression.
251 If supported, the default value is read from
252 .Fn lzma_cputhreads .
255 .Bl -tag -compact -width indent
256 .It Cm compression-level
257 The value is interpreted as a decimal integer specifying the
258 compression level. Supported values depend on the library version,
259 common values are from 1 to 22.
262 .Bl -tag -compact -width indent
272 to indicate how the following entries should be compressed.
273 Note that this setting is ignored for directories, symbolic links,
274 and other special entries.
275 .It Cm compression-level
276 The value is interpreted as a decimal integer specifying the
278 Values between 0 and 9 are supported.
279 The interpretation of the compression level depends on the chosen
283 .Bl -tag -compact -width indent
285 The value is used as a character set name that will be
286 used when translating file names.
289 .Bl -tag -compact -width indent
291 The value is used as a character set name that will be
292 used when translating file, group and user names.
294 .It Format iso9660 - volume metadata
295 These options are used to set standard ISO9660 metadata.
296 .Bl -tag -compact -width indent
297 .It Cm abstract-file Ns = Ns Ar filename
298 The file with the specified name will be identified in the ISO9660 metadata
299 as holding the abstract for this volume.
301 .It Cm application-id Ns = Ns Ar filename
302 The file with the specified name will be identified in the ISO9660 metadata
303 as holding the application identifier for this volume.
305 .It Cm biblio-file Ns = Ns Ar filename
306 The file with the specified name will be identified in the ISO9660 metadata
307 as holding the bibliography for this volume.
309 .It Cm copyright-file Ns = Ns Ar filename
310 The file with the specified name will be identified in the ISO9660 metadata
311 as holding the copyright for this volume.
313 .It Cm publisher Ns = Ns Ar filename
314 The file with the specified name will be identified in the ISO9660 metadata
315 as holding the publisher information for this volume.
317 .It Cm volume-id Ns = Ns Ar string
318 The specified string will be used as the Volume Identifier in the ISO9660 metadata.
319 It is limited to 32 bytes.
322 .It Format iso9660 - boot support
323 These options are used to make an ISO9660 image that can be directly
324 booted on various systems.
325 .Bl -tag -compact -width indent
326 .It Cm boot Ns = Ns Ar filename
327 The file matching this name will be used as the El Torito boot image file.
328 .It Cm boot-catalog Ns = Ns Ar name
329 The name that will be used for the El Torito boot catalog.
332 .It Cm boot-info-table
333 The boot image file provided by the
334 .Cm boot Ns = Ns Ar filename
335 option will be edited with appropriate boot information in bytes 8 through 64.
337 .It Cm boot-load-seg Ns = Ns Ar hexadecimal-number
338 The load segment for a no-emulation boot image.
339 .It Cm boot-load-size Ns = Ns Ar decimal-number
340 The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image.
341 Some very old BIOSes can only load very small images, setting this
342 value to 4 will often allow such BIOSes to load the first part of
343 the boot image (which will then need to be intelligent enough to
344 load the rest of itself).
345 This should not be needed unless you are trying to support systems with very old BIOSes.
346 This defaults to the full size of the image.
347 .It Cm boot-type Ns = Ns Ar value
348 Specifies the boot semantics used by the El Torito boot image:
353 then the boot image is assumed to be a bootable floppy image.
358 then the boot image is assumed to be a bootable hard disk image.
363 the boot image is used without floppy or hard disk emulation.
364 If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then
367 otherwise the default is
370 .It Format iso9660 - filename and size extensions
371 Various extensions to the base ISO9660 format.
372 .Bl -tag -compact -width indent
374 If enabled, allows filenames to begin with a leading period.
375 If disabled, filenames that begin with a leading period will have
376 that period replaced by an underscore character in the standard ISO9660
378 This does not impact names stored in the Rockridge or Joliet extension area.
380 .It Cm allow-lowercase
381 If enabled, allows filenames to contain lowercase characters.
382 If disabled, filenames will be forced to uppercase.
383 This does not impact names stored in the Rockridge or Joliet extension area.
385 .It Cm allow-multidot
386 If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification.
387 If disabled, additional periods will be converted to underscore characters.
388 This does not impact names stored in the Rockridge or Joliet extension area.
391 If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification.
392 If disabled, trailing periods will be converted to underscore characters.
393 This does not impact names stored in the Rockridge or Joliet extension area.
395 .It Cm allow-pvd-lowercase
396 If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification.
397 If disabled, characters will be converted to uppercase ASCII.
399 .It Cm allow-sharp-tilde
400 If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification.
401 If disabled, such characters will be converted to underscore characters.
404 If enabled, version numbers will be included with files.
405 If disabled, version numbers will be suppressed, in violation of the ISO9660 standard.
406 This does not impact names stored in the Rockridge or Joliet extension area.
409 This enables support for file size and file name extensions in the
411 The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas.
412 .Bl -tag -compact -width indent
414 The most compliant form of ISO9660 image.
415 Filenames are limited to 8.3 uppercase format,
416 directory names are limited to 8 uppercase characters,
417 files are limited to 4 GiB,
418 the complete ISO9660 image cannot exceed 4 GiB.
420 Filenames are limited to 30 uppercase characters with a 30-character extension,
421 directory names are limited to 30 characters,
422 files are limited to 4 GiB.
426 except that files may exceed 4 GiB.
430 except that filenames may be up to 193 characters
431 and may include arbitrary 8-bit characters.
434 Microsoft's Joliet extensions store a completely separate set of directory information about each file.
435 In particular, this information includes Unicode filenames of up to 255 characters.
438 If enabled, libarchive will use directory relocation records to ensure that
439 no pathname exceeds the ISO9660 limit of 8 directory levels.
440 If disabled, no relocation will occur.
443 If enabled, libarchive will cause an error if there are more than
445 If disabled, there is no limit on the number of directories.
448 If enabled, 300 kiB of zero bytes will be appended to the end of the archive.
450 .It Cm relaxed-filenames
451 If enabled, all 7-bit ASCII characters are permitted in filenames
452 (except lowercase characters unless
455 This violates ISO9660 standards.
456 This does not impact names stored in the Rockridge or Joliet extension area.
459 The Rockridge extensions store an additional set of POSIX-style file
460 information with each file, including mtime, atime, ctime, permissions,
461 and long filenames with arbitrary 8-bit characters.
462 These extensions also support symbolic links and other POSIX file types.
465 .It Format iso9660 - zisofs support
466 The zisofs extensions permit each file to be independently compressed
467 using a gzip-compatible compression.
468 This can provide significant size savings, but requires the reading
469 system to have support for these extensions.
470 These extensions are disabled by default.
471 .Bl -tag -compact -width indent
472 .It Cm compression-level Ns = Ns number
473 The compression level used by the deflate compressor.
474 Ranges from 0 (least effort) to 9 (most effort).
480 Compress each file in the archive.
482 .Cm zisofs=indirect ,
483 this is handled entirely within libarchive and does not require a
485 For best results, libarchive tests each file and will store
486 the file uncompressed if the compression does not actually save any space.
487 In particular, files under 2k will never be compressed.
488 Note that boot image files are never compressed.
489 .It Cm zisofs=indirect
490 Recognizes files that have already been compressed with the
492 utility and sets up the necessary file metadata so that
493 readers will correctly identify these as zisofs-compressed files.
494 .It Cm zisofs-exclude Ns = Ns Ar filename
495 Specifies a filename that should not be compressed when using
497 This option can be provided multiple times to suppress compression
501 .Bl -tag -compact -width indent
502 .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
503 Enable a particular keyword in the mtree output.
504 Prefix with an exclamation mark to disable the corresponding keyword.
505 The default is equivalent to
506 .Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname .
508 Enables all of the above keywords.
510 Enables generation of
512 lines that specify default values for the following files and/or directories.
514 XXX needs explanation XXX
517 .Bl -tag -compact -width indent
519 The value is used as a character set name that will be
520 used when translating file names.
523 .Bl -tag -compact -width indent
525 The value is used as a character set name that will be
526 used when translating file, group and user names.
533 there is no character conversion, with
535 names are converted to UTF-8.
537 When storing extended attributes, this option configures which
538 headers should be written. The value is one of
550 .Bl -tag -compact -width indent
552 The value is used as a character set name that will be
553 used when translating file, group and user names.
556 .Bl -tag -compact -width indent
558 The value is used as a character set name that will be
559 used when translating file, group and user names.
562 .Bl -tag -compact -width indent
566 to disable output of the warcinfo record.
569 .Bl -tag -compact -width indent
570 .It Cm checksum Ns = Ns Ar type
573 as file checksum method.
580 .It Cm compression Ns = Ns Ar type
583 as compression method.
592 .It Cm compression_level
593 The value is a decimal integer from 1 to 9 specifying the compression level.
594 .It Cm toc-checksum Ns = Ns Ar type
597 as table of contents checksum method.
606 .Bl -tag -compact -width indent
612 to indicate how the following entries should be compressed.
613 Note that this setting is ignored for directories, symbolic links,
614 and other special entries.
615 .It Cm compression-level
616 The value is interpreted as a decimal integer specifying the
618 Values between 0 and 9 are supported.
619 A compression level of 0 switches the compression method to
621 other values will enable
623 compression with the given level.
625 Enable encryption using traditional zip encryption.
626 .It Cm encryption Ns = Ns Ar type
632 .Pq traditional zip encryption ,
634 .Pq WinZip AES-128 encryption
637 .Pq WinZip AES-256 encryption .
639 This boolean option enables or disables experimental Zip features
640 that may not be compatible with other Zip implementations.
642 This boolean option disables CRC calculations.
643 All CRC fields are set to zero.
644 It should not be used except for testing purposes.
646 The value is used as a character set name that will be
647 used when translating file names.
649 Zip64 extensions provide additional file size information
650 for entries larger than 4 GiB.
651 They also provide extended file offset and archive size information
652 when archives exceed 4 GiB.
653 By default, the Zip writer selectively enables these extensions only as needed.
654 In particular, if the file size is unknown, the Zip writer will
655 include Zip64 extensions to guard against the possibility that the
656 file might be larger than 4 GiB.
658 Setting this boolean option will force the writer to use Zip64 extensions
659 even for small files that would not otherwise require them.
660 This is primarily useful for testing.
662 Disabling this option with
664 will force the Zip writer to avoid Zip64 extensions:
665 It will reject files with size greater than 4 GiB,
666 it will reject any new entries once the total archive size reaches 4 GiB,
667 and it will not use Zip64 extensions for files with unknown size.
668 In particular, this can improve compatibility when generating archives
669 where the entry sizes are not known in advance.
673 The following example creates an archive write handle to
674 create a gzip-compressed ISO9660 format image.
675 The two options here specify that the ISO9660 archive will use
677 as the boot image for El Torito booting, and that the gzip
678 compressor should use the maximum compression level.
679 .Bd -literal -offset indent
680 a = archive_write_new();
681 archive_write_add_filter_gzip(a);
682 archive_write_set_format_iso9660(a);
683 archive_write_set_options(a, "boot=kernel.img,compression=9");
684 archive_write_open_filename(a, filename, blocksize);
688 More detailed error codes and textual descriptions are available from the
691 .Fn archive_error_string
696 .Xr archive_read_set_options 3 ,
697 .Xr archive_write 3 ,
702 library first appeared in
706 The options support for libarchive was originally implemented by
707 .An Michihiro NAKAJIMA .