Blame doc/text/archive_write_set_options.3.txt

Packit Service 1d0348
ARCHIVE_WRITE_OPTIONS(3) BSD Library Functions Manual ARCHIVE_WRITE_OPTIONS(3)
Packit Service 1d0348
Packit Service 1d0348
NAME
Packit Service 1d0348
     archive_write_set_filter_option, archive_write_set_format_option,
Packit Service 1d0348
     archive_write_set_option, archive_write_set_options — functions control‐
Packit Service 1d0348
     ling options for writing archives
Packit Service 1d0348
Packit Service 1d0348
LIBRARY
Packit Service 1d0348
     Streaming Archive Library (libarchive, -larchive)
Packit Service 1d0348
Packit Service 1d0348
SYNOPSIS
Packit Service 1d0348
     int
Packit Service 1d0348
     archive_write_set_filter_option(struct archive *, const char *module,
Packit Service 1d0348
	 const char *option, const char *value);
Packit Service 1d0348
Packit Service 1d0348
     int
Packit Service 1d0348
     archive_write_set_format_option(struct archive *, const char *module,
Packit Service 1d0348
	 const char *option, const char *value);
Packit Service 1d0348
Packit Service 1d0348
     int
Packit Service 1d0348
     archive_write_set_option(struct archive *, const char *module,
Packit Service 1d0348
	 const char *option, const char *value);
Packit Service 1d0348
Packit Service 1d0348
     int
Packit Service 1d0348
     archive_write_set_options(struct archive *, const char *options);
Packit Service 1d0348
Packit Service 1d0348
DESCRIPTION
Packit Service 1d0348
     These functions provide a way for libarchive clients to configure spe‐
Packit Service 1d0348
     cific write modules.
Packit Service 1d0348
Packit Service 1d0348
     archive_write_set_filter_option(), archive_write_set_format_option()
Packit Service 1d0348
	     Specifies an option that will be passed to currently-registered
Packit Service 1d0348
	     filters (including decompression filters) or format readers.
Packit Service 1d0348
Packit Service 1d0348
	     If option and value are both NULL, these functions will do noth‐
Packit Service 1d0348
	     ing and ARCHIVE_OK will be returned.  If option is NULL but value
Packit Service 1d0348
	     is not, these functions will do nothing and ARCHIVE_FAILED will
Packit Service 1d0348
	     be returned.
Packit Service 1d0348
Packit Service 1d0348
	     If module is not NULL, option and value will be provided to the
Packit Service 1d0348
	     filter or reader named module.  The return value will be either
Packit Service 1d0348
	     ARCHIVE_OK if the option was successfully handled or ARCHIVE_WARN
Packit Service 1d0348
	     if the option was unrecognized by the module or could otherwise
Packit Service 1d0348
	     not be handled.  If there is no such module, ARCHIVE_FAILED will
Packit Service 1d0348
	     be returned.
Packit Service 1d0348
Packit Service 1d0348
	     If module is NULL, option and value will be provided to every
Packit Service 1d0348
	     registered module.  If any module returns ARCHIVE_FATAL, this
Packit Service 1d0348
	     value will be returned immediately.  Otherwise, ARCHIVE_OK will
Packit Service 1d0348
	     be returned if any module accepts the option, and ARCHIVE_FAILED
Packit Service 1d0348
	     in all other cases.
Packit Service 1d0348
Packit Service 1d0348
     archive_write_set_option()
Packit Service 1d0348
	     Calls archive_write_set_format_option(), then
Packit Service 1d0348
	     archive_write_set_filter_option().  If either function returns
Packit Service 1d0348
	     ARCHIVE_FATAL, ARCHIVE_FATAL will be returned immediately.  Oth‐
Packit Service 1d0348
	     erwise, greater of the two values will be returned.
Packit Service 1d0348
Packit Service 1d0348
     archive_write_set_options()
Packit Service 1d0348
	     options is a comma-separated list of options.  If options is NULL
