Provided by: atool_0.38.0-1_all bug

NAME

       atool - A script for managing file archives of various types

SYNOPSIS

       atool [OPTION]... ARCHIVE [FILE]...
       aunpack [OPTION]... ARCHIVE [FILE]...
       apack [OPTION]... ARCHIVE [FILE]...
       als [OPTION]... ARCHIVE [FILE]...
       acat [OPTION]... ARCHIVE [FILE]...
       adiff [OPTION]... ARCHIVE ARCHIVE
       arepack [OPTION]...OLD-ARCHIVE NEW-ARCHIVE

DESCRIPTION

       This manual page document describes the atool commands.  These commands
       are used for managing file archives of various types, such as  tar  and
       Zip  archives.  Each  command can be executed individually or by giving
       the appropriate options to atool (see OPTIONS below).

       aunpack extracts files from an archive. Often one wants to extract  all
       files  in  an archive to a single subdirectory.  However, some archives
       contain multiple files in their root directories. The  aunpack  program
       overcomes   this   problem  by  first  extracting  files  to  a  unique
       (temporary) directory, and then moving its contents back  if  possible.
       This also prevents local files from being overwritten by mistake.

       apack  creates archives (or compresses files). If no file arguments are
       specified, filenames to add are read from standard in.

       als lists files in an archive.

       acat extracts files in an archive to standard out.

       adiff generates a diff between two archives using diff(1).

       arepack repacks archives to a different format. It does this  by  first
       extracting  all  files  of  the old archive into a temporary directory,
       then packing all files extracted to that directory to the new  archive.
       Use  the --each (-e) option in combination with --format (-F) to repack
       multiple archives using a single invocation of atool. Note that arepack
       will not remove the old archive.

       Unless  the  --format  (-F)  option  is provided, the archive format is
       determined by the archive file extension. I.e.  an extension  ".tar.gz"
       or  ".tgz"  means tar+gzip format. Note that the extensions are checked
       in the order listed in the section ARCHIVE TYPES below, which is why  a
       file  with  extension ".tar.gz" is considered to a be tar+gzip archive,
       not a gzip compressed file.

