4mARCHIVE_WRITE_OPTIONS24m(3)	 Library Functions Manual  4mARCHIVE_WRITE_OPTIONS24m(3)

1mNAME0m
       archive_write_set_filter_option,	      archive_write_set_format_option,
       archive_write_set_option, archive_write_set_options  —  functions  con‐
       trolling options for writing archives

1mLIBRARY0m
       Streaming Archive Library (libarchive, -larchive)

1mSYNOPSIS0m
       4mint0m
       1marchive_write_set_filter_option22m(4mstruct24m 4marchive24m 4m*24m,   4mconst24m 4mchar24m 4m*module24m,
	   4mconst24m 4mchar24m 4m*option24m, 4mconst24m 4mchar24m 4m*value24m);

       4mint0m
       1marchive_write_set_format_option22m(4mstruct24m 4marchive24m 4m*24m,   4mconst24m 4mchar24m 4m*module24m,
	   4mconst24m 4mchar24m 4m*option24m, 4mconst24m 4mchar24m 4m*value24m);

       4mint0m
       1marchive_write_set_option22m(4mstruct24m 4marchive24m 4m*24m,	       4mconst24m 4mchar24m 4m*module24m,
	   4mconst24m 4mchar24m 4m*option24m, 4mconst24m 4mchar24m 4m*value24m);

       4mint0m
       1marchive_write_set_options22m(4mstruct24m 4marchive24m 4m*24m, 4mconst24m 4mchar24m 4m*options24m);

1mDESCRIPTION0m
       These functions provide a way for libarchive clients to configure  spe‐
       cific write modules.

       1marchive_write_set_filter_option22m(), 1marchive_write_set_format_option22m()
	       Specifies an option that will be passed to the currently-regis‐
	       tered filters (including decompression filters) or format read‐
	       ers.

	       If  4moption24m	and  4mvalue24m	 are  both NULL, these functions will do
	       nothing and 1mARCHIVE_OK 22mwill be returned.  If 4moption24m is NULL but
	       4mvalue24m  is  not,   these   functions	  will	 do   nothing	and
	       1mARCHIVE_FAILED 22mwill be returned.

	       If 4mmodule24m is not NULL, 4moption24m and 4mvalue24m will be provided to the
	       filter or reader named 4mmodule24m.  The return value will be either
	       1mARCHIVE_OK   22mif   the   option   was  successfully	handled	 or
	       1mARCHIVE_WARN 22mif the option was unrecognized by  the	 module	 or
	       could  otherwise	 not  be handled.  If there is no such module,
	       1mARCHIVE_FAILED 22mwill be returned.

	       If 4mmodule24m is NULL, 4moption24m and 4mvalue24m will be provided  to	every
	       registered  module.   If any module returns 1mARCHIVE_FATAL22m, this
	       value will be returned immediately.  Otherwise, 1mARCHIVE_OK 22mwill
	       be  returned  if	  any	module	 accepts   the	 option,   and
	       1mARCHIVE_FAILED 22min all other cases.

       1marchive_write_set_option22m()
	       Calls	      1marchive_write_set_format_option22m(),	       then
	       1marchive_write_set_filter_option22m().	If either function  returns
	       1mARCHIVE_FATAL22m,  1mARCHIVE_FATAL  22mwill  be  returned  immediately.
	       Otherwise, the greater of the two values will be returned.

       1marchive_write_set_options22m()
	       4moptions24m is a comma-separated list of options.   If	4moptions24m  is
	       NULL or empty, 1mARCHIVE_OK 22mwill be returned immediately.

	       Individual options have one of the following forms:
	       4moption=value0m
		       The option/value pair will be provided to every module.
		       Modules	that  do  not  accept an option with this name
		       will ignore it.
	       4moption24m  The option will be provided	 to  every  module  with  a
		       value of “1”.
	       4m!option0m
		       The option will be provided to every module with a NULL
		       value.
	       4mmodule:option=value24m, 4mmodule:option24m, 4mmodule:!option0m
		       As  above,  but the corresponding option and value will
		       be provided only to modules whose name matches 4mmodule24m.

1mOPTIONS0m
       Filter b64encode
	       1mmode	 22mThe value is interpreted as octal digits specifying the
		       file mode.
	       1mname	 22mThe value specifies the file name.
       Filter bzip2
	       1mcompression-level0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the	 bzip2 compression level. Supported values are
		       from 1 to 9.
       Filter gzip
	       1mcompression-level0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the	 gzip  compression level. Supported values are
		       from 0 to 9.
	       1mtimestamp0m
		       Store timestamp. This is enabled by default.
       Filter lrzip
	       1mcompression22m=4mtype0m
		       Use 4mtype24m as compression method.  Supported	values	are
		       “bzip2”, “gzipi”, “lzo” (ultra fast), and “zpaq” (best,
		       extremely slow).
	       1mcompression-level0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the lrzip compression level. Supported  values  are
		       from 1 to 9.
       Filter lz4
	       1mcompression-level0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the lz4 compression	level.	Supported  values  are
		       from 0 to 9.
	       1mstream-checksum0m
		       Enable stream checksum. This is enabled by default.
	       1mblock-checksum0m
		       Enable block checksum. This is disabled by default.
	       1mblock-size0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the lz4 compression block  size.  Supported	values
		       are from 4 to 7 (default).
	       1mblock-dependence0m
		       Use  the	 previous  block of the block being compressed
		       for a compression dictionary to improve compression ra‐
		       tio.  This is disabled by default.
       Filter lzop
	       1mcompression-level0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the	 lzop  compression level. Supported values are
		       from 1 to 9.
       Filter uuencode
	       1mmode	 22mThe value is interpreted as octal digits specifying the
		       file mode.
	       1mname	 22mThe value specifies the file name.
       Filter xz
	       1mcompression-level0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the compression level. Supported values are from 0
		       to 9.
	       1mthreads0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the number of threads for multi-threaded lzma com‐
		       pression.  If supported, the default value is read from
		       1mlzma_cputhreads22m().
       Filter zstd
	       1mcompression-level0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the	 compression level. Supported values depend on
		       the library version, common values are from 1 to 22.
	       1mlong	 22mEnables long distance matching.  The  value	 is  inter‐
		       preted as a decimal integer specifying log2 window size
		       in bytes. Values from 10 to 30 for 32 bit, or 31 for 64
		       bit, are supported.
	       1mthreads0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the number of threads for multi-threaded zstd  com‐
		       pression.  If set to 0, zstd will attempt to detect and
		       use the number of physical CPU cores.
       Format 7zip
	       1mcompression0m
		       The   value  is	one  of	 “store”,  “copy”,  “deflate”,
		       “bzip2”, “lzma1”, “lzma2” or “ppmd” to indicate how the
		       following entries should	 be  compressed.   The	values
		       “store”	and  “copy” are synonyms.  Note that this set‐
		       ting is ignored for directories,	 symbolic  links,  and
		       other special entries.
	       1mcompression-level0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the compression level.  Values between 0 and 9  are
		       supported,  with the exception of bzip2 which only sup‐
		       ports values between 1 and 9.   The  interpretation  of
		       the compression level depends on the chosen compression
		       method.
       Format bin
	       1mhdrcharset0m
		       The  value is used as a character set name that will be
		       used when translating file names.
       Format gnutar
	       1mhdrcharset0m
		       The value is used as a character set name that will  be
		       used when translating file, group and user names.
       Format iso9660 - volume metadata
	       These options are used to set standard ISO9660 metadata.
	       1mabstract-file22m=4mfilename0m
		       The  file with the specified name will be identified in
		       the ISO9660 metadata as holding the abstract  for  this
		       volume.	Default: none.
	       1mapplication-id22m=4mfilename0m
		       The  file with the specified name will be identified in
		       the ISO9660 metadata as holding the application identi‐
		       fier for this volume.  Default: none.
	       1mbiblio-file22m=4mfilename0m
		       The file with the specified name will be identified  in
		       the  ISO9660  metadata  as holding the bibliography for
		       this volume.  Default: none.
	       1mcopyright-file22m=4mfilename0m
		       The file with the specified name will be identified  in
		       the  ISO9660 metadata as holding the copyright for this
		       volume.	Default: none.
	       1mpublisher22m=4mfilename0m
		       The file with the specified name will be identified  in
		       the  ISO9660 metadata as holding the publisher informa‐
		       tion for this volume.  Default: none.
	       1mvolume-id22m=4mstring0m
		       The specified string will be used as the Volume Identi‐
		       fier in the ISO9660 metadata.   It  is  limited	to  32
		       bytes.  Default: none.
       Format iso9660 - boot support
	       These options are used to make an ISO9660 image that can be di‐
	       rectly booted on various systems.
	       1mboot22m=4mfilename0m
		       The  file  matching  this  name	will be used as the El
		       Torito boot image file.
	       1mboot-catalog22m=4mname0m
		       The name that will be used for the El Torito boot cata‐
		       log.  Default: 4mboot.catalog0m
	       1mboot-info-table0m
		       The boot image file provided by the  1mboot22m=4mfilename24m  op‐
		       tion  will  be edited with appropriate boot information
		       in bytes 8 through 64.  Default: disabled
	       1mboot-load-seg22m=4mhexadecimal-number0m
		       The load segment for a no-emulation boot image.
	       1mboot-load-size22m=4mdecimal-number0m
		       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  intelli‐
		       gent  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.
	       1mboot-type22m=4mvalue0m
		       Specifies the boot semantics used by the El Torito boot
		       image: If the 4mvalue24m is 1mfd22m, then the boot image	 is  as‐
		       sumed  to  be a bootable floppy image.  If the 4mvalue24m is
		       1mhd22m, then the boot image is assumed	to  be	a  bootable
		       hard  disk  image.   If	the 4mvalue24m is 1mno-emulation22m, the
		       boot image is used without floppy or hard  disk	emula‐
		       tion.   If  the boot image is exactly 1.2MB, 1.44MB, or
		       2.88MB, then the default is 1mfd22m, otherwise  the  default
		       is 1mno-emulation22m.
       Format iso9660 - filename and size extensions
	       Various extensions to the base ISO9660 format.
	       1mallow-ldots0m
		       If  enabled,  allows  filenames to begin with a leading
		       period.	If disabled, filenames that begin with a lead‐
		       ing period will have that period replaced by an	under‐
		       score  character	 in  the  standard  ISO9660 namespace.
		       This does not impact names stored in the	 Rockridge  or
		       Joliet extension area.  Default: disabled.
	       1mallow-lowercase0m
		       If enabled, allows filenames to contain lowercase char‐
		       acters.	 If  disabled, filenames will be forced to up‐
		       percase.	 This does not	impact	names  stored  in  the
		       Rockridge or Joliet extension area.  Default: disabled.
	       1mallow-multidot0m
		       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.   De‐
		       fault: disabled.
	       1mallow-period0m
		       If enabled, allows filenames to contain trailing period
		       characters,  in violation of the ISO9660 specification.
		       If disabled, trailing periods will be converted to  un‐
		       derscore characters.  This does not impact names stored
		       in  the	Rockridge  or Joliet extension area.  Default:
		       disabled.
	       1mallow-pvd-lowercase0m
		       If enabled, the Primary Volume Descriptor  may  contain
		       lowercase ASCII characters, in violation of the ISO9660
		       specification.	If  disabled,  characters will be con‐
		       verted to uppercase ASCII.  Default: disabled.
	       1mallow-sharp-tilde0m
		       If enabled, sharp and tilde characters will be  permit‐
		       ted  in filenames, in violation if the ISO9660 specifi‐
		       cation.	If disabled, such characters will be converted
		       to underscore characters.  Default: disabled.
	       1mallow-vernum0m
		       If enabled,  version  numbers  will  be	included  with
		       files.	If  disabled,  version	numbers	 will  be sup‐
		       pressed, in violation of the  ISO9660  standard.	  This
		       does not impact names stored in the Rockridge or Joliet
		       extension area.	Default: enabled.
	       1miso-level0m
		       This enables support for file size and file name exten‐
		       sions  in  the  core ISO9660 area.  The name extensions
		       specified here do not affect the names  stored  in  the
		       Rockridge or Joliet extension areas.
		       1miso-level=10m
			       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.
		       1miso-level=20m
			       Filenames  are  limited to 30 uppercase charac‐
			       ters with a 30-character	 extension,  directory
			       names  are  limited to 30 characters, files are
			       limited to 4 GiB.
		       1miso-level=30m
			       As with 1miso-level=222m, except that files may	ex‐
			       ceed 4 GiB.
		       1miso-level=40m
			       As  with 1miso-level=322m, except that filenames may
			       be up to 193 characters and may	include	 arbi‐
			       trary 8-bit characters.
	       1mjoliet	 22mMicrosoft's	 Joliet extensions store a completely sepa‐
		       rate set of directory information about each file.   In
		       particular, this information includes Unicode filenames
		       of up to 255 characters.	 Default: enabled.
	       1mlimit-depth0m
		       If  enabled,  libarchive	 will use directory relocation
		       records to ensure that no pathname exceeds the  ISO9660
		       limit  of  8 directory levels.  If disabled, no reloca‐
		       tion will occur.	 Default: enabled.
	       1mlimit-dirs0m
		       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
	       1mpad	 22mIf	enabled,  300 kiB of zero bytes will be appended to
		       the end of the archive.	Default: enabled
	       1mrelaxed-filenames0m
		       If enabled, all 7-bit ASCII characters are permitted in
		       filenames   (except   lowercase	  characters	unless
		       1mallow-lowercase  22mis	 also  specified).   This  violates
		       ISO9660 standards.  This does not impact	 names	stored
		       in  the	Rockridge  or Joliet extension area.  Default:
		       disabled.
	       1mrockridge0m
		       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.  De‐
		       fault: enabled.
       Format iso9660 - zisofs support
	       The zisofs extensions permit each file to be independently com‐
	       pressed	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 dis‐
	       abled by default.
	       1mcompression-level22m=number
		       The compression level used by the  deflate  compressor.
		       Ranges  from  0 (least effort) to 9 (most effort).  De‐
		       fault: 6
	       1mzisofs	 22mSynonym for 1mzisofs=direct22m.
	       1mzisofs=direct0m
		       Compress	  each	 file	in   the   archive.	Unlike
		       1mzisofs=indirect22m,   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.
	       1mzisofs=indirect0m
		       Recognizes files that have already been compressed with
		       the  1mmkzftree	22mutility  and	 sets up the necessary file
		       metadata so that readers will correctly identify	 these
		       as zisofs-compressed files.
	       1mzisofs-exclude22m=4mfilename0m
		       Specifies a filename that should not be compressed when
		       using  1mzisofs=direct22m.  This option can be provided mul‐
		       tiple times to suppress compression on many files.
       Format mtree
	       1mcksum22m, 1mdevice22m, 1mflags22m, 1mgid22m,  1mgname22m,  1mindent22m,  1mlink22m,  1mmd522m,	 1mmode22m,
		       1mnlink22m,  1mrmd16022m,  1msha122m,  1msha25622m,  1msha38422m,  1msha51222m, 1msize22m,
		       1mtime22m, 1muid22m, 1muname0m
		       Enable a particular keyword in the mtree output.	  Pre‐
		       fix with an exclamation mark to disable the correspond‐
		       ing  keyword.   The  default  is equivalent to “device,
		       flags, gid, gname, link, mode, nlink, size, time, type,
		       uid, uname”.
	       1mall	 22mEnables all of the above keywords.
	       1muse-set0m
		       Enables generation of 1m/set 22mlines that  specify  default
		       values for the following files and/or directories.
	       1mindent	 22mXXX needs explanation XXX
       Format newc
	       1mhdrcharset0m
		       The  value is used as a character set name that will be
		       used when translating file names.
       Format odc
	       1mhdrcharset0m
		       The value is used as a character set name that will  be
		       used when translating file names.
       Format pwb
	       1mhdrcharset0m
		       The  value is used as a character set name that will be
		       used when translating file names.
       Format pax
	       1mhdrcharset0m
		       The value is used as a character set name that will  be
		       used  when translating file, group and user names.  The
		       value is one of “BINARY”	 or  “UTF-8”.	With  “BINARY”
		       there  is  no  character conversion, with “UTF-8” names
		       are converted to UTF-8.
	       1mxattrheader0m
		       When storing extended attributes, this  option  config‐
		       ures  which headers should be written. The value is one
		       of “all”, “LIBARCHIVE”, or “SCHILY”.  By default,  both
		       “LIBARCHIVE.xattr” and “SCHILY.xattr” headers are writ‐
		       ten.
       Format ustar
	       1mhdrcharset0m
		       The  value is used as a character set name that will be
		       used when translating file, group and user names.
       Format v7tar
	       1mhdrcharset0m
		       The value is used as a character set name that will  be
		       used when translating file, group and user names.
       Format warc
	       1momit-warcinfo0m
		       Set to “true” to disable output of the warcinfo record.
       Format xar
	       1mchecksum22m=4mtype0m
		       Use 4mtype24m as file checksum method.  Supported values are
		       “none”, “md5”, and “sha1” (default).
	       1mcompression22m=4mtype0m
		       Use  4mtype24m  as compression method.  Supported values are
		       “none”, “bzip2”, “gzip” (default), “lzma” and “xz”.
	       1mcompression_level0m
		       The value is a decimal integer from 1 to	 9  specifying
		       the compression level.
	       1mtoc-checksum22m=4mtype0m
		       Use  4mtype24m  as  table of contents checksum method.  Sup‐
		       ported values are “none”, “md5” and “sha1” (default).
       Format zip
	       1mcompression0m
		       The value is either “store” or  “deflate”  to  indicate
		       how  the	 following entries should be compressed.  Note
		       that this setting is ignored for directories,  symbolic
		       links, and other special entries.
	       1mcompression-level0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the compression level.  Values between 0 and 9  are
		       supported.   A compression level of 0 switches the com‐
		       pression method to “store”, other  values  will	enable
		       “deflate” compression with the given level.
	       1mencryption0m
		       Enable encryption using traditional zip encryption.
	       1mencryption22m=4mtype0m
		       Use  4mtype24m  as  encryption  type.   Supported values are
		       “zipcrypt”  (traditional	 zip   encryption),   “aes128”
		       (WinZip	 AES-128   encryption)	and  “aes256”  (WinZip
		       AES-256 encryption).
	       1mexperimental0m
		       This boolean option enables  or	disables  experimental
		       Zip  features that may not be compatible with other Zip
		       implementations.
	       1mfakecrc320m
		       This boolean option disables CRC calculations.  All CRC
		       fields are set to zero.	It should not be  used	except
		       for testing purposes.
	       1mhdrcharset0m
		       The  value is used as a character set name that will be
		       used when translating file names.
	       1mzip64	 22mZip64 extensions provide additional file size  informa‐
		       tion  for entries larger than 4 GiB.  They also provide
		       extended file offset and archive size information  when
		       archives	 exceed 4 GiB.	By default, the Zip writer se‐
		       lectively enables these extensions only as needed.   In
		       particular, if the file size is unknown, the Zip writer
		       will include Zip64 extensions to guard against the pos‐
		       sibility that the file might be larger than 4 GiB.

		       Setting	this  boolean  option will force the writer to
		       use Zip64 extensions even for small  files  that	 would
		       not  otherwise  require them.  This is primarily useful
		       for testing.

		       Disabling this option with 1m!zip64 22mwill  force  the	Zip
		       writer  to avoid Zip64 extensions: It will reject files
		       with size greater than 4 GiB, it will  reject  any  new
		       entries	once the total archive size reaches 4 GiB, and
		       it will not use Zip64 extensions for files with unknown
		       size.  In particular, this  can	improve	 compatibility
		       when  generating archives where the entry sizes are not
		       known in advance.

1mEXAMPLES0m
       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 4mkernel.img24m as the boot  image  for	 El  Torito
       booting,	 and  that the gzip compressor should use the maximum compres‐
       sion level.

	     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);

1mERRORS0m
       More detailed error codes and textual descriptions are  available  from
       the 1marchive_errno22m() and 1marchive_error_string22m() functions.

1mSEE ALSO0m
       4mtar24m(1), 4marchive_read_set_options24m(3), 4marchive_write24m(3), 4mlibarchive24m(3)

1mHISTORY0m
       The 1mlibarchive 22mlibrary first appeared in FreeBSD 5.3.

1mAUTHORS0m
       The  options  support  for  libarchive  was  originally	implemented by
       Michihiro NAKAJIMA.

1mBUGS0m
Debian			       January 31, 2020	      4mARCHIVE_WRITE_OPTIONS24m(3)