Packit Service 1d0348
	     or empty, ARCHIVE_OK will be returned immediately.
Packit Service 1d0348
Packit Service 1d0348
	     Individual options have one of the following forms:
Packit Service 1d0348
	     option=value
Packit Service 1d0348
		     The option/value pair will be provided to every module.
Packit Service 1d0348
		     Modules that do not accept an option with this name will
Packit Service 1d0348
		     ignore it.
Packit Service 1d0348
	     option  The option will be provided to every module with a value
Packit Service 1d0348
		     of “1”.
Packit Service 1d0348
	     !option
Packit Service 1d0348
		     The option will be provided to every module with a NULL
Packit Service 1d0348
		     value.
Packit Service 1d0348
	     module:option=value, module:option, module:!option
Packit Service 1d0348
		     As above, but the corresponding option and value will be
Packit Service 1d0348
		     provided only to modules whose name matches module.
Packit Service 1d0348
Packit Service 1d0348
OPTIONS
Packit Service 1d0348
     Filter gzip
Packit Service 1d0348
	     compression-level
Packit Service 1d0348
		     The value is interpreted as a decimal integer specifying
Packit Service 1d0348
		     the gzip compression level.
Packit Service 1d0348
     Filter xz
Packit Service 1d0348
	     compression-level
Packit Service 1d0348
		     The value is interpreted as a decimal integer specifying
Packit Service 1d0348
		     the compression level.
Packit Service 1d0348
     Format mtree
Packit Service 1d0348
	     cksum, device, flags, gid, gname, indent, link, md5, mode, nlink,
Packit Service 1d0348
		     rmd160, sha1, sha256, sha384, sha512, size, time, uid,
Packit Service 1d0348
		     uname
Packit Service 1d0348
		     Enable a particular keyword in the mtree output.  Prefix
Packit Service 1d0348
		     with an exclamation mark to disable the corresponding
Packit Service 1d0348
		     keyword.  The default is equivalent to “device, flags,
Packit Service 1d0348
		     gid, gname, link, mode, nlink, size, time, type, uid,
Packit Service 1d0348
		     uname”.
Packit Service 1d0348
	     all     Enables all of the above keywords.
Packit Service 1d0348
	     use-set
Packit Service 1d0348
		     Enables generation of /set lines that specify default
Packit Service 1d0348
		     values for the following files and/or directories.
Packit Service 1d0348
	     indent  XXX needs explanation XXX
Packit Service 1d0348
     Format iso9660 - volume metadata
Packit Service 1d0348
	     These options are used to set standard ISO9660 metadata.
Packit Service 1d0348
	     abstract-file=filename
Packit Service 1d0348
		     The file with the specified name will be identified in
Packit Service 1d0348
		     the ISO9660 metadata as holding the abstract for this
Packit Service 1d0348
		     volume.  Default: none.
Packit Service 1d0348
	     application-id=filename
Packit Service 1d0348
		     The file with the specified name will be identified in
Packit Service 1d0348
		     the ISO9660 metadata as holding the application identi‐
Packit Service 1d0348
		     fier for this volume.  Default: none.
Packit Service 1d0348
	     biblio-file=filename
Packit Service 1d0348
		     The file with the specified name will be identified in
Packit Service 1d0348
		     the ISO9660 metadata as holding the bibliography for this
Packit Service 1d0348
		     volume.  Default: none.
Packit Service 1d0348
	     copyright-file=filename
Packit Service 1d0348
		     The file with the specified name will be identified in
Packit Service 1d0348
		     the ISO9660 metadata as holding the copyright for this
Packit Service 1d0348
		     volume.  Default: none.
Packit Service 1d0348
	     publisher=filename
Packit Service 1d0348
		     The file with the specified name will be identified in
Packit Service 1d0348
		     the ISO9660 metadata as holding the publisher information
Packit Service 1d0348
		     for this volume.  Default: none.
Packit Service 1d0348
	     volume-id=string
Packit Service 1d0348
		     The specified string will be used as the Volume Identi‐
