1ARCHIVE_WRITE_OPTIONS(3) BSD Library Functions Manual ARCHIVE_WRITE_OPTIONS(3)
2
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
9 Streaming Archive Library (libarchive, -larchive)
10
12 int
13 archive_write_set_filter_option(struct archive *, const char *module,
14 const char *option, const char *value);
15 int
17 archive_write_set_format_option(struct archive *, const char *module,
18 const char *option, const char *value);
19 int
21 archive_write_set_option(struct archive *, const char *module,
22 const char *option, const char *value);
23 int
25 archive_write_set_options(struct archive *, const char *options);
26
28 These functions provide a way for libarchive clients to configure spe‐
29 cific write modules.
30 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 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 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 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 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 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 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
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
143 library 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
150 entries.
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
155 depends on the chosen compression method.
156 Format cpio
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
192 directly 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
219 image. 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
222 default 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
227 period. 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
241 underscore 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).
328 Default: 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 pax
367 hdrcharset
368 The value is used as a character set name that will be
369 used when translating file, group and user names. The
370 value is one of “BINARY” or “UTF-8”. With “BINARY” there
371 is no character conversion, with “UTF-8” names are con‐
372 verted to UTF-8.
373 xattrheader
374 When storing extended attributes, this option configures
375 which headers should be written. The value is one of
376 “all”, “LIBARCHIVE”, or “SCHILY”. By default, both
377 “LIBARCHIVE.xattr” and “SCHILY.xattr” headers are writ‐
378 ten.
379 Format ustar
380 hdrcharset
381 The value is used as a character set name that will be
382 used when translating file, group and user names.
383 Format v7tar
384 hdrcharset
385 The value is used as a character set name that will be
386 used when translating file, group and user names.
387 Format warc
388 omit-warcinfo
389 Set to “true” to disable output of the warcinfo record.
390 Format xar
391 checksum=type
392 Use type as file checksum method. Supported values are
393 “none”, “md5”, and “sha1” (default).
394 compression=type
395 Use type as compression method. Supported values are
396 “none”, “bzip2”, “gzip” (default), “lzma” and “xz”.
397 compression_level
398 The value is a decimal integer from 1 to 9 specifying the
399 compression level.
400 toc-checksum=type
401 Use type as table of contents checksum method. Supported
402 values are “none”, “md5” and “sha1” (default).
403 Format zip
404 compression
405 The value is either “store” or “deflate” to indicate how
406 the following entries should be compressed. Note that
407 this setting is ignored for directories, symbolic links,
408 and other special entries.
409 compression-level
410 The value is interpreted as a decimal integer specifying
411 the compression level. Values between 0 and 9 are sup‐
412 ported. A compression level of 0 switches the compres‐
413 sion method to “store”, other values will enable
414 “deflate” compression with the given level.
415 encryption
416 Enable encryption using traditional zip encryption.
417 encryption=type
418 Use type as encryption type. Supported values are
419 “zipcrypt” (traditional zip encryption), “aes128” (WinZip
420 AES-128 encryption) and “aes256” (WinZip AES-256
421 encryption).
422 experimental
423 This boolean option enables or disables experimental Zip
424 features that may not be compatible with other Zip imple‐
425 mentations.
426 fakecrc32
427 This boolean option disables CRC calculations. All CRC
428 fields are set to zero. It should not be used except for
429 testing purposes.
430 hdrcharset
431 The value is used as a character set name that will be
432 used when translating file names.
433 zip64 Zip64 extensions provide additional file size information
434 for entries larger than 4 GiB. They also provide
435 extended file offset and archive size information when
436 archives exceed 4 GiB. By default, the Zip writer selec‐
437 tively enables these extensions only as needed. In par‐
438 ticular, if the file size is unknown, the Zip writer will
439 include Zip64 extensions to guard against the possibility
440 that the file might be larger than 4 GiB.
441 Setting this boolean option will force the writer to use
443 Zip64 extensions even for small files that would not oth‐
444 erwise require them. This is primarily useful for test‐
445 ing.
446 Disabling this option with !zip64 will force the Zip
448 writer to avoid Zip64 extensions: It will reject files
449 with size greater than 4 GiB, it will reject any new
450 entries once the total archive size reaches 4 GiB, and it
451 will not use Zip64 extensions for files with unknown
452 size. In particular, this can improve compatibility when
453 generating archives where the entry sizes are not known
454 in advance.
455
457 The following example creates an archive write handle to create a gzip-
458 compressed ISO9660 format image. The two options here specify that the
459 ISO9660 archive will use kernel.img as the boot image for El Torito boot‐
460 ing, and that the gzip compressor should use the maximum compression
461 level.
462 a = archive_write_new();
464 archive_write_add_filter_gzip(a);
465 archive_write_set_format_iso9660(a);
466 archive_write_set_options(a, "boot=kernel.img,compression=9");
467 archive_write_open_filename(a, filename, blocksize);
468
470 More detailed error codes and textual descriptions are available from the
471 archive_errno() and archive_error_string() functions.
472
474 tar(1), archive_read_set_options(3), archive_write(3), libarchive(3)
475
477 The libarchive library first appeared in FreeBSD 5.3.
478
480 The options support for libarchive was originally implemented by
481 Michihiro NAKAJIMA.
482
484BSD January 31, 2020 BSD