1ARCHIVE_WRITE_OPTIONS(3) BSD Library Functions Manual ARCHIVE_WRITE_OPTIONS(3)
2

NAME

4     archive_write_set_filter_option, archive_write_set_format_option,
5     archive_write_set_option, archive_write_set_options — functions control‐
6     ling options for writing archives
7

LIBRARY

9     Streaming Archive Library (libarchive, -larchive)
10

SYNOPSIS

12     int
13     archive_write_set_filter_option(struct archive *, const char *module,
14         const char *option, const char *value);
15
16     int
17     archive_write_set_format_option(struct archive *, const char *module,
18         const char *option, const char *value);
19
20     int
21     archive_write_set_option(struct archive *, const char *module,
22         const char *option, const char *value);
23
24     int
25     archive_write_set_options(struct archive *, const char *options);
26

DESCRIPTION

28     These functions provide a way for libarchive clients to configure spe‐
29     cific write modules.
30
31     archive_write_set_filter_option(), archive_write_set_format_option()
32             Specifies an option that will be passed to the currently-regis‐
33             tered filters (including decompression filters) or format read‐
34             ers.
35
36             If option and value are both NULL, these functions will do noth‐
37             ing and ARCHIVE_OK will be returned.  If option is NULL but value
38             is not, these functions will do nothing and ARCHIVE_FAILED will
39             be returned.
40
41             If module is not NULL, option and value will be provided to the
42             filter or reader named module.  The return value will be either
43             ARCHIVE_OK if the option was successfully handled or ARCHIVE_WARN
44             if the option was unrecognized by the module or could otherwise
45             not be handled.  If there is no such module, ARCHIVE_FAILED will
46             be returned.
47
48             If module is NULL, option and value will be provided to every
49             registered module.  If any module returns ARCHIVE_FATAL, this
50             value will be returned immediately.  Otherwise, ARCHIVE_OK will
51             be returned if any module accepts the option, and ARCHIVE_FAILED
52             in all other cases.
53
54     archive_write_set_option()
55             Calls archive_write_set_format_option(), then
56             archive_write_set_filter_option().  If either function returns
57             ARCHIVE_FATAL, ARCHIVE_FATAL will be returned immediately.  Oth‐
58             erwise, the greater of the two values will be returned.
59
60     archive_write_set_options()
61             options is a comma-separated list of options.  If options is NULL
62             or empty, ARCHIVE_OK will be returned immediately.
63
64             Individual options have one of the following forms:
65             option=value
66                     The option/value pair will be provided to every module.
67                     Modules that do not accept an option with this name will
68                     ignore it.
69             option  The option will be provided to every module with a value
70                     of “1”.
71             !option
72                     The option will be provided to every module with a NULL
73                     value.
74             module:option=value, module:option, module:!option
75                     As above, but the corresponding option and value will be
76                     provided only to modules whose name matches module.
77

OPTIONS