Packit Service 1d0348
		     fier in the ISO9660 metadata.  It is limited to 32 bytes.
Packit Service 1d0348
		     Default: none.
Packit Service 1d0348
     Format iso9660 - boot support
Packit Service 1d0348
	     These options are used to make an ISO9660 image that can be
Packit Service 1d0348
	     directly booted on various systems.
Packit Service 1d0348
	     boot=filename
Packit Service 1d0348
		     The file matching this name will be used as the El Torito
Packit Service 1d0348
		     boot image file.
Packit Service 1d0348
	     boot-catalog=name
Packit Service 1d0348
		     The name that will be used for the El Torito boot cata‐
Packit Service 1d0348
		     log.  Default: boot.catalog
Packit Service 1d0348
	     boot-info-table
Packit Service 1d0348
		     The boot image file provided by the boot=filename option
Packit Service 1d0348
		     will be edited with appropriate boot information in bytes
Packit Service 1d0348
		     8 through 64.  Default: disabled
Packit Service 1d0348
	     boot-load-seg=hexadecimal-number
Packit Service 1d0348
		     The load segment for a no-emulation boot image.
Packit Service 1d0348
	     boot-load-size=decimal-number
Packit Service 1d0348
		     The number of "virtual" 512-byte sectors to be loaded
Packit Service 1d0348
		     from a no-emulation boot image.  Some very old BIOSes can
Packit Service 1d0348
		     only load very small images, setting this value to 4 will
Packit Service 1d0348
		     often allow such BIOSes to load the first part of the
Packit Service 1d0348
		     boot image (which will then need to be intelligent enough
Packit Service 1d0348
		     to load the rest of itself).  This should not be needed
Packit Service 1d0348
		     unless you are trying to support systems with very old
Packit Service 1d0348
		     BIOSes.  This defaults to the full size of the image.
Packit Service 1d0348
	     boot-type=value
Packit Service 1d0348
		     Specifies the boot semantics used by the El Torito boot
Packit Service 1d0348
		     image: If the value is fd, then the boot image is assumed
Packit Service 1d0348
		     to be a bootable floppy image.  If the value is hd, then
Packit Service 1d0348
		     the boot image is assumed to be a bootable hard disk
Packit Service 1d0348
		     image.  If the value is no-emulation, the boot image is
Packit Service 1d0348
		     used without floppy or hard disk emulation.  If the boot
Packit Service 1d0348
		     image is exactly 1.2MB, 1.44MB, or 2.88MB, then the
Packit Service 1d0348
		     default is fd, otherwise the default is no-emulation.
Packit Service 1d0348
     Format iso9660 - filename and size extensions
Packit Service 1d0348
	     Various extensions to the base ISO9660 format.
Packit Service 1d0348
	     allow-ldots
Packit Service 1d0348
		     If enabled, allows filenames to begin with a leading
Packit Service 1d0348
		     period.  If disabled, filenames that begin with a leading
Packit Service 1d0348
		     period will have that period replaced by an underscore
Packit Service 1d0348
		     character in the standard ISO9660 namespace.  This does
Packit Service 1d0348
		     not impact names stored in the Rockridge or Joliet exten‐
Packit Service 1d0348
		     sion area.  Default: disabled.
Packit Service 1d0348
	     allow-lowercase
Packit Service 1d0348
		     If enabled, allows filenames to contain lowercase charac‐
Packit Service 1d0348
		     ters.  If disabled, filenames will be forced to upper‐
Packit Service 1d0348
		     case.  This does not impact names stored in the Rockridge
Packit Service 1d0348
		     or Joliet extension area.	Default: disabled.
Packit Service 1d0348
	     allow-multidot
Packit Service 1d0348
		     If enabled, allows filenames to contain multiple period
Packit Service 1d0348
		     characters, in violation of the ISO9660 specification.
Packit Service 1d0348
		     If disabled, additional periods will be converted to
Packit Service 1d0348
		     underscore characters.  This does not impact names stored
