doc/text/archive_write_set_options.3.txt

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