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