Packit Service 1d0348
		     in the Rockridge or Joliet extension area.  Default: dis‐
Packit Service 1d0348
		     abled.
Packit Service 1d0348
	     allow-period
Packit Service 1d0348
		     If enabled, allows filenames to contain trailing period
Packit Service 1d0348
		     characters, in violation of the ISO9660 specification.
Packit Service 1d0348
		     If disabled,trailing periods will be converted to under‐
Packit Service 1d0348
		     score characters.	This does not impact names stored in
Packit Service 1d0348
		     the Rockridge or Joliet extension area.  Default: dis‐
Packit Service 1d0348
		     abled.
Packit Service 1d0348
	     allow-pvd-lowercase
Packit Service 1d0348
		     If enabled, the Primary Volume Descriptor may contain
Packit Service 1d0348
		     lowercase ASCII characters, in violation of the ISO9660
Packit Service 1d0348
		     specification.  If disabled, characters will be converted
Packit Service 1d0348
		     to uppercase ASCII.  Default: disabled.
Packit Service 1d0348
	     allow-sharp-tilde
Packit Service 1d0348
		     If enabled, sharp and tilde characters will be permitted
Packit Service 1d0348
		     in filenames, in violation if the ISO9660 specification.
Packit Service 1d0348
		     If disabled, such characters will be converted to under‐
Packit Service 1d0348
		     score characters.	Default: disabled.
Packit Service 1d0348
	     allow-vernum
Packit Service 1d0348
		     If enabled, version numbers will be included with files.
Packit Service 1d0348
		     If disabled, version numbers will be suppressed, in vio‐
Packit Service 1d0348
		     lation of the ISO9660 standard.  This does not impact
Packit Service 1d0348
		     names stored in the Rockridge or Joliet extension area.
Packit Service 1d0348
		     Default: enabled.
Packit Service 1d0348
	     iso-level
Packit Service 1d0348
		     This enables support for file size and file name exten‐
Packit Service 1d0348
		     sions in the core ISO9660 area.  The name extensions
Packit Service 1d0348
		     specified here do not affect the names stored in the
Packit Service 1d0348
		     Rockridge or Joliet extension areas.
Packit Service 1d0348
		     iso-level=1
Packit Service 1d0348
			     The most compliant form of ISO9660 image.	File‐
Packit Service 1d0348
			     names are limited to 8.3 uppercase format, direc‐
Packit Service 1d0348
			     tory names are limited to 8 uppercase characters,
Packit Service 1d0348
			     files are limited to 4 GiB, the complete ISO9660
Packit Service 1d0348
			     image cannot exceed 4 GiB.
Packit Service 1d0348
		     iso-level=2
Packit Service 1d0348
			     Filenames are limited to 30 uppercase characters
Packit Service 1d0348
			     with a 30-character extension, directory names
Packit Service 1d0348
			     are limited to 30 characters, files are limited
Packit Service 1d0348
			     to 4 GiB.
Packit Service 1d0348
		     iso-level=3
Packit Service 1d0348
			     As with iso-level=2, except that files may exceed
Packit Service 1d0348
			     4 GiB.
Packit Service 1d0348
		     iso-level=4
Packit Service 1d0348
			     As with iso-level=3, except that filenames may be
Packit Service 1d0348
			     up to 193 characters and may include arbitrary
Packit Service 1d0348
			     8-bit characters.
Packit Service 1d0348
	     joliet  Microsoft's Joliet extensions store a completely separate
Packit Service 1d0348
		     set of directory information about each file.  In partic‐
Packit Service 1d0348
		     ular, this information includes Unicode filenames of up
Packit Service 1d0348
		     to 255 characters.  Default: enabled.
Packit Service 1d0348
	     limit-depth
Packit Service 1d0348
		     If enabled, libarchive will use directory relocation
Packit Service 1d0348
		     records to ensure that no pathname exceeds the ISO9660
Packit Service 1d0348
		     limit of 8 directory levels.  If disabled, no relocation
