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 currently-registered
33 filters (including decompression filters) or format readers.
34 If option and value are both NULL, these functions will do noth‐
36 ing and ARCHIVE_OK will be returned. If option is NULL but value
37 is not, these functions will do nothing and ARCHIVE_FAILED will
38 be returned.
39 If module is not NULL, option and value will be provided to the
41 filter or reader named module. The return value will be either
42 ARCHIVE_OK if the option was successfully handled or ARCHIVE_WARN
43 if the option was unrecognized by the module or could otherwise
44 not be handled. If there is no such module, ARCHIVE_FAILED will
45 be returned.
46 If module is NULL, option and value will be provided to every
48 registered module. If any module returns ARCHIVE_FATAL, this
49 value will be returned immediately. Otherwise, ARCHIVE_OK will
50 be returned if any module accepts the option, and ARCHIVE_FAILED
51 in all other cases.
52 archive_write_set_option()
54 Calls archive_write_set_format_option(), then
55 archive_write_set_filter_option(). If either function returns
56 ARCHIVE_FATAL, ARCHIVE_FATAL will be returned immediately. Oth‐
57 erwise, greater of the two values will be returned.
58 archive_write_set_options()
60 options is a comma-separated list of options. If options is NULL
61 or empty, ARCHIVE_OK will be returned immediately.
62 Individual options have one of the following forms:
64 option=value
65 The option/value pair will be provided to every module.
66 Modules that do not accept an option with this name will
67 ignore it.
68 option The option will be provided to every module with a value
69 of “1”.
70 !option
71 The option will be provided to every module with a NULL
72 value.
73 module:option=value, module:option, module:!option
74 As above, but the corresponding option and value will be
75 provided only to modules whose name matches module.
76
78 Filter gzip
79 compression-level
80 The value is interpreted as a decimal integer specifying
81 the gzip compression level.
82 Filter xz
83 compression-level
84 The value is interpreted as a decimal integer specifying
85 the compression level.
86 Format mtree
87 cksum, device, flags, gid, gname, indent, link, md5, mode, nlink,
88 rmd160, sha1, sha256, sha384, sha512, size, time, uid,
89 uname
90 Enable a particular keyword in the mtree output. Prefix
91 with an exclamation mark to disable the corresponding
92 keyword. The default is equivalent to “device, flags,
93 gid, gname, link, mode, nlink, size, time, type, uid,
94 uname”.
95 all Enables all of the above keywords.
96 use-set
97 Enables generation of /set lines that specify default
98 values for the following files and/or directories.
99 indent XXX needs explanation XXX
100 Format iso9660 - volume metadata
101 These options are used to set standard ISO9660 metadata.
102 abstract-file=filename
103 The file with the specified name will be identified in
104 the ISO9660 metadata as holding the abstract for this
105 volume. Default: none.
106 application-id=filename
107 The file with the specified name will be identified in
108 the ISO9660 metadata as holding the application identi‐
109 fier for this volume. Default: none.
110 biblio-file=filename
111 The file with the specified name will be identified in
112 the ISO9660 metadata as holding the bibliography for this
113 volume. Default: none.
114 copyright-file=filename
115 The file with the specified name will be identified in
116 the ISO9660 metadata as holding the copyright for this
117 volume. Default: none.
118 publisher=filename
119 The file with the specified name will be identified in
120 the ISO9660 metadata as holding the publisher information
121 for this volume. Default: none.
122 volume-id=string
123 The specified string will be used as the Volume Identi‐
124 fier in the ISO9660 metadata. It is limited to 32 bytes.
125 Default: none.
126 Format iso9660 - boot support
127 These options are used to make an ISO9660 image that can be
128 directly booted on various systems.
129 boot=filename
130 The file matching this name will be used as the El Torito
131 boot image file.
132 boot-catalog=name
133 The name that will be used for the El Torito boot cata‐
134 log. Default: boot.catalog
135 boot-info-table
136 The boot image file provided by the boot=filename option
137 will be edited with appropriate boot information in bytes
138 8 through 64. Default: disabled
139 boot-load-seg=hexadecimal-number
140 The load segment for a no-emulation boot image.
141 boot-load-size=decimal-number
142 The number of "virtual" 512-byte sectors to be loaded
143 from a no-emulation boot image. Some very old BIOSes can
144 only load very small images, setting this value to 4 will
145 often allow such BIOSes to load the first part of the
146 boot image (which will then need to be intelligent enough
147 to load the rest of itself). This should not be needed
148 unless you are trying to support systems with very old
149 BIOSes. This defaults to the full size of the image.
150 boot-type=value
151 Specifies the boot semantics used by the El Torito boot
152 image: If the value is fd, then the boot image is assumed
153 to be a bootable floppy image. If the value is hd, then
154 the boot image is assumed to be a bootable hard disk
155 image. If the value is no-emulation, the boot image is
156 used without floppy or hard disk emulation. If the boot
157 image is exactly 1.2MB, 1.44MB, or 2.88MB, then the
158 default is fd, otherwise the default is no-emulation.
159 Format iso9660 - filename and size extensions
160 Various extensions to the base ISO9660 format.
161 allow-ldots
162 If enabled, allows filenames to begin with a leading
163 period. If disabled, filenames that begin with a leading
164 period will have that period replaced by an underscore
165 character in the standard ISO9660 namespace. This does
166 not impact names stored in the Rockridge or Joliet exten‐
167 sion area. Default: disabled.
168 allow-lowercase
169 If enabled, allows filenames to contain lowercase charac‐
170 ters. If disabled, filenames will be forced to upper‐
171 case. This does not impact names stored in the Rockridge
172 or Joliet extension area. Default: disabled.
173 allow-multidot
174 If enabled, allows filenames to contain multiple period
175 characters, in violation of the ISO9660 specification.
176 If disabled, additional periods will be converted to
177 underscore characters. This does not impact names stored
178 in the Rockridge or Joliet extension area. Default: dis‐
179 abled.
180 allow-period
181 If enabled, allows filenames to contain trailing period
182 characters, in violation of the ISO9660 specification.
183 If disabled,trailing periods will be converted to under‐
184 score characters. This does not impact names stored in
185 the Rockridge or Joliet extension area. Default: dis‐
186 abled.
187 allow-pvd-lowercase
188 If enabled, the Primary Volume Descriptor may contain
189 lowercase ASCII characters, in violation of the ISO9660
190 specification. If disabled, characters will be converted
191 to uppercase ASCII. Default: disabled.
192 allow-sharp-tilde
193 If enabled, sharp and tilde characters will be permitted
194 in filenames, in violation if the ISO9660 specification.
195 If disabled, such characters will be converted to under‐
196 score characters. Default: disabled.
197 allow-vernum
198 If enabled, version numbers will be included with files.
199 If disabled, version numbers will be suppressed, in vio‐
200 lation of the ISO9660 standard. This does not impact
201 names stored in the Rockridge or Joliet extension area.
202 Default: enabled.
203 iso-level
204 This enables support for file size and file name exten‐
205 sions in the core ISO9660 area. The name extensions
206 specified here do not affect the names stored in the
207 Rockridge or Joliet extension areas.
208 iso-level=1
209 The most compliant form of ISO9660 image. File‐
210 names are limited to 8.3 uppercase format, direc‐
211 tory names are limited to 8 uppercase characters,
212 files are limited to 4 GiB, the complete ISO9660
213 image cannot exceed 4 GiB.
214 iso-level=2
215 Filenames are limited to 30 uppercase characters
216 with a 30-character extension, directory names
217 are limited to 30 characters, files are limited
218 to 4 GiB.
219 iso-level=3
220 As with iso-level=2, except that files may exceed
221 4 GiB.
222 iso-level=4
223 As with iso-level=3, except that filenames may be
224 up to 193 characters and may include arbitrary
225 8-bit characters.
226 joliet Microsoft's Joliet extensions store a completely separate
227 set of directory information about each file. In partic‐
228 ular, this information includes Unicode filenames of up
229 to 255 characters. Default: enabled.
230 limit-depth
231 If enabled, libarchive will use directory relocation
232 records to ensure that no pathname exceeds the ISO9660
233 limit of 8 directory levels. If disabled, no relocation
234 will occur. Default: enabled.
235 limit-dirs
236 If enabled, libarchive will cause an error if there are
237 more than 65536 directories. If disabled, there is no
238 limit on the number of directories. Default: enabled
239 pad If enabled, 300 kiB of zero bytes will be appended to the
240 end of the archive. Default: enabled
241 relaxed-filenames
242 If enabled, all 7-bit ASCII characters are permitted in
243 filenames (except lowercase characters unless
244 allow-lowercase is also specified). This violates
245 ISO9660 standards. This does not impact names stored in
246 the Rockridge or Joliet extension area. Default: dis‐
247 abled.
248 rockridge
249 The Rockridge extensions store an additional set of
250 POSIX-style file information with each file, including
251 mtime, atime, ctime, permissions, and long filenames with
252 arbitrary 8-bit characters. These extensions also sup‐
253 port symbolic links and other POSIX file types. Default:
254 enabled.
255 Format iso9660 - zisofs support
256 The zisofs extensions permit each file to be independently com‐
257 pressed using a gzip-compatible compression. This can provide
258 significant size savings, but requires the reading system to have
259 support for these extensions. These extensions are disabled by
260 default.
261 compression-level=number
262 The compression level used by the deflate compressor.
263 Ranges from 0 (least effort) to 9 (most effort).
264 Default: 6
265 zisofs Synonym for zisofs=direct.
266 zisofs=direct
267 Compress each file in the archive. Unlike
268 zisofs=indirect, this is handled entirely within
269 libarchive and does not require a separate utility. For
270 best results, libarchive tests each file and will store
271 the file uncompressed if the compression does not actu‐
272 ally save any space. In particular, files under 2k will
273 never be compressed. Note that boot image files are
274 never compressed.
275 zisofs=indirect
276 Recognizes files that have already been compressed with
277 the mkzftree utility and sets up the necessary file meta‐
278 data so that readers will correctly identify these as
279 zisofs-compressed files.
280 zisofs-exclude=filename
281 Specifies a filename that should not be compressed when
282 using zisofs=direct. This option can be provided multi‐
283 ple times to suppress compression on many files.
284 Format zip
285 compression
286 The value is either “store” or “deflate” to indicate how
287 the following entries should be compressed. Note that
288 this setting is ignored for directories, symbolic links,
289 and other special entries.
290 experimental
291 This boolean option enables or disables experimental Zip
292 features that may not be compatible with other Zip imple‐
293 mentations.
294 fakecrc32
295 This boolean option disables CRC calculations. All CRC
296 fields are set to zero. It should not be used except for
297 testing purposes.
298 hdrcharset
299 This sets the character set used for filenames.
300 zip64 Zip64 extensions provide additional file size information
301 for entries larger than 4 GiB. They also provide
302 extended file offset and archive size information when
303 archives exceed 4 GiB. By default, the Zip writer selec‐
304 tively enables these extensions only as needed. In par‐
305 ticular, if the file size is unknown, the Zip writer will
306 include Zip64 extensions to guard against the possibility
307 that the file might be larger than 4 GiB.
308 Setting this boolean option will force the writer to use
310 Zip64 extensions even for small files that would not oth‐
311 erwise require them. This is primarily useful for test‐
312 ing.
313 Disabling this option with !zip64 will force the Zip
315 writer to avoid Zip64 extensions: It will reject files
316 with size greater than 4 GiB, it will reject any new
317 entries once the total archive size reaches 4 GiB, and it
318 will not use Zip64 extensions for files with unknown
319 size. In particular, this can improve compatibility when
320 generating archives where the entry sizes are not known
321 in advance.
322
324 The following example creates an archive write handle to create a gzip-
325 compressed ISO9660 format image. The two options here specify that the
326 ISO9660 archive will use kernel.img as the boot image for El Torito boot‐
327 ing, and that the gzip compressor should use the maximum compression
328 level.
329 a = archive_write_new();
331 archive_write_add_filter_gzip(a);
332 archive_write_set_format_iso9660(a);
333 archive_write_set_options(a, "boot=kernel.img,compression=9");
334 archive_write_open_filename(a, filename, blocksize);
335
337 More detailed error codes and textual descriptions are available from the
338 archive_errno() and archive_error_string() functions.
339
341 tar(1), libarchive(3), archive_read_set_options(3), archive_write(3)
342
344 The libarchive library first appeared in FreeBSD 5.3.
345
347 The options support for libarchive was originally implemented by
348 Michihiro NAKAJIMA.
349
351BSD February 2, 2012 BSD