1 .\" Copyright (c) 2003-2010 Tim Kientzle
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .Dt ARCHIVE_WRITE_OPTIONS 3
31 .Nm archive_write_set_filter_option ,
32 .Nm archive_write_set_format_option ,
33 .Nm archive_write_set_option ,
34 .Nm archive_write_set_options
35 .Nd functions controlling options for writing archives
37 Streaming Archive Library (libarchive, -larchive)
40 .Fo archive_write_set_filter_option
41 .Fa "struct archive *"
42 .Fa "const char *module"
43 .Fa "const char *option"
44 .Fa "const char *value"
47 .Fo archive_write_set_format_option
48 .Fa "struct archive *"
49 .Fa "const char *module"
50 .Fa "const char *option"
51 .Fa "const char *value"
54 .Fo archive_write_set_option
55 .Fa "struct archive *"
56 .Fa "const char *module"
57 .Fa "const char *option"
58 .Fa "const char *value"
61 .Fo archive_write_set_options
62 .Fa "struct archive *"
63 .Fa "const char *options"
66 These functions provide a way for libarchive clients to configure
67 specific write modules.
68 .Bl -tag -width indent
70 .Fn archive_write_set_filter_option ,
71 .Fn archive_write_set_format_option
73 Specifies an option that will be passed to currently-registered
74 filters (including decompression filters) or format readers.
82 these functions will do nothing and
91 is not, these functions will do nothing and
102 will be provided to the filter or reader named
104 The return value will be either
106 if the option was successfully handled or
108 if the option was unrecognized by the module or could otherwise
110 If there is no such module,
121 will be provided to every registered module.
122 If any module returns
124 this value will be returned immediately.
127 will be returned if any module accepts the option, and
131 .It Fn archive_write_set_option
133 .Fn archive_write_set_format_option ,
135 .Fn archive_write_set_filter_option .
136 If either function returns
141 Otherwise, greater of the two values will be returned.
143 .It Fn archive_write_set_options
145 is a comma-separated list of options.
152 will be returned immediately.
154 Individual options have one of the following forms:
155 .Bl -tag -compact -width indent
157 The option/value pair will be provided to every module.
158 Modules that do not accept an option with this name will ignore it.
160 The option will be provided to every module with a value of
163 The option will be provided to every module with a NULL value.
164 .It Ar module:option=value , Ar module:option , Ar module:!option
165 As above, but the corresponding option and value will be provided
166 only to modules whose name matches
172 .Bl -tag -compact -width indent
174 .Bl -tag -compact -width indent
175 .It Cm compression-level
176 The value is interpreted as a decimal integer specifying the
177 gzip compression level.
180 .Bl -tag -compact -width indent
181 .It Cm compression-level
182 The value is interpreted as a decimal integer specifying the
186 .Bl -tag -compact -width indent
187 .It Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname
188 Enable a particular keyword in the mtree output.
189 Prefix with an exclamation mark to disable the corresponding keyword.
190 The default is equivalent to
191 .Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname .
193 Enables all of the above keywords.
195 Enables generation of
197 lines that specify default values for the following files and/or directories.
199 XXX needs explanation XXX
201 .It Format iso9660 - volume metadata
202 These options are used to set standard ISO9660 metadata.
203 .Bl -tag -compact -width indent
204 .It Cm abstract-file Ns = Ns Ar filename
205 The file with the specified name will be identified in the ISO9660 metadata
206 as holding the abstract for this volume. Default: none.
207 .It Cm application-id Ns = Ns Ar filename
208 The file with the specified name will be identified in the ISO9660 metadata
209 as holding the application identifier for this volume. Default: none.
210 .It Cm biblio-file Ns = Ns Ar filename
211 The file with the specified name will be identified in the ISO9660 metadata
212 as holding the bibliography for this volume. Default: none.
213 .It Cm copyright-file Ns = Ns Ar filename
214 The file with the specified name will be identified in the ISO9660 metadata
215 as holding the copyright for this volume. Default: none.
216 .It Cm publisher Ns = Ns Ar filename
217 The file with the specified name will be identified in the ISO9660 metadata
218 as holding the publisher information for this volume. Default: none.
219 .It Cm volume-id Ns = Ns Ar string
220 The specified string will be used as the Volume Identifier in the ISO9660 metadata.
221 It is limited to 32 bytes. Default: none.
223 .It Format iso9660 - boot support
224 These options are used to make an ISO9660 image that can be directly
225 booted on various systems.
226 .Bl -tag -compact -width indent
227 .It Cm boot Ns = Ns Ar filename
228 The file matching this name will be used as the El Torito boot image file.
229 .It Cm boot-catalog Ns = Ns Ar name
230 The name that will be used for the El Torito boot catalog.
233 .It Cm boot-info-table
234 The boot image file provided by the
235 .Cm boot Ns = Ns Ar filename
236 option will be edited with appropriate boot information in bytes 8 through 64.
238 .It Cm boot-load-seg Ns = Ns Ar hexadecimal-number
239 The load segment for a no-emulation boot image.
240 .It Cm boot-load-size Ns = Ns Ar decimal-number
241 The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image.
242 Some very old BIOSes can only load very small images, setting this
243 value to 4 will often allow such BIOSes to load the first part of
244 the boot image (which will then need to be intelligent enough to
245 load the rest of itself).
246 This should not be needed unless you are trying to support systems with very old BIOSes.
247 This defaults to the full size of the image.
248 .It Cm boot-type Ns = Ns Ar value
249 Specifies the boot semantics used by the El Torito boot image:
254 then the boot image is assumed to be a bootable floppy image.
259 then the boot image is assumed to be a bootable hard disk image.
264 the boot image is used without floppy or hard disk emulation.
265 If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then
268 otherwise the default is
271 .It Format iso9660 - filename and size extensions
272 Various extensions to the base ISO9660 format.
273 .Bl -tag -compact -width indent
275 If enabled, allows filenames to begin with a leading period.
276 If disabled, filenames that begin with a leading period will have
277 that period replaced by an underscore character in the standard ISO9660
279 This does not impact names stored in the Rockridge or Joliet extension area.
281 .It Cm allow-lowercase
282 If enabled, allows filenames to contain lowercase characters.
283 If disabled, filenames will be forced to uppercase.
284 This does not impact names stored in the Rockridge or Joliet extension area.
286 .It Cm allow-multidot
287 If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification.
288 If disabled, additional periods will be converted to underscore characters.
289 This does not impact names stored in the Rockridge or Joliet extension area.
292 If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification.
293 If disabled,trailing periods will be converted to underscore characters.
294 This does not impact names stored in the Rockridge or Joliet extension area.
296 .It Cm allow-pvd-lowercase
297 If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification.
298 If disabled, characters will be converted to uppercase ASCII.
300 .It Cm allow-sharp-tilde
301 If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification.
302 If disabled, such characters will be converted to underscore characters.
305 If enabled, version numbers will be included with files.
306 If disabled, version numbers will be suppressed, in violation of the ISO9660 standard.
307 This does not impact names stored in the Rockridge or Joliet extension area.
310 This enables support for file size and file name extensions in the
312 The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas.
313 .Bl -tag -compact -width indent
315 The most compliant form of ISO9660 image.
316 Filenames are limited to 8.3 uppercase format,
317 directory names are limited to 8 uppercase characters,
318 files are limited to 4 GiB,
319 the complete ISO9660 image cannot exceed 4 GiB.
321 Filenames are limited to 30 uppercase characters with a 30-character extension,
322 directory names are limited to 30 characters,
323 files are limited to 4 GiB.
327 except that files may exceed 4 GiB.
331 except that filenames may be up to 193 characters
332 and may include arbitrary 8-bit characters.
335 Microsoft's Joliet extensions store a completely separate set of directory information about each file.
336 In particular, this information includes Unicode filenames of up to 255 characters.
339 If enabled, libarchive will use directory relocation records to ensure that
340 no pathname exceeds the ISO9660 limit of 8 directory levels.
341 If disabled, no relocation will occur.
344 If enabled, libarchive will cause an error if there are more than
346 If disabled, there is no limit on the number of directories.
349 If enabled, 300 kiB of zero bytes will be appended to the end of the archive.
351 .It Cm relaxed-filenames
352 If enabled, all 7-bit ASCII characters are permitted in filenames
353 (except lowercase characters unless
356 This violates ISO9660 standards.
357 This does not impact names stored in the Rockridge or Joliet extension area.
360 The Rockridge extensions store an additional set of POSIX-style file
361 information with each file, including mtime, atime, ctime, permissions,
362 and long filenames with arbitrary 8-bit characters.
363 These extensions also support symbolic links and other POSIX file types.
366 .It Format iso9660 - zisofs support
367 The zisofs extensions permit each file to be independently compressed
368 using a gzip-compatible compression.
369 This can provide significant size savings, but requires the reading
370 system to have support for these extensions.
371 These extensions are disabled by default.
372 .Bl -tag -compact -width indent
373 .It Cm compression-level Ns = Ns number
374 The compression level used by the deflate compressor.
375 Ranges from 0 (least effort) to 9 (most effort).
381 Compress each file in the archive.
383 .Cm zisofs=indirect ,
384 this is handled entirely within libarchive and does not require a
386 For best results, libarchive tests each file and will store
387 the file uncompressed if the compression does not actually save any space.
388 In particular, files under 2k will never be compressed.
389 Note that boot image files are never compressed.
390 .It Cm zisofs=indirect
391 Recognizes files that have already been compressed with the
393 utility and sets up the necessary file metadata so that
394 readers will correctly identify these as zisofs-compressed files.
395 .It Cm zisofs-exclude Ns = Ns Ar filename
396 Specifies a filename that should not be compressed when using
398 This option can be provided multiple times to suppress compression
402 .Bl -tag -compact -width indent
408 to indicate how the following entries should be compressed.
409 Note that this setting is ignored for directories, symbolic links,
410 and other special entries.
412 This boolean option enables or disables experimental Zip features
413 that may not be compatible with other Zip implementations.
415 This boolean option disables CRC calculations.
416 All CRC fields are set to zero.
417 It should not be used except for testing purposes.
419 This sets the character set used for filenames.
421 Zip64 extensions provide additional file size information
422 for entries larger than 4 GiB.
423 They also provide extended file offset and archive size information
424 when archives exceed 4 GiB.
425 By default, the Zip writer selectively enables these extensions only as needed.
426 In particular, if the file size is unknown, the Zip writer will
427 include Zip64 extensions to guard against the possibility that the
428 file might be larger than 4 GiB.
430 Setting this boolean option will force the writer to use Zip64 extensions
431 even for small files that would not otherwise require them.
432 This is primarily useful for testing.
434 Disabling this option with
436 will force the Zip writer to avoid Zip64 extensions:
437 It will reject files with size greater than 4 GiB,
438 it will reject any new entries once the total archive size reaches 4 GiB,
439 and it will not use Zip64 extensions for files with unknown size.
440 In particular, this can improve compatibility when generating archives
441 where the entry sizes are not known in advance.
445 The following example creates an archive write handle to
446 create a gzip-compressed ISO9660 format image.
447 The two options here specify that the ISO9660 archive will use
449 as the boot image for El Torito booting, and that the gzip
450 compressor should use the maximum compression level.
451 .Bd -literal -offset indent
452 a = archive_write_new();
453 archive_write_add_filter_gzip(a);
454 archive_write_set_format_iso9660(a);
455 archive_write_set_options(a, "boot=kernel.img,compression=9");
456 archive_write_open_filename(a, filename, blocksize);
460 More detailed error codes and textual descriptions are available from the
463 .Fn archive_error_string
469 .Xr archive_read_set_options 3 ,
474 library first appeared in
478 The options support for libarchive was originally implemented by
479 .An Michihiro NAKAJIMA .