Packit Service 1d0348
		     will occur.  Default: enabled.
Packit Service 1d0348
	     limit-dirs
Packit Service 1d0348
		     If enabled, libarchive will cause an error if there are
Packit Service 1d0348
		     more than 65536 directories.  If disabled, there is no
Packit Service 1d0348
		     limit on the number of directories.  Default: enabled
Packit Service 1d0348
	     pad     If enabled, 300 kiB of zero bytes will be appended to the
Packit Service 1d0348
		     end of the archive.  Default: enabled
Packit Service 1d0348
	     relaxed-filenames
Packit Service 1d0348
		     If enabled, all 7-bit ASCII characters are permitted in
Packit Service 1d0348
		     filenames (except lowercase characters unless
Packit Service 1d0348
		     allow-lowercase is also specified).  This violates
Packit Service 1d0348
		     ISO9660 standards.  This does not impact names stored in
Packit Service 1d0348
		     the Rockridge or Joliet extension area.  Default: dis‐
Packit Service 1d0348
		     abled.
Packit Service 1d0348
	     rockridge
Packit Service 1d0348
		     The Rockridge extensions store an additional set of
Packit Service 1d0348
		     POSIX-style file information with each file, including
Packit Service 1d0348
		     mtime, atime, ctime, permissions, and long filenames with
Packit Service 1d0348
		     arbitrary 8-bit characters.  These extensions also sup‐
Packit Service 1d0348
		     port symbolic links and other POSIX file types.  Default:
Packit Service 1d0348
		     enabled.
Packit Service 1d0348
     Format iso9660 - zisofs support
Packit Service 1d0348
	     The zisofs extensions permit each file to be independently com‐
Packit Service 1d0348
	     pressed using a gzip-compatible compression.  This can provide
Packit Service 1d0348
	     significant size savings, but requires the reading system to have
Packit Service 1d0348
	     support for these extensions.  These extensions are disabled by
Packit Service 1d0348
	     default.
Packit Service 1d0348
	     compression-level=number
Packit Service 1d0348
		     The compression level used by the deflate compressor.
Packit Service 1d0348
		     Ranges from 0 (least effort) to 9 (most effort).
Packit Service 1d0348
		     Default: 6
Packit Service 1d0348
	     zisofs  Synonym for zisofs=direct.
Packit Service 1d0348
	     zisofs=direct
Packit Service 1d0348
		     Compress each file in the archive.  Unlike
Packit Service 1d0348
		     zisofs=indirect, this is handled entirely within
Packit Service 1d0348
		     libarchive and does not require a separate utility.  For
Packit Service 1d0348
		     best results, libarchive tests each file and will store
Packit Service 1d0348
		     the file uncompressed if the compression does not actu‐
Packit Service 1d0348
		     ally save any space.  In particular, files under 2k will
Packit Service 1d0348
		     never be compressed.  Note that boot image files are
Packit Service 1d0348
		     never compressed.
Packit Service 1d0348
	     zisofs=indirect
Packit Service 1d0348
		     Recognizes files that have already been compressed with
Packit Service 1d0348
		     the mkzftree utility and sets up the necessary file meta‐
Packit Service 1d0348
		     data so that readers will correctly identify these as
Packit Service 1d0348
		     zisofs-compressed files.
Packit Service 1d0348
	     zisofs-exclude=filename
Packit Service 1d0348
		     Specifies a filename that should not be compressed when
Packit Service 1d0348
		     using zisofs=direct.  This option can be provided multi‐
Packit Service 1d0348
		     ple times to suppress compression on many files.
Packit Service 1d0348
     Format zip
Packit Service 1d0348
	     compression
Packit Service 1d0348
		     The value is either “store” or “deflate” to indicate how
Packit Service 1d0348
		     the following entries should be compressed.  Note that
Packit Service 1d0348
		     this setting is ignored for directories, symbolic links,
Packit Service 1d0348
		     and other special entries.
Packit Service 1d0348
	     experimental
