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