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 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 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 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
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 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
478 More detailed error codes and textual descriptions are available from the
479 archive_errno() and archive_error_string() functions.
480
482 tar(1), archive_read_set_options(3), archive_write(3), libarchive(3)
483
485 The libarchive library first appeared in FreeBSD 5.3.
486
488 The options support for libarchive was originally implemented by
489 Michihiro NAKAJIMA.
490
492BSD January 31, 2020 BSD