Packit Service 1d0348
		     This boolean option enables or disables experimental Zip
Packit Service 1d0348
		     features that may not be compatible with other Zip imple‐
Packit Service 1d0348
		     mentations.
Packit Service 1d0348
	     fakecrc32
Packit Service 1d0348
		     This boolean option disables CRC calculations.  All CRC
Packit Service 1d0348
		     fields are set to zero.  It should not be used except for
Packit Service 1d0348
		     testing purposes.
Packit Service 1d0348
	     hdrcharset
Packit Service 1d0348
		     This sets the character set used for filenames.
Packit Service 1d0348
	     zip64   Zip64 extensions provide additional file size information
Packit Service 1d0348
		     for entries larger than 4 GiB.  They also provide
Packit Service 1d0348
		     extended file offset and archive size information when
Packit Service 1d0348
		     archives exceed 4 GiB.  By default, the Zip writer selec‐
Packit Service 1d0348
		     tively enables these extensions only as needed.  In par‐
Packit Service 1d0348
		     ticular, if the file size is unknown, the Zip writer will
Packit Service 1d0348
		     include Zip64 extensions to guard against the possibility
Packit Service 1d0348
		     that the file might be larger than 4 GiB.
Packit Service 1d0348
Packit Service 1d0348
		     Setting this boolean option will force the writer to use
Packit Service 1d0348
		     Zip64 extensions even for small files that would not oth‐
Packit Service 1d0348
		     erwise require them.  This is primarily useful for test‐
Packit Service 1d0348
		     ing.
Packit Service 1d0348
Packit Service 1d0348
		     Disabling this option with !zip64 will force the Zip
Packit Service 1d0348
		     writer to avoid Zip64 extensions: It will reject files
Packit Service 1d0348
		     with size greater than 4 GiB, it will reject any new
Packit Service 1d0348
		     entries once the total archive size reaches 4 GiB, and it
Packit Service 1d0348
		     will not use Zip64 extensions for files with unknown
Packit Service 1d0348
		     size.  In particular, this can improve compatibility when
Packit Service 1d0348
		     generating archives where the entry sizes are not known
Packit Service 1d0348
		     in advance.
Packit Service 1d0348
Packit Service 1d0348
EXAMPLES
Packit Service 1d0348
     The following example creates an archive write handle to create a gzip-
Packit Service 1d0348
     compressed ISO9660 format image.  The two options here specify that the
Packit Service 1d0348
     ISO9660 archive will use kernel.img as the boot image for El Torito boot‐
Packit Service 1d0348
     ing, and that the gzip compressor should use the maximum compression
Packit Service 1d0348
     level.
Packit Service 1d0348
Packit Service 1d0348
	   a = archive_write_new();
Packit Service 1d0348
	   archive_write_add_filter_gzip(a);
Packit Service 1d0348
	   archive_write_set_format_iso9660(a);
Packit Service 1d0348
	   archive_write_set_options(a, "boot=kernel.img,compression=9");
Packit Service 1d0348
	   archive_write_open_filename(a, filename, blocksize);
Packit Service 1d0348
Packit Service 1d0348
ERRORS
Packit Service 1d0348
     More detailed error codes and textual descriptions are available from the
Packit Service 1d0348
     archive_errno() and archive_error_string() functions.
Packit Service 1d0348
Packit Service 1d0348
SEE ALSO
Packit Service 1d0348
     tar(1), libarchive(3), archive_read_set_options(3), archive_write(3)
Packit Service 1d0348
Packit Service 1d0348
HISTORY
Packit Service 1d0348
     The libarchive library first appeared in FreeBSD 5.3.
Packit Service 1d0348
Packit Service 1d0348
AUTHORS
Packit Service 1d0348
     The options support for libarchive was originally implemented by
Packit Service 1d0348
     Michihiro NAKAJIMA.
Packit Service 1d0348
Packit Service 1d0348
BUGS
Packit Service 1d0348
BSD			       February 2, 2012 			   BSD