1 ARCHIVE_WRITE_OPTIONS(3) manual page
3 '''archive_write_set_filter_option''',
4 '''archive_write_set_format_option''',
5 '''archive_write_set_option''',
6 '''archive_write_set_options'''
7 - functions controlling options for reading archives
9 Streaming Archive Library (libarchive, -larchive)
14 '''archive_write_set_filter_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
18 '''archive_write_set_format_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
22 '''archive_write_set_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
26 '''archive_write_set_options'''(''struct archive *'', ''const char *options'');
28 These functions provide a way for libarchive clients to configure
29 specific write modules.
32 '''archive_write_set_filter_option'''(),
33 '''archive_write_set_format_option'''()
35 Specifies an option that will be passed to currently-registered
36 filters (including decompression filters) or format readers.
44 these functions will do nothing and
53 is not, these functions will do nothing and
64 will be provided to the filter or reader named
66 The return value will be either
68 if the option was successfully handled or
70 if the option was unrecognized by the module or could otherwise
72 If there is no such module,
83 will be provided to every registered module.
86 this value will be returned immediately.
89 will be returned if any module accepts the option, and
92 </dd><dt>'''archive_write_set_option'''()</dt><dd>
94 '''archive_write_set_format_option'''(),
96 '''archive_write_set_filter_option'''().
97 If either function returns
102 Otherwise, greater of the two values will be returned.
103 </dd><dt>'''archive_write_set_options'''()</dt><dd>
105 is a comma-separated list of options.
112 will be returned immediately.
114 Individual options have one of the following forms:
116 <dt>''option=value''</dt><dd>
117 The option/value pair will be provided to every module.
118 Modules that do not accept an option with this name will ignore it.
119 </dd><dt>''option''</dt><dd>
120 The option will be provided to every module with a value of
122 </dd><dt>''!option''</dt><dd>
123 The option will be provided to every module with a NULL value.
124 </dd><dt>''module:option=value'', ''module:option'', ''module:!option''</dt><dd>
125 As above, but the corresponding option and value will be provided
126 only to modules whose name matches
132 <dt>Filter gzip</dt><dd>
134 <dt>'''compression-level'''</dt><dd>
135 The value is interpreted as a decimal integer specifying the
136 gzip compression level.
138 </dd><dt>Filter xz</dt><dd>
140 <dt>'''compression-level'''</dt><dd>
141 The value is interpreted as a decimal integer specifying the
144 </dd><dt>Format mtree</dt><dd>
146 <dt>'''cksum''', '''device''', '''flags''', '''gid''', '''gname''', '''indent''', '''link''', '''md5''', '''mode''', '''nlink''', '''rmd160''', '''sha1''', '''sha256''', '''sha384''', '''sha512''', '''size''', '''time''', '''uid''', '''uname'''</dt><dd>
147 Enable a particular keyword in the mtree output.
148 Prefix with an exclamation mark to disable the corresponding keyword.
149 The default is equivalent to
150 "device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname".
151 </dd><dt>'''all'''</dt><dd>
152 Enables all of the above keywords.
153 </dd><dt>'''use-set'''</dt><dd>
154 Enables generation of
156 lines that specify default values for the following files and/or directories.
157 </dd><dt>'''indent'''</dt><dd>
158 XXX needs explanation XXX
160 </dd><dt>Format iso9660 - volume metadata</dt><dd>
161 These options are used to set standard ISO9660 metadata.
163 <dt>'''abstract-file'''=''filename''</dt><dd>
164 The file with the specified name will be identified in the ISO9660 metadata
165 as holding the abstract for this volume. Default: none.
166 </dd><dt>'''application-id'''=''filename''</dt><dd>
167 The file with the specified name will be identified in the ISO9660 metadata
168 as holding the application identifier for this volume. Default: none.
169 </dd><dt>'''biblio-file'''=''filename''</dt><dd>
170 The file with the specified name will be identified in the ISO9660 metadata
171 as holding the bibliography for this volume. Default: none.
172 </dd><dt>'''copyright-file'''=''filename''</dt><dd>
173 The file with the specified name will be identified in the ISO9660 metadata
174 as holding the copyright for this volume. Default: none.
175 </dd><dt>'''publisher'''=''filename''</dt><dd>
176 The file with the specified name will be identified in the ISO9660 metadata
177 as holding the publisher information for this volume. Default: none.
178 </dd><dt>'''volume-id'''=''string''</dt><dd>
179 The specified string will be used as the Volume Identifier in the ISO9660 metadata.
180 It is limited to 32 bytes. Default: none.
182 </dd><dt>Format iso9660 - boot support</dt><dd>
183 These options are used to make an ISO9660 image that can be directly
184 booted on various systems.
186 <dt>'''boot'''=''filename''</dt><dd>
187 The file matching this name will be used as the El Torito boot image file.
188 </dd><dt>'''boot-catalog'''=''name''</dt><dd>
189 The name that will be used for the El Torito boot catalog.
192 </dd><dt>'''boot-info-table'''</dt><dd>
193 The boot image file provided by the
194 '''boot'''=''filename''
195 option will be edited with appropriate boot information in bytes 8 through 64.
197 </dd><dt>'''boot-load-seg'''=''hexadecimal-number''</dt><dd>
198 The load segment for a no-emulation boot image.
199 </dd><dt>'''boot-load-size'''=''decimal-number''</dt><dd>
200 The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image.
201 Some very old BIOSes can only load very small images, setting this
202 value to 4 will often allow such BIOSes to load the first part of
203 the boot image (which will then need to be intelligent enough to
204 load the rest of itself).
205 This should not be needed unless you are trying to support systems with very old BIOSes.
206 This defaults to the full size of the image.
207 </dd><dt>'''boot-type'''=''value''</dt><dd>
208 Specifies the boot semantics used by the El Torito boot image:
213 then the boot image is assumed to be a bootable floppy image.
218 then the boot image is assumed to be a bootable hard disk image.
223 the boot image is used without floppy or hard disk emulation.
224 If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then
227 otherwise the default is
230 </dd><dt>Format iso9660 - filename and size extensions</dt><dd>
231 Various extensions to the base ISO9660 format.
233 <dt>'''allow-ldots'''</dt><dd>
234 If enabled, allows filenames to begin with a leading period.
235 If disabled, filenames that begin with a leading period will have
236 that period replaced by an underscore character in the standard ISO9660
238 This does not impact names stored in the Rockridge or Joliet extension area.
240 </dd><dt>'''allow-lowercase'''</dt><dd>
241 If enabled, allows filenames to contain lowercase characters.
242 If disabled, filenames will be forced to uppercase.
243 This does not impact names stored in the Rockridge or Joliet extension area.
245 </dd><dt>'''allow-multidot'''</dt><dd>
246 If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification.
247 If disabled, additional periods will be converted to underscore characters.
248 This does not impact names stored in the Rockridge or Joliet extension area.
250 </dd><dt>'''allow-period'''</dt><dd>
251 If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification.
252 If disabled,trailing periods will be converted to underscore characters.
253 This does not impact names stored in the Rockridge or Joliet extension area.
255 </dd><dt>'''allow-pvd-lowercase'''</dt><dd>
256 If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification.
257 If disabled, characters will be converted to uppercase ASCII.
259 </dd><dt>'''allow-sharp-tilde'''</dt><dd>
260 If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification.
261 If disabled, such characters will be converted to underscore characters.
263 </dd><dt>'''allow-vernum'''</dt><dd>
264 If enabled, version numbers will be included with files.
265 If disabled, version numbers will be suppressed, in violation of the ISO9660 standard.
266 This does not impact names stored in the Rockridge or Joliet extension area.
268 </dd><dt>'''iso-level'''</dt><dd>
269 This enables support for file size and file name extensions in the
271 The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas.
273 <dt>'''iso-level=1'''</dt><dd>
274 The most compliant form of ISO9660 image.
275 Filenames are limited to 8.3 uppercase format,
276 directory names are limited to 8 uppercase characters,
277 files are limited to 4 GiB,
278 the complete ISO9660 image cannot exceed 4 GiB.
279 </dd><dt>'''iso-level=2'''</dt><dd>
280 Filenames are limited to 30 uppercase characters with a 30-character extension,
281 directory names are limited to 30 characters,
282 files are limited to 4 GiB.
283 </dd><dt>'''iso-level=3'''</dt><dd>
286 except that files may exceed 4 GiB.
287 </dd><dt>'''iso-level=4'''</dt><dd>
290 except that filenames may be up to 193 characters
291 and may include arbitrary 8-bit characters.
293 </dd><dt>'''joliet'''</dt><dd>
294 Microsoft's Joliet extensions store a completely separate set of directory information about each file.
295 In particular, this information includes Unicode filenames of up to 255 characters.
297 </dd><dt>'''limit-depth'''</dt><dd>
298 If enabled, libarchive will use directory relocation records to ensure that
299 no pathname exceeds the ISO9660 limit of 8 directory levels.
300 If disabled, no relocation will occur.
302 </dd><dt>'''limit-dirs'''</dt><dd>
303 If enabled, libarchive will cause an error if there are more than
305 If disabled, there is no limit on the number of directories.
307 </dd><dt>'''pad'''</dt><dd>
308 If enabled, 300 kiB of zero bytes will be appended to the end of the archive.
310 </dd><dt>'''relaxed-filenames'''</dt><dd>
311 If enabled, all 7-bit ASCII characters are permitted in filenames
312 (except lowercase characters unless
313 '''allow-lowercase'''
315 This violates ISO9660 standards.
316 This does not impact names stored in the Rockridge or Joliet extension area.
318 </dd><dt>'''rockridge'''</dt><dd>
319 The Rockridge extensions store an additional set of POSIX-style file
320 information with each file, including mtime, atime, ctime, permissions,
321 and long filenames with arbitrary 8-bit characters.
322 These extensions also support symbolic links and other POSIX file types.
325 </dd><dt>Format iso9660 - zisofs support</dt><dd>
326 The zisofs extensions permit each file to be independently compressed
327 using a gzip-compatible compression.
328 This can provide significant size savings, but requires the reading
329 system to have support for these extensions.
330 These extensions are disabled by default.
332 <dt>'''compression-level'''=number</dt><dd>
333 The compression level used by the deflate compressor.
334 Ranges from 0 (least effort) to 9 (most effort).
336 </dd><dt>'''zisofs'''</dt><dd>
339 </dd><dt>'''zisofs=direct'''</dt><dd>
340 Compress each file in the archive.
342 '''zisofs=indirect''',
343 this is handled entirely within libarchive and does not require a
345 For best results, libarchive tests each file and will store
346 the file uncompressed if the compression does not actually save any space.
347 In particular, files under 2k will never be compressed.
348 Note that boot image files are never compressed.
349 </dd><dt>'''zisofs=indirect'''</dt><dd>
350 Recognizes files that have already been compressed with the
352 utility and sets up the necessary file metadata so that
353 readers will correctly identify these as zisofs-compressed files.
354 </dd><dt>'''zisofs-exclude'''=''filename''</dt><dd>
355 Specifies a filename that should not be compressed when using
357 This option can be provided multiple times to suppress compression
360 </dd><dt>Format zip</dt><dd>
362 <dt>'''compression'''</dt><dd>
367 to indicate how the following entries should be compressed.
368 Note that this setting is ignored for directories, symbolic links,
369 and other special entries.
370 </dd><dt>'''experimental'''</dt><dd>
371 This boolean option enables or disables experimental Zip features
372 that may not be compatible with other Zip implementations.
373 </dd><dt>'''fakecrc32'''</dt><dd>
374 This boolean option disables CRC calculations.
375 All CRC fields are set to zero.
376 It should not be used except for testing purposes.
377 </dd><dt>'''hdrcharset'''</dt><dd>
378 This sets the character set used for filenames.
379 </dd><dt>'''zip64'''</dt><dd>
380 Zip64 extensions provide additional file size information
381 for entries larger than 4 GiB.
382 They also provide extended file offset and archive size information
383 when archives exceed 4 GiB.
384 By default, the Zip writer selectively enables these extensions only as needed.
385 In particular, if the file size is unknown, the Zip writer will
386 include Zip64 extensions to guard against the possibility that the
387 file might be larger than 4 GiB.
389 Setting this boolean option will force the writer to use Zip64 extensions
390 even for small files that would not otherwise require them.
391 This is primarily useful for testing.
393 Disabling this option with
395 will force the Zip writer to avoid Zip64 extensions:
396 It will reject files with size greater than 4 GiB,
397 it will reject any new entries once the total archive size reaches 4 GiB,
398 and it will not use Zip64 extensions for files with unknown size.
399 In particular, this can improve compatibility when generating archives
400 where the entry sizes are not known in advance.
404 The following example creates an archive write handle to
405 create a gzip-compressed ISO9660 format image.
406 The two options here specify that the ISO9660 archive will use
408 as the boot image for El Torito booting, and that the gzip
409 compressor should use the maximum compression level.
411 a = archive_write_new();
412 archive_write_add_filter_gzip(a);
413 archive_write_set_format_iso9660(a);
414 archive_write_set_options(a, "boot=kernel.img,compression=9");
415 archive_write_open_filename(a, filename, blocksize);
418 More detailed error codes and textual descriptions are available from the
419 '''archive_errno'''()
421 '''archive_error_string'''()
425 [[ManPageibarchive3]],
426 [[ManPagerchiveeadetptions3]],
427 [[ManPagerchiverite3]]
431 library first appeared in
434 The options support for libarchive was originally implemented by