Provided by: atool_0.29.0-2ubuntu1_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

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

       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 automaticly assumed when
              als is executed.

       -x, --extract
              Extract files from archive.  This option is automaticly  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 automaticly assumed when apack
              is executed.

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

       -d, --diff
              Extract two archives and use diff(1)  to  generate  differencies
              between  them.  This option is automaticly 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.

       --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 (.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.

       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.

       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.

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_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.

       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_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).

              Note that tar-archives compressed with a file  compressor  (such
              as  gzip,  bzip2  and  so on) can’t be identified this way.  For
              this reason, files packed with gzip and other  file  compressors
              are not identified either.

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

       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_compress (default: compress)

       path_lzop (default: lzop)

       path_rar (default: rar)

       path_unrar (default: unrar)

       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_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

       Here’s a shell function that will make the aunpack command change  into
       the directory where files were extracted:
            aunpack () {
              TMP=mktemp /tmp/aunpack.XXXXXXXXXXatool -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@>.

AUTHOR

       atool was written by Oskar Liljeblad.

                                 July 1, 2004                         atool(1)