OPTIONS

       These programs follow the usual GNU  command  line  syntax,  with  long
       options  starting  with  two  dashes  (`-').   A  summary of options is
       included below.

       -l, --list
              List files in archive.  This  option  is  automatically  assumed
              when als is executed.

       -x, --extract
              Extract  files  from  archive.   This  option  is  automatically
              assumed when aunpack is executed.

       -X, --extract-to=PATH
              Extract files from archive  to  the  specified  directory.  When
              unpacking  compressed files, PATH may refer to either a filename
              or an existing directory.

       -a, --add
              Create archive.  This option is automatically assumed when apack
              is executed.

       -c, --cat
              Extract  a  file  from archive to standard out (displaying it on
              screen).  This option is  automatically  assumed  when  acat  is
              executed.

       -d, --diff
              Extract  two  archives  and use diff(1) to generate differencies
              between them.  This option is automatically assumed  when  adiff
              is executed.

       -e, --each
              For  each  argument,  execute the specified command. This can be
              used to quickly extract, list or create multiple  archives  (see
              EXAMPLES  below).  This  option  can  not  be  used with the cat
              command.

       -F, --format=EXTENSION
              Specify archive format manually (see ARCHIVE TYPES below).

       -S, --simulate
              Run atool in simulation mode. No changes to the filesystem (i.e.
              writes)  will  be  made, and all commands that would be executed
              are displayed  instead.  This  option  can't  be  combined  with
              --explain (since it implies that already).

              Note  that  it  is  not  guaranteed that the commands printed in
              simulation mode will be the  same  as  those  executed  in  non-
              simulation  mode. This is because some operations depend on what
              files  archives  contain,  and  atool  can  at  this  time  only
              determine that by extracting archives.

       -E, --explain
              Display  commands  executed  by  atool.  This  option  can't  be
              combined with --simulate.

       -p, --page
              Run output through a pager, usually pager unless the environment
              variable PAGER is set.

       -f, --force
              When  extracting  from  files, allow overwriting of local files.
              When  creating  an  archive,  allow  the  archive  file  to   be
              overwritten  if  it  already exists. Note that it is possible to
              add files to existing RAR and Zip archives (this is not possible
              for many other formats).

       -D, --subdir
              When  extracting archives, always create a new directory for the
              archive even if the archive only contains one file in  its  root
              directory.

       -0, --null
              If no file arguments are specified when creating or adding files
              to archives, the list of files will be read  from  standard  in.
              Normally these filenames are separated by newline, but with this
              option they are separated by null-bytes. This is useful with the
              GNU find -print0 option.

       -q, --quiet
              Decrease  verbosity  level  by  one. This is subtracted from the
              default  verbosity  level,   or   the   level   specified   with
              --verbosity. This option may be specified more than once to make
              atool even less verbose.

       -v, --verbose
              Increase verbosity level by one. This is added  to  the  default
              verbosity  level,  or the level specified with --verbosity. This
              option may be specified more than once to make atool  even  more
              verbose.

       -V, --verbosity=LEVEL
              Specify  verbosity  level.  The  default level is 1, which means
              "normal verbosity" - e.g.  when  creating  and  extracting  from
              archives, files will be listed.

       --config=FILE
              Load  configuration  from  the  specified  file. When using this
              option, the system-wide and user-wide configuration  files  will
              not  be  loaded. If the specified file does not exist or can not
              be read, atool will terminate with an error message.

       -o, --option=KEY=VALUE
              Override a configuration option. These are applied after reading
              the configuration files.

              You  can  specify  this  multiple  times  to  override different
              options.

       -O, --format-option=OPTION
              Send additional options to the archiver  command.  This  can  be
              useful  when  specifying  compression options for some archives,
              e.g.
                      apack -F7z -O-mx=9 archive.7z dir
              You can specify this multiple times add different options.

       --save-outdir=FILE
              When extracting files, save the name of the directory which  the
              archive  was  extracted to to the specified file. If the command
              was not `extract', or the archive was not  extracted  to  a  new
              directory,  then  nothing will be written to the specified file.
              If multiple archives were specified (with  -e),  then  only  the
              last  directory  that files were extracted to will be written to
              FILE.

              This option is used internally (see EXAMPLES below).

       --help Show summary of options.

       --version
              Output version information and exit.

ARCHIVE TYPES

       Unless the -f (--format) option is  provided,  the  archive  format  is
       determined  by  the archive file extension. I.e. an extension ".tar.gz"
       or ".tgz" means tar+gzip format. Note that the extensions  are  checked
       in the other listed above, which is why a file with extension ".tar.gz"
       is considered to a tar+gzip archive, not a gzip archive.

       The  diff  command  is  supported  whenever  the  extract  command   is
       supported.

       The supported archive types are:

       tar+gzip (.tar.gz, .tgz)
              All commands are supported.

       tar+bzip (.tar.bz, .tbz)
              All commands are supported.

       tar+bzip2 (.tar.bz2, .tbz2)
              All commands are supported.

       tar+compress (.tar.Z, .tZ)
              All commands are supported.

       tar+lzop (.tar.lzo, .tzo)
              All commands are supported.

       tar+lzip (.tar.lz, .tlz)
              All commands are supported.

       tar+xz (.tar.xz, .txz)
              All commands are supported.

       tar+7z (.tar.7z, .t7z)
              All commands are supported.

       tar (.tar)
              All commands are supported.

       zip (.zip)
              All commands are supported.

       jar (.jar, .war)
              List, extract, and add commands are supported.  Cat is supported
              if use_jar_program is disabled.

       rar (.rar)
              All commands are supported.

       lha (.lha, .lzh)
              All commands are supported.

       7z (.7z)
              Extract, list and add commands are supported.

       alzip (.alz)
              Extract command is supported.

       ace (.ace)
              Extract and list commands are supported.

       ar (.a)
              All commands are supported.

       arj (.arj)
              List, extract and add commands are supported.

       arc (.arc)
              All command are supported.  (Note  that  arc  outputs  an  extra
              newline when the cat command is used.)

       rpm (.rpm)
              Extract and list commands are supported.

       deb (.deb)
              Extract and list commands are supported.

       cab (.cab)
              Cat, extract, and list commands are supported.

       gzip (.gz)
              Cat, extract, and add commands are supported.

       bzip (.bz)
              Cat, extract, and add commands are supported.

       bzip2 (.bz2)
              Cat, extract, and add commands are supported.

       compress (.Z)
              Cat, extract, and add commands are supported.

       lzma (.lzma)
              Cat, extract, and add commands are supported.

       lzop (.lzo)
              Extract  and  add commands are supported. The cat command is not
              supported because  lzop  does  not  want  to  extract  files  to
              standard out unless the -f flag is given.

       lzip (.lz)
              Cat, extract, and add commands are supported.

       xz (.xz)
              Cat, extract, and add commands are supported.

       rzip (.rz)
              Extract and add commands are supported.

       lrzip (.lrz)
              Extract and add commands are supported.

       7zip (.7z)
              All  commands  are  supported.   (Note  that 7z refuses to write
              extracted files to standard out if standard out is  a  terminal.
              Use  -p or pipe the output of atool/acat to a pager when reading
              in a terminal.)

       cpio (.cpio)
              List, extract and add commands are supported.

CONFIGURATION

       Since version 0.8.0, atool can read custom configuration files.  First,
       hardcoded  defaults  in  the  atool  program  file are evaluated.  Then
       system-wide configuration values are  loaded  from  /etc/atool.conf  if
       that  file  exists.  Finally,  per-user configuration values are loaded
       from .atoolrc in the current user's home directory.

       The format of the configuration files is simple:

              variable value

       Here variable is a variable listed below, and value  is  the  value  to
       associate  the  variable  with.  variable and value should be separated
       with at least one whitespace (space, tab etc). Empty  lines  and  lines
       beginning with # are discarded.

       A  value  of  `1'  means that the option is enabled, and `0' that it is
       disabled. Strings should not be quoted, as they start at the first non-
       whitespace character and end at the end of the line.

       The options are:

       use_tar_bzip2_option (default: 1)
              Enable  this  if  you  use  GNU  tar and it supports the --bzip2
              option for filtering  bzip2'ed  files  through  bzip2.  Versions
              1.13.6  or  later  of GNU tar support --bzip2. Therefore, if you
              use GNU tar earlier than 1.13.6, you will need to  disable  this
              option.

              This  used  to  be  use_tar_j_option  but  using --bzip2 is more
              portable.

       use_tar_z_option (default: 1)
              Enable this if you use GNU tar and it supports the -z option for
              filtering  gzipped  files through gzip. You will need to disable
              this and use_tar_j_option if you don't use GNU tar.

              Disabling these  two  options  doesn't  mean  that  atool  can't
              extract  bzip2/gzip files. If disabled, atool use a pipe to send
              output from bzip2/gzip to tar instead.

              If  possible,  these  options  should  be  enabled  since  error
              management is better when filtering is done by tar.

       use_tar_lzma_option (default: 1)
              Enable this if you use GNU tar and it supports the --lzma option
              for filtering lzma compressed files through lzma. Versions  1.20
              or later of GNU tar support --lzma.

       use_tar_lzop_option (default: 0)
              Enable this if you use GNU tar and it supports the --lzop option
              for filtering lzop compressed files through lzop. Versions  1.21
              or later of GNU tar support --lzop.

       use_tar_xz_option (default: 0)
              Enable  this  if you use GNU tar and it supports the --xz option
              for filtering xz compressed files through xz. Versions  1.22  or
              later of GNU tar support --xz.

       use_gzip_for_z (default: 1)
              Enable  this  if you want to use gzip instead of uncompress when
              decompressing compress'ed files (`.Z' files).

       use_rar_for_unpack (default: 0)
              Enable this if you want to always use rar instead of unrar  when
              possible.  This  makes atool use the rar command (path_rar) even
              when listing and extracting RAR files.

       use_arc_for_unpack (default: 0)
              Enable this if you want to always use  arc  instead  of  nomarch
              when  possible.  This makes atool use the arc command (path_arc)
              even when listing and extracting ARC files.

       use_arj_for_unpack (default: 0)
              Enable this if you want to always use arj instead of unarj  when
              possible.  This  makes atool use the arj command (path_arj) even
              when listing and extracting ARJ files.

       use_find_cpio_print0 (default: 1)
              Enable this  if  find  supports  the  -print0  option  and  cpio
              supports  the  -0 option. Without it, it is impossible/harder to
              make cpio archives of files with  newline  characters  in  their
              names.

       extract_deb_control (default: 1)
              Debian  .deb  package  files  contain  control  information in a
              DEBIAN  directory,  especially  the  package's  "control"  file.
              Enable this if you want the control information to be exctracted
              during extraction in addition to the normal files.

       strip_unknown_ext (default: 1)
              Certain  types  of  files  are  actually  archives,  but   their
              extensions  doesn't  tell so. Examples are Open Office documents
              (Zip files) and Gnumeric documents (gzip'ed  files).  Since  the
              extensions  of  those filenames are unknown to atool, they would
              not be stripped with this option set to 0. The  output  file  in
              that  case  would  be  something  like Unpack-XYZW. Setting this
              option to 1 will cause the extension to be stripped instead.

       use_pbzip2 (default: 0)
              Enable this if you want to use pbzip2 rather than bzip2.  Please
              not  that if use_tar_bzip2_option is enabled, then bzip2 will be
              used by tar regardless of the use_pbzip2 option. So if you  want
              tar  to  use  pbzip2  rather than bzip2, set use_pbzip2 to 1 and
              use_tar_bzip2_option to 0.

       use_jar (default: 0)
              Enable this if you want to use jar for managing jar archives. If
              you  disable  this  option,  zip will be used (which should work
              just as well, and probably be faster too).

              This option is disabled by default  since  extracting  files  to
              standard out (`cat') is not supported by jar.

       use_file (default: 1)
              Enable  this  if  you  want  atool  to identify file types using
              file(1) for those files with an unrecognized extension (or  none
              at all).

       use_file_always (default: 0)
              Enable  this if you want atool to always identify archives using
              file(1), regardless of the file extension. Please note that this
              currently has some drawbacks, such as not being able to identify
              all archive types (especially tar archives compressed with 7zip,
              lzop, szip etc).

       tmpdir_name (default: Unpack-%04d)
              atool  extracts  to a temporary directory created in the current
              directory so  that  no  files  are  overwritten.  This  variable
              controlls what name that temporary directory should have.

              The  `%d' string in this variable will be replaced with a random
              number between 0 and 9999. It is possible change the  format  of
              this number by using something else than `%d' - see printf(3).

       tmpfile_name (default: Pack-%04d)
              When  using pbzip2, and creating archives, a temporary file need
              to be created. This option controls the name of that file.   See
              tmpdir_name for further details on the format.

       path_pager (default: pager)

       path_jar (default: jar)

       path_tar (default: tar)

       path_zip (default: zip)

       path_unzip (default: unzip)

       path_gzip (default: gzip)

       path_bzip (default: bzip)

       path_bzip2 (default: bzip2)

       path_pbzip2 (default: pbzip2)

       path_compress (default: compress)

       path_lzma (default: lzma)

       path_lzop (default: lzop)

       path_lzip (default: lzip)

       path_rar (default: rar)

       path_unrar (default: unrar)

       path_cabextract (default: cabextract)

       path_7z (default: 7z)

       path_unalz (default: unalz)

       path_lha (default: lha)

       path_unace (default: unace)

       path_ar (default: ar)

       path_arj (default: arj)

       path_unarj (default: unarj)

       path_arc (default: arc)

       path_nomarch (default: nomarch)

       path_rpm (default: rpm)

       path_rpm2cpio (default: rpm2cpio)

       path_dpkg_deb (default: dpkg-deb)

       path_cpio (default: cpio)

       path_file (default: file)

       path_find (default: find)

       path_xargs (default: xargs)

       path_cat (default: cat)

       path_diff (default: diff)
              These are all paths to the corresponding programs. It is usually
              best to leave them as is, because that way their  locations  can
              be looked up from the PATH variable.

       args_diff (default: -ru)
              This  variable  specifies  command line arguments to pass to the
              diff command (as specified by path_diff) when using adiff. Space
              characters separate arguments in this string.

       path_syscfg (default: /etc/atool.conf)
              (This variable can only be set in the atool program file.)  This
              variable  specifies  the   directory   where   the   system-wide
              configuration file is located.

       path_usercfg (default: .atoolrc)
              (This  variable  can  only  be set in the atool program file and
              system-wide configuration file.)  This variable specifies  where
              the  user  configuration  file  is  located.  Note  that if this
              filename is relative (i.e. doesn't being with `/'), it  will  be
              relative  to the current user's home directory (as determined by
              the HOME environment variable).

       default_verbosity (default: 1)
              This is the default verbosity of  atool.  By  using  -q  and  -v
              options, the verbosity level can be raised and lowered.  Level 1
              means "normal verbosity" - e.g.  when  creating  and  extracting
              from archives, files will be listed.

       show_extracted (default: 1)
              If  this  is set to 1, the aunpack command will always show what
              file or directory that was extracted. Otherwise that  will  only
              be  printed  if  the  archive  was  extracted  to  an unexpected
              location (as a result of local files  already  existing  or  the
              archive having multiple files in its root directory).

              This can be quite useful in combinatiaon with `default_verbosity
              0'.  Note that this option will  have  no  effect  when  the  -X
              option  is used with aunpack, and it has no effect on compressed
              files.

       keep_compressed (default: 1)
              When compressing  a  file  with  gzip  or  bzip2,  the  original
              (uncompressed)   file  is  usually  deleted  once  it  has  been
              compressed. I.e. if you compress a file "test" you will  end  up
              with  only  one file, "test.gz".  With this option set to 1, you
              will make atool keep the original file  as  well.  The  original
              behaviour is achieved by setting this option to 0.

              This  option  also  has  an  equivalent  effect on uncompressing
              compressed files. When set to 1, the original (compressed)  file
              will be kept.  Otherwise it will be deleted.

              Note  however  that  this option has no effect when packing up a
              compressed file with the -X option  (for  specifying  an  output
              directory  or  file).  In  that case the original file is always
              kept.

       decompress_to_cwd (default: 1)
              When decompressing a file with commands such as gzip  or  bzip2,
              the decompressed file is usually placed in the same directory as
              the compressed file. With this option set to 1, the decompressed
              file is instead placed in the current working directory.

              Note that this option has no effect when -X is used.

ENVIRONMENT VARIABLES

       PAGER The default pager to use when the -p/--page option is specified.

EXAMPLES

       To extract all files from archive `foobar.tar.gz' to a subdirectory (or
       the current directory if it only contains one file):
            aunpack foobar.tar.gz

       To extract all  files  from  all  `.tar.gz'  archives  in  the  current
       directory:
            aunpack -e *.tar.gz

       To create a zip archive of two files `foo' and `bar':
            apack myarchive.zip foo bar

       To  display  the  file  `baz'  in the archive `myarchive.zip' through a
       pager:
            acat -p myarchive.zip baz

       To list contents of the rar archive `stuff.rar':
            als stuff.rar

       To   create   three   archives,   `dir1.tar.gz',   `dir2.tar.gz'    and
       `dir3.tar.gz',  so  that  the first one contains all files in dir1, the
       second all in dir2 and the third all dir3:
            apack -e -F .tar.gz dir1 dir2 dir3

       To show all differences  between  version  2.4.17  and  2.4.18  of  the
       kernel:
            adiff linux-2.4.17.tar.gz linux-2.4.18.tar.gz

       To repack all .tar.gz archives in the current directory to .tar.7z (the
       old archive will be kept untouched):
            arepack -F.tar.7z -e *.tar.gz

       Here's a shell function that will make the aunpack command change  into
       the directory where files were extracted:
            aunpack () {
              TMP=`mktemp /tmp/aunpack.XXXXXXXXXX`
              atool -x --save-outdir=$TMP "$@"
              DIR="`cat $TMP`"
              [ "$DIR" != "" -a -d "$DIR" ] && cd "$DIR"
              rm $TMP
            }
       If  you  don't have the mktemp program, you can replace the second line
       with (note however that this is not entirely safe)
              TMP="/tmp/atool_outdir.$$"

KNOWN BUGS

       Trying to extract gzip and other compressed files without the  .gz  (or
       .bz2 etc) extension won't work:

         aunpack: foo: format not known, identifying using file
         aunpack: foo: format is `gzip'
         gzip: foo: unknown suffix -- ignored

       This last error above is generated by gzip -d foo.

       If   you   find   a   bug   not   listed  here,  please  report  it  to
       <@PACKAGE_BUGREPORT@>.

REPORTING BUGS

       Report bugs to <oskar@osk.mine.nu>.

AUTHOR

       The  author  of  atool  and  this  manual  page  is   Oskar   Liljeblad
       <oskar@osk.mine.nu>.

COPYRIGHT

       Copyright  (C)  2001,  2002,  2003,  2004, 2005, 2007, 2008, 2009 Oskar
       Liljeblad

       This is free software; see the source for copying conditions.  There is
       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.