394 lines
14 KiB
Plaintext
394 lines
14 KiB
Plaintext
ARCHIVE_WRITE_OPTIONS(3) manual page
|
|
== NAME ==
|
|
'''archive_write_set_filter_option''',
|
|
'''archive_write_set_format_option''',
|
|
'''archive_write_set_option''',
|
|
'''archive_write_set_options'''
|
|
- functions controlling options for reading archives
|
|
== LIBRARY ==
|
|
Streaming Archive Library (libarchive, -larchive)
|
|
== SYNOPSIS ==
|
|
<br>
|
|
'''int'''
|
|
<br>
|
|
'''archive_write_set_filter_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
|
|
<br>
|
|
'''int'''
|
|
<br>
|
|
'''archive_write_set_format_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
|
|
<br>
|
|
'''int'''
|
|
<br>
|
|
'''archive_write_set_option'''(''struct archive *'', ''const char *module'', ''const char *option'', ''const char *value'');
|
|
<br>
|
|
'''int'''
|
|
<br>
|
|
'''archive_write_set_options'''(''struct archive *'', ''const char *options'');
|
|
== DESCRIPTION ==
|
|
These functions provide a way for libarchive clients to configure
|
|
specific write modules.
|
|
<dl>
|
|
<dt>
|
|
'''archive_write_set_filter_option'''(),
|
|
'''archive_write_set_format_option'''()
|
|
</dt> <dd>
|
|
Specifies an option that will be passed to currently-registered
|
|
filters (including decompression filters) or format readers.
|
|
|
|
If
|
|
''option''
|
|
and
|
|
''value''
|
|
are both
|
|
NULL,
|
|
these functions will do nothing and
|
|
'''ARCHIVE_OK'''
|
|
will be returned.
|
|
If
|
|
''option''
|
|
is
|
|
NULL
|
|
but
|
|
''value''
|
|
is not, these functions will do nothing and
|
|
'''ARCHIVE_FAILED'''
|
|
will be returned.
|
|
|
|
If
|
|
''module''
|
|
is not
|
|
NULL,
|
|
''option''
|
|
and
|
|
''value''
|
|
will be provided to the filter or reader named
|
|
''module''.
|
|
The return value will be that of the module.
|
|
If there is no such module,
|
|
'''ARCHIVE_FAILED'''
|
|
will be returned.
|
|
|
|
If
|
|
''module''
|
|
is
|
|
NULL,
|
|
''option''
|
|
and
|
|
''value''
|
|
will be provided to every registered module.
|
|
If any module returns
|
|
'''ARCHIVE_FATAL''',
|
|
this value will be returned immediately.
|
|
Otherwise,
|
|
'''ARCHIVE_OK'''
|
|
will be returned if any module accepts the option, and
|
|
'''ARCHIVE_FAILED'''
|
|
in all other cases.
|
|
</dd><dt>
|
|
'''archive_write_set_option'''()
|
|
</dt> <dd>
|
|
Calls
|
|
'''archive_write_set_format_option'''(),
|
|
then
|
|
'''archive_write_set_filter_option'''().
|
|
If either function returns
|
|
'''ARCHIVE_FATAL''',
|
|
'''ARCHIVE_FATAL'''
|
|
will be returned
|
|
immediately.
|
|
Otherwise, greater of the two values will be returned.
|
|
</dd><dt>
|
|
'''archive_write_set_options'''()
|
|
</dt> <dd>
|
|
''options''
|
|
is a comma-separated list of options.
|
|
If
|
|
''options''
|
|
is
|
|
NULL
|
|
or empty,
|
|
'''ARCHIVE_OK'''
|
|
will be returned immediately.
|
|
|
|
Individual options have one of the following forms:
|
|
<dl>
|
|
<dt>''option=value''</dt><dd>
|
|
The option/value pair will be provided to every module.
|
|
Modules that do not accept an option with this name will ignore it.
|
|
</dd><dt>''option''</dt><dd>
|
|
The option will be provided to every module with a value of
|
|
"1".
|
|
</dd><dt>''!option''</dt><dd>
|
|
The option will be provided to every module with a NULL value.
|
|
</dd><dt>''module:option=value'', ''module:option'', ''module:!option''</dt><dd>
|
|
As above, but the corresponding option and value will be provided
|
|
only to modules whose name matches
|
|
''module''.
|
|
</dd></dl>
|
|
</dd></dl>
|
|
== OPTIONS ==
|
|
<dl>
|
|
<dt>Filter gzip</dt><dd>
|
|
<dl>
|
|
<dt>'''compression-level'''</dt><dd>
|
|
The value is interpreted as a decimal integer specifying the
|
|
gzip compression level.
|
|
</dd></dl>
|
|
</dd><dt>Filter xz</dt><dd>
|
|
<dl>
|
|
<dt>'''compression-level'''</dt><dd>
|
|
The value is interpreted as a decimal integer specifying the
|
|
compression level.
|
|
</dd></dl>
|
|
</dd><dt>Format mtree</dt><dd>
|
|
<dl>
|
|
<dt>'''cksum''', '''device''', '''flags''', '''gid''', '''gname''', '''indent''', '''link''', '''md5''', '''mode''', '''nlink''', '''rmd160''', '''sha1''', '''sha256''', '''sha384''', '''sha512''', '''size''', '''time''', '''uid''', '''uname'''</dt><dd>
|
|
Enable a particular keyword in the mtree output.
|
|
Prefix with an exclamation mark to disable the corresponding keyword.
|
|
The default is equivalent to
|
|
"device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname".
|
|
</dd><dt>'''all'''</dt><dd>
|
|
Enables all of the above keywords.
|
|
</dd><dt>'''use-set'''</dt><dd>
|
|
Enables generation of
|
|
'''/set'''
|
|
lines that specify default values for the following files and/or directories.
|
|
</dd><dt>'''indent'''</dt><dd>
|
|
XXX needs explanation XXX
|
|
</dd></dl>
|
|
</dd><dt>Format iso9660 - volume metadata</dt><dd>
|
|
These options are used to set standard ISO9660 metadata.
|
|
<dl>
|
|
<dt>'''abstract-file'''=''filename''</dt><dd>
|
|
The file with the specified name will be identified in the ISO9660 metadata
|
|
as holding the abstract for this volume. Default: none.
|
|
</dd><dt>'''application-id'''=''filename''</dt><dd>
|
|
The file with the specified name will be identified in the ISO9660 metadata
|
|
as holding the application identifier for this volume. Default: none.
|
|
</dd><dt>'''biblio-file'''=''filename''</dt><dd>
|
|
The file with the specified name will be identified in the ISO9660 metadata
|
|
as holding the bibliography for this volume. Default: none.
|
|
</dd><dt>'''copyright-file'''=''filename''</dt><dd>
|
|
The file with the specified name will be identified in the ISO9660 metadata
|
|
as holding the copyright for this volume. Default: none.
|
|
</dd><dt>'''publisher'''=''filename''</dt><dd>
|
|
The file with the specified name will be identified in the ISO9660 metadata
|
|
as holding the publisher information for this volume. Default: none.
|
|
</dd><dt>'''volume-id'''=''string''</dt><dd>
|
|
The specified string will be used as the Volume Identifier in the ISO9660 metadata.
|
|
It is limited to 32 bytes. Default: none.
|
|
</dd></dl>
|
|
</dd><dt>Format iso9660 - boot support</dt><dd>
|
|
These options are used to make an ISO9660 image that can be directly
|
|
booted on various systems.
|
|
<dl>
|
|
<dt>'''boot'''=''filename''</dt><dd>
|
|
The file matching this name will be used as the El Torito boot image file.
|
|
</dd><dt>'''boot-catalog'''=''name''</dt><dd>
|
|
The name that will be used for the El Torito boot catalog.
|
|
Default:
|
|
''boot.catalog''
|
|
</dd><dt>'''boot-info-table'''</dt><dd>
|
|
The boot image file provided by the
|
|
'''boot'''=''filename''
|
|
option will be edited with appropriate boot information in bytes 8 through 64.
|
|
Default: disabled
|
|
</dd><dt>'''boot-load-seg'''=''hexadecimal-number''</dt><dd>
|
|
The load segment for a no-emulation boot image.
|
|
</dd><dt>'''boot-load-size'''=''decimal-number''</dt><dd>
|
|
The number of "virtual" 512-byte sectors to be loaded from a no-emulation boot image.
|
|
Some very old BIOSes can only load very small images, setting this
|
|
value to 4 will often allow such BIOSes to load the first part of
|
|
the boot image (which will then need to be intelligent enough to
|
|
load the rest of itself).
|
|
This should not be needed unless you are trying to support systems with very old BIOSes.
|
|
This defaults to the full size of the image.
|
|
</dd><dt>'''boot-type'''=''value''</dt><dd>
|
|
Specifies the boot semantics used by the El Torito boot image:
|
|
If the
|
|
''value''
|
|
is
|
|
'''fd''',
|
|
then the boot image is assumed to be a bootable floppy image.
|
|
If the
|
|
''value''
|
|
is
|
|
'''hd''',
|
|
then the the boot image is assumed to be a bootable hard disk image.
|
|
If the
|
|
''value''
|
|
is
|
|
'''no-emulation''',
|
|
the boot image is used without floppy or hard disk emulation.
|
|
If the boot image is exactly 1.2MB, 1.44MB, or 2.88MB, then
|
|
the default is
|
|
'''fd''',
|
|
otherwise the default is
|
|
'''no-emulation.'''
|
|
</dd></dl>
|
|
</dd><dt>Format iso9660 - filename and size extensions</dt><dd>
|
|
Various extensions to the base ISO9660 format.
|
|
<dl>
|
|
<dt>'''allow-ldots'''</dt><dd>
|
|
If enabled, allows filenames to begin with a leading period.
|
|
If disabled, filenames that begin with a leading period will have
|
|
that period replaced by an underscore character in the standard ISO9660
|
|
namespace.
|
|
This does not impact names stored in the Rockridge or Joliet extension area.
|
|
Default: disabled.
|
|
</dd><dt>'''allow-lowercase'''</dt><dd>
|
|
If enabled, allows filenames to contain lowercase characters.
|
|
If disabled, filenames will be forced to uppercase.
|
|
This does not impact names stored in the Rockridge or Joliet extension area.
|
|
Default: disabled.
|
|
</dd><dt>'''allow-multidot'''</dt><dd>
|
|
If enabled, allows filenames to contain multiple period characters, in violation of the ISO9660 specification.
|
|
If disabled, additional periods will be converted to underscore characters.
|
|
This does not impact names stored in the Rockridge or Joliet extension area.
|
|
Default: disabled.
|
|
</dd><dt>'''allow-period'''</dt><dd>
|
|
If enabled, allows filenames to contain trailing period characters, in violation of the ISO9660 specification.
|
|
If disabled,trailing periods will be converted to underscore characters.
|
|
This does not impact names stored in the Rockridge or Joliet extension area.
|
|
Default: disabled.
|
|
</dd><dt>'''allow-pvd-lowercase'''</dt><dd>
|
|
If enabled, the Primary Volume Descriptor may contain lowercase ASCII characters, in violation of the ISO9660 specification.
|
|
If disabled, characters will be converted to uppercase ASCII.
|
|
Default: disabled.
|
|
</dd><dt>'''allow-sharp-tilde'''</dt><dd>
|
|
If enabled, sharp and tilde characters will be permitted in filenames, in violation if the ISO9660 specification.
|
|
If disabled, such characters will be converted to underscore characters.
|
|
Default: disabled.
|
|
</dd><dt>'''allow-vernum'''</dt><dd>
|
|
If enabled, version numbers will be included with files.
|
|
If disabled, version numbers will be suppressed, in violation of the ISO9660 standard.
|
|
This does not impact names stored in the Rockridge or Joliet extension area.
|
|
Default: enabled.
|
|
</dd><dt>'''iso-level'''</dt><dd>
|
|
This enables support for file size and file name extensions in the
|
|
core ISO9660 area.
|
|
The name extensions specified here do not affect the names stored in the Rockridge or Joliet extension areas.
|
|
<dl>
|
|
<dt>'''iso-level=1'''</dt><dd>
|
|
The most compliant form of ISO9660 image.
|
|
Filenames are limited to 8.3 uppercase format,
|
|
directory names are limited to 8 uppercase characters,
|
|
files are limited to 4 GiB,
|
|
the complete ISO9660 image cannot exceed 4 GiB.
|
|
</dd><dt>'''iso-level=2'''</dt><dd>
|
|
Filenames are limited to 30 uppercase characters with a 30-character extension,
|
|
directory names are limited to 30 characters,
|
|
files are limited to 4 GiB.
|
|
</dd><dt>'''iso-level=3'''</dt><dd>
|
|
As with
|
|
'''iso-level=2''',
|
|
except that files may exceed 4 GiB.
|
|
</dd><dt>'''iso-level=4'''</dt><dd>
|
|
As with
|
|
'''iso-level=3''',
|
|
except that filenames may be up to 193 characters
|
|
and may include arbitrary 8-bit characters.
|
|
</dd></dl>
|
|
</dd><dt>'''joliet'''</dt><dd>
|
|
Microsoft's Joliet extensions store a completely separate set of directory information about each file.
|
|
In particular, this information includes Unicode filenames of up to 255 characters.
|
|
Default: enabled.
|
|
</dd><dt>'''limit-depth'''</dt><dd>
|
|
If enabled, libarchive will use directory relocation records to ensure that
|
|
no pathname exceeds the ISO9660 limit of 8 directory levels.
|
|
If disabled, no relocation will occur.
|
|
Default: enabled.
|
|
</dd><dt>'''limit-dirs'''</dt><dd>
|
|
If enabled, libarchive will cause an error if there are more than
|
|
65536 directories.
|
|
If disabled, there is no limit on the number of directories.
|
|
Default: enabled
|
|
</dd><dt>'''pad'''</dt><dd>
|
|
If enabled, 300 kiB of zero bytes will be appended to the end of the archive.
|
|
Default: enabled
|
|
</dd><dt>'''relaxed-filenames'''</dt><dd>
|
|
If enabled, all 7-bit ASCII characters are permitted in filenames
|
|
(except lowercase characters unless
|
|
'''allow-lowercase'''
|
|
is also specified).
|
|
This violates ISO9660 standards.
|
|
This does not impact names stored in the Rockridge or Joliet extension area.
|
|
Default: disabled.
|
|
</dd><dt>'''rockridge'''</dt><dd>
|
|
The Rockridge extensions store an additional set of POSIX-style file
|
|
information with each file, including mtime, atime, ctime, permissions,
|
|
and long filenames with arbitrary 8-bit characters.
|
|
These extensions also support symbolic links and other POSIX file types.
|
|
Default: enabled.
|
|
</dd></dl>
|
|
</dd><dt>Format iso9660 - zisofs support</dt><dd>
|
|
The zisofs extensions permit each file to be independently compressed
|
|
using a gzip-compatible compression.
|
|
This can provide significant size savings, but requires the reading
|
|
system to have support for these extensions.
|
|
These extensions are disabled by default.
|
|
<dl>
|
|
<dt>'''compression-level'''=number</dt><dd>
|
|
The compression level used by the deflate compressor.
|
|
Ranges from 0 (least effort) to 9 (most effort).
|
|
Default: 6
|
|
</dd><dt>'''zisofs'''</dt><dd>
|
|
Synonym for
|
|
'''zisofs=direct'''.
|
|
</dd><dt>'''zisofs=direct'''</dt><dd>
|
|
Compress each file in the archive.
|
|
Unlike
|
|
'''zisofs=indirect''',
|
|
this is handled entirely within libarchive and does not require a
|
|
separate utility.
|
|
For best results, libarchive tests each file and will store
|
|
the file uncompressed if the compression does not actually save any space.
|
|
In particular, files under 2k will never be compressed.
|
|
Note that boot image files are never compressed.
|
|
</dd><dt>'''zisofs=indirect'''</dt><dd>
|
|
Recognizes files that have already been compressed with the
|
|
'''mkzftree'''
|
|
utility and sets up the necessary file metadata so that
|
|
readers will correctly identify these as zisofs-compressed files.
|
|
</dd><dt>'''zisofs-exclude'''=''filename''</dt><dd>
|
|
Specifies a filename that should not be compressed when using
|
|
'''zisofs=direct'''.
|
|
This option can be provided multiple times to suppress compression
|
|
on many files.
|
|
</dd></dl>
|
|
</dd></dl>
|
|
== EXAMPLES ==
|
|
The following example creates an archive write handle to
|
|
create a gzip-compressed ISO9660 format image.
|
|
The two options here specify that the ISO9660 archive will use
|
|
''kernel.img''
|
|
as the boot image for El Torito booting, and that the gzip
|
|
compressor should use the maximum compression level.
|
|
```text
|
|
a = archive_write_new();
|
|
archive_write_add_filter_gzip(a);
|
|
archive_write_set_format_iso9660(a);
|
|
archive_write_set_options(a, "boot=kernel.img,compression=9");
|
|
archive_write_open_filename(a, filename, blocksize);
|
|
```
|
|
== ERRORS ==
|
|
Detailed error codes and textual descriptions are available from the
|
|
'''archive_errno'''()
|
|
and
|
|
'''archive_error_string'''()
|
|
functions.
|
|
== SEE ALSO ==
|
|
'''tar'''(1),
|
|
'''libarchive'''(3),
|
|
'''archive_read_set_options'''(3),
|
|
'''archive_write'''(3)
|
|
== HISTORY ==
|
|
The
|
|
'''libarchive'''
|
|
library first appeared in
|
|
FreeBSD 5.3.
|
|
== AUTHORS ==
|
|
The options support for libarchive was originally implemented by
|
|
Michihiro NAKAJIMA.
|
|
== BUGS ==
|