79     Filter b64encode
80             mode    The value is interpreted as octal digits specifying the
81                     file mode.
82             name    The value specifies the file name.
83     Filter bzip2
84             compression-level
85                     The value is interpreted as a decimal integer specifying
86                     the bzip2 compression level. Supported values are from 1
87                     to 9.
88     Filter gzip
89             compression-level
90                     The value is interpreted as a decimal integer specifying
91                     the gzip compression level. Supported values are from 0
92                     to 9.
93             timestamp
94                     Store timestamp. This is enabled by default.
95     Filter lrzip
96             compression=type
97                     Use type as compression method.  Supported values are
98                     “bzip2”, “gzipi”, “lzo” (ultra fast), and “zpaq” (best,
99                     extremely slow).
100             compression-level
101                     The value is interpreted as a decimal integer specifying
102                     the lrzip compression level. Supported values are from 1
103                     to 9.
104     Filter lz4
105             compression-level
106                     The value is interpreted as a decimal integer specifying
107                     the lz4 compression level. Supported values are from 0 to
108                     9.
109             stream-checksum
110                     Enable stream checksum. This is enabled by default.
111             block-checksum
112                     Enable block checksum. This is disabled by default.
113             block-size
114                     The value is interpreted as a decimal integer specifying
115                     the lz4 compression block size. Supported values are from
116                     4 to 7 (default).
117             block-dependence
118                     Use the previous block of the block being compressed for
119                     a compression dictionary to improve compression ratio.
120                     This is disabled by default.
121     Filter lzop
122             compression-level
123                     The value is interpreted as a decimal integer specifying
124                     the lzop compression level. Supported values are from 1
125                     to 9.
126     Filter uuencode
127             mode    The value is interpreted as octal digits specifying the
128                     file mode.
129             name    The value specifies the file name.
130     Filter xz
131             compression-level
132                     The value is interpreted as a decimal integer specifying
133                     the compression level. Supported values are from 0 to 9.
134             threads
135                     The value is interpreted as a decimal integer specifying
136                     the number of threads for multi-threaded lzma compres‐
137                     sion.  If supported, the default value is read from
138                     lzma_cputhreads().
139     Filter zstd
140             compression-level
141                     The value is interpreted as a decimal integer specifying
142                     the compression level. Supported values depend on the li‐
143                     brary version, common values are from 1 to 22.
144     Format 7zip
145             compression
146                     The value is one of “store”, “deflate”, “bzip2”, “lzma1”,
147                     “lzma2” or “ppmd” to indicate how the following entries
148                     should be compressed.  Note that this setting is ignored
149                     for directories, symbolic links, and other special en‐
150                     tries.
151             compression-level
152                     The value is interpreted as a decimal integer specifying
153                     the compression level.  Values between 0 and 9 are sup‐
154                     ported.  The interpretation of the compression level de‐
155                     pends on the chosen compression method.
156     Format bin
157             hdrcharset
158                     The value is used as a character set name that will be
159                     used when translating file names.
160     Format gnutar
161             hdrcharset
162                     The value is used as a character set name that will be
163                     used when translating file, group and user names.
164     Format iso9660 - volume metadata
165             These options are used to set standard ISO9660 metadata.
166             abstract-file=filename
167                     The file with the specified name will be identified in
168                     the ISO9660 metadata as holding the abstract for this
169                     volume.  Default: none.
170             application-id=filename
171                     The file with the specified name will be identified in
172                     the ISO9660 metadata as holding the application identi‐
173                     fier for this volume.  Default: none.
174             biblio-file=filename
175                     The file with the specified name will be identified in
176                     the ISO9660 metadata as holding the bibliography for this
177                     volume.  Default: none.
178             copyright-file=filename
179                     The file with the specified name will be identified in
180                     the ISO9660 metadata as holding the copyright for this
181                     volume.  Default: none.
182             publisher=filename
183                     The file with the specified name will be identified in
184                     the ISO9660 metadata as holding the publisher information
185                     for this volume.  Default: none.
186             volume-id=string
187                     The specified string will be used as the Volume Identi‐
188                     fier in the ISO9660 metadata.  It is limited to 32 bytes.
189                     Default: none.
190     Format iso9660 - boot support
191             These options are used to make an ISO9660 image that can be di‐
192             rectly booted on various systems.
193             boot=filename
194                     The file matching this name will be used as the El Torito
195                     boot image file.
196             boot-catalog=name
197                     The name that will be used for the El Torito boot cata‐
198                     log.  Default: boot.catalog
199             boot-info-table
200                     The boot image file provided by the boot=filename option
201                     will be edited with appropriate boot information in bytes
202                     8 through 64.  Default: disabled
203             boot-load-seg=hexadecimal-number
204                     The load segment for a no-emulation boot image.
205             boot-load-size=decimal-number
206                     The number of "virtual" 512-byte sectors to be loaded
207                     from a no-emulation boot image.  Some very old BIOSes can
208                     only load very small images, setting this value to 4 will
209                     often allow such BIOSes to load the first part of the
210                     boot image (which will then need to be intelligent enough
211                     to load the rest of itself).  This should not be needed
212                     unless you are trying to support systems with very old
213                     BIOSes.  This defaults to the full size of the image.
214             boot-type=value
215                     Specifies the boot semantics used by the El Torito boot
216                     image: If the value is fd, then the boot image is assumed
217                     to be a bootable floppy image.  If the value is hd, then
218                     the boot image is assumed to be a bootable hard disk im‐
219                     age.  If the value is no-emulation, the boot image is
220                     used without floppy or hard disk emulation.  If the boot
221                     image is exactly 1.2MB, 1.44MB, or 2.88MB, then the de‐
222                     fault is fd, otherwise the default is no-emulation.
223     Format iso9660 - filename and size extensions
224             Various extensions to the base ISO9660 format.
225             allow-ldots
226                     If enabled, allows filenames to begin with a leading pe‐
227                     riod.  If disabled, filenames that begin with a leading
228                     period will have that period replaced by an underscore
229                     character in the standard ISO9660 namespace.  This does
230                     not impact names stored in the Rockridge or Joliet exten‐
231                     sion area.  Default: disabled.
232             allow-lowercase
233                     If enabled, allows filenames to contain lowercase charac‐
234                     ters.  If disabled, filenames will be forced to upper‐
235                     case.  This does not impact names stored in the Rockridge
236                     or Joliet extension area.  Default: disabled.
237             allow-multidot
238                     If enabled, allows filenames to contain multiple period
239                     characters, in violation of the ISO9660 specification.
240                     If disabled, additional periods will be converted to un‐
241                     derscore characters.  This does not impact names stored
242                     in the Rockridge or Joliet extension area.  Default: dis‐
243                     abled.
244             allow-period
245                     If enabled, allows filenames to contain trailing period
246                     characters, in violation of the ISO9660 specification.
247                     If disabled, trailing periods will be converted to under‐
248                     score characters.  This does not impact names stored in
249                     the Rockridge or Joliet extension area.  Default: dis‐
250                     abled.
251             allow-pvd-lowercase
252                     If enabled, the Primary Volume Descriptor may contain
253                     lowercase ASCII characters, in violation of the ISO9660
254                     specification.  If disabled, characters will be converted
255                     to uppercase ASCII.  Default: disabled.
256             allow-sharp-tilde
257                     If enabled, sharp and tilde characters will be permitted
258                     in filenames, in violation if the ISO9660 specification.
259                     If disabled, such characters will be converted to under‐
260                     score characters.  Default: disabled.
261             allow-vernum
262                     If enabled, version numbers will be included with files.
263                     If disabled, version numbers will be suppressed, in vio‐
264                     lation of the ISO9660 standard.  This does not impact
265                     names stored in the Rockridge or Joliet extension area.
266                     Default: enabled.
267             iso-level
268                     This enables support for file size and file name exten‐
269                     sions in the core ISO9660 area.  The name extensions
270                     specified here do not affect the names stored in the
271                     Rockridge or Joliet extension areas.
272                     iso-level=1
273                             The most compliant form of ISO9660 image.  File‐
274                             names are limited to 8.3 uppercase format, direc‐
275                             tory names are limited to 8 uppercase characters,
276                             files are limited to 4 GiB, the complete ISO9660
277                             image cannot exceed 4 GiB.
278                     iso-level=2
279                             Filenames are limited to 30 uppercase characters
280                             with a 30-character extension, directory names
281                             are limited to 30 characters, files are limited
282                             to 4 GiB.
283                     iso-level=3
284                             As with iso-level=2, except that files may exceed
285                             4 GiB.
286                     iso-level=4
287                             As with iso-level=3, except that filenames may be
288                             up to 193 characters and may include arbitrary
289                             8-bit characters.
290             joliet  Microsoft's Joliet extensions store a completely separate
291                     set of directory information about each file.  In partic‐
292                     ular, this information includes Unicode filenames of up
293                     to 255 characters.  Default: enabled.
294             limit-depth
295                     If enabled, libarchive will use directory relocation
296                     records to ensure that no pathname exceeds the ISO9660
297                     limit of 8 directory levels.  If disabled, no relocation
298                     will occur.  Default: enabled.
299             limit-dirs
300                     If enabled, libarchive will cause an error if there are
301                     more than 65536 directories.  If disabled, there is no
302                     limit on the number of directories.  Default: enabled
303             pad     If enabled, 300 kiB of zero bytes will be appended to the
304                     end of the archive.  Default: enabled
305             relaxed-filenames
306                     If enabled, all 7-bit ASCII characters are permitted in
307                     filenames (except lowercase characters unless
308                     allow-lowercase is also specified).  This violates
309                     ISO9660 standards.  This does not impact names stored in
310                     the Rockridge or Joliet extension area.  Default: dis‐
311                     abled.
312             rockridge
313                     The Rockridge extensions store an additional set of
314                     POSIX-style file information with each file, including
315                     mtime, atime, ctime, permissions, and long filenames with
316                     arbitrary 8-bit characters.  These extensions also sup‐
317                     port symbolic links and other POSIX file types.  Default:
318                     enabled.
319     Format iso9660 - zisofs support
320             The zisofs extensions permit each file to be independently com‐
321             pressed using a gzip-compatible compression.  This can provide
322             significant size savings, but requires the reading system to have
323             support for these extensions.  These extensions are disabled by
324             default.
325             compression-level=number
326                     The compression level used by the deflate compressor.
327                     Ranges from 0 (least effort) to 9 (most effort).  De‐
328                     fault: 6
329             zisofs  Synonym for zisofs=direct.
330             zisofs=direct
331                     Compress each file in the archive.  Unlike
332                     zisofs=indirect, this is handled entirely within
333                     libarchive and does not require a separate utility.  For
334                     best results, libarchive tests each file and will store
335                     the file uncompressed if the compression does not actu‐
336                     ally save any space.  In particular, files under 2k will
337                     never be compressed.  Note that boot image files are
338                     never compressed.
339             zisofs=indirect
340                     Recognizes files that have already been compressed with
341                     the mkzftree utility and sets up the necessary file meta‐
342                     data so that readers will correctly identify these as
343                     zisofs-compressed files.
344             zisofs-exclude=filename
345                     Specifies a filename that should not be compressed when
346                     using zisofs=direct.  This option can be provided multi‐
347                     ple times to suppress compression on many files.
348     Format mtree
349             cksum, device, flags, gid, gname, indent, link, md5, mode, nlink,
350                     rmd160, sha1, sha256, sha384, sha512, size, time, uid,
351                     uname
352                     Enable a particular keyword in the mtree output.  Prefix
353                     with an exclamation mark to disable the corresponding
354                     keyword.  The default is equivalent to “device, flags,
355                     gid, gname, link, mode, nlink, size, time, type, uid,
356                     uname”.
357             all     Enables all of the above keywords.
358             use-set
359                     Enables generation of /set lines that specify default
360                     values for the following files and/or directories.
361             indent  XXX needs explanation XXX
362     Format newc
363             hdrcharset
364                     The value is used as a character set name that will be
365                     used when translating file names.
366     Format odc
367             hdrcharset
368                     The value is used as a character set name that will be
369                     used when translating file names.
370     Format pwb
371             hdrcharset
372                     The value is used as a character set name that will be
373                     used when translating file names.
374     Format pax
375             hdrcharset
376                     The value is used as a character set name that will be
377                     used when translating file, group and user names.  The
378                     value is one of “BINARY” or “UTF-8”.  With “BINARY” there
379                     is no character conversion, with “UTF-8” names are con‐
380                     verted to UTF-8.
381             xattrheader
382                     When storing extended attributes, this option configures
383                     which headers should be written. The value is one of
384                     “all”, “LIBARCHIVE”, or “SCHILY”.  By default, both
385                     “LIBARCHIVE.xattr” and “SCHILY.xattr” headers are writ‐
386                     ten.
387     Format ustar
388             hdrcharset
389                     The value is used as a character set name that will be
390                     used when translating file, group and user names.
391     Format v7tar
392             hdrcharset
393                     The value is used as a character set name that will be
394                     used when translating file, group and user names.
395     Format warc
396             omit-warcinfo
397                     Set to “true” to disable output of the warcinfo record.
398     Format xar
399             checksum=type
400                     Use type as file checksum method.  Supported values are
401                     “none”, “md5”, and “sha1” (default).
402             compression=type
403                     Use type as compression method.  Supported values are
404                     “none”, “bzip2”, “gzip” (default), “lzma” and “xz”.
405             compression_level
406                     The value is a decimal integer from 1 to 9 specifying the
407                     compression level.
408             toc-checksum=type
409                     Use type as table of contents checksum method.  Supported
410                     values are “none”, “md5” and “sha1” (default).
411     Format zip
412             compression
413                     The value is either “store” or “deflate” to indicate how
414                     the following entries should be compressed.  Note that
415                     this setting is ignored for directories, symbolic links,
416                     and other special entries.
417             compression-level
418                     The value is interpreted as a decimal integer specifying
419                     the compression level.  Values between 0 and 9 are sup‐
420                     ported.  A compression level of 0 switches the compres‐
421                     sion method to “store”, other values will enable
422                     “deflate” compression with the given level.
423             encryption
424                     Enable encryption using traditional zip encryption.
425             encryption=type
426                     Use type as encryption type.  Supported values are
427                     “zipcrypt” (traditional zip encryption), “aes128” (WinZip
428                     AES-128 encryption) and “aes256” (WinZip AES-256
429                     encryption).
430             experimental
431                     This boolean option enables or disables experimental Zip
432                     features that may not be compatible with other Zip imple‐
433                     mentations.
434             fakecrc32
435                     This boolean option disables CRC calculations.  All CRC
436                     fields are set to zero.  It should not be used except for
437                     testing purposes.
438             hdrcharset
439                     The value is used as a character set name that will be
440                     used when translating file names.
441             zip64   Zip64 extensions provide additional file size information
442                     for entries larger than 4 GiB.  They also provide ex‐
443                     tended file offset and archive size information when ar‐
444                     chives exceed 4 GiB.  By default, the Zip writer selec‐
445                     tively enables these extensions only as needed.  In par‐
446                     ticular, if the file size is unknown, the Zip writer will
447                     include Zip64 extensions to guard against the possibility
448                     that the file might be larger than 4 GiB.
449
450                     Setting this boolean option will force the writer to use
451                     Zip64 extensions even for small files that would not oth‐
452                     erwise require them.  This is primarily useful for test‐
453                     ing.
454
455                     Disabling this option with !zip64 will force the Zip
456                     writer to avoid Zip64 extensions: It will reject files
457                     with size greater than 4 GiB, it will reject any new en‐
458                     tries once the total archive size reaches 4 GiB, and it
459                     will not use Zip64 extensions for files with unknown
460                     size.  In particular, this can improve compatibility when
461                     generating archives where the entry sizes are not known
462                     in advance.
463

EXAMPLES

465     The following example creates an archive write handle to create a gzip-
466     compressed ISO9660 format image.  The two options here specify that the
467     ISO9660 archive will use kernel.img as the boot image for El Torito boot‐
468     ing, and that the gzip compressor should use the maximum compression
469     level.
470
471           a = archive_write_new();
472           archive_write_add_filter_gzip(a);
473           archive_write_set_format_iso9660(a);
474           archive_write_set_options(a, "boot=kernel.img,compression=9");
475           archive_write_open_filename(a, filename, blocksize);
476

ERRORS

478     More detailed error codes and textual descriptions are available from the
479     archive_errno() and archive_error_string() functions.
480

SEE ALSO

482     tar(1), archive_read_set_options(3), archive_write(3), libarchive(3)
483

HISTORY

485     The libarchive library first appeared in FreeBSD 5.3.
486

AUTHORS

488     The options support for libarchive was originally implemented by
489     Michihiro NAKAJIMA.
490

BUGS

492BSD                            January 31, 2020                            BSD
Impressum