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 active physical CPU cores.
       Format 7zip
	       1mcompression0m
		       The   value  is	one  of	 “store”,  “copy”,  “deflate”,
		       “bzip2”, “lzma1”, “lzma2”, “ppmd”, or “zstd”  to	 indi‐
		       cate  how  the  following entries should be compressed.
		       The values “store” and “copy” are synonyms.  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, with the exception of bzip2 which only  sup‐
		       ports  values  between 1 and 9, and zstd which may sup‐
		       port negative values depending on the  library  version
		       and commonly used values 1 through 22.  The interpreta‐
		       tion  of	 the  compression  level depends on the chosen
		       compression method.
	       1mthreads0m
		       The value is interpreted as a decimal integer  specify‐
		       ing  the	 number of threads for multi-threaded compres‐
		       sion (for compressors like zstd that  support  it).  If
		       set  to 0, an attempt will be made to discover the num‐
		       ber of CPU cores.
       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”,  “deflate”,  “bzip2”,
		       “lzma”, “xz”, or “zstd” 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”,  “bzip2”,  “lzma”, or “zstd” compression (in
		       order of priority,  depending  on  what	libraries  are
		       linked) with the given level.
	       1mthreads0m
		       The  value is interpreted as a decimal integer specify‐
		       ing the number of threads to use for  compression.   It
		       is  supported  only  for “xz” or “zstd” compression and
		       ignored for any other.  A threads value of 0 is a  spe‐
		       cial  one  requesting to detect and use as many threads
		       as the number of active physical CPU cores.
	       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)
