Provided by: tcllib_1.15-dfsg-2_all bug

NAME

       tar - Tar file creation, extraction & manipulation

SYNOPSIS

       package require Tcl  8.4

       package require tar  ?0.7?

       ::tar::contents tarball ?-chan?

       ::tar::stat tarball ?file? ?-chan?

       ::tar::untar tarball args

       ::tar::get tarball fileName ?-chan?

       ::tar::create tarball files args

       ::tar::add tarball files args

       ::tar::remove tarball files

_________________________________________________________________

DESCRIPTION

       ::tar::contents tarball ?-chan?
              Returns  a  list  of  the  files  contained in tarball. The order is not sorted and
              depends on the order files were stored in the archive.

              If the option -chan is present tarball is interpreted as an open  channel.   It  is
              assumed  that  the channel was opened for reading, and configured for binary input.
              The command will not close the channel.

       ::tar::stat tarball ?file? ?-chan?
              Returns a nested dict containing information on the named ?file? in tarball, or all
              files  if none is specified. The top level are pairs of filename and info. The info
              is a dict with the keys "mode uid gid size mtime type linkname uname gname devmajor
              devminor"
              % ::tar::stat tarball.tar
              foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}

       If  the  option -chan is present tarball is interpreted as an open channel.  It is assumed
       that the channel was opened for reading, and configured for  binary  input.   The  command
       will not close the channel.

       ::tar::untar tarball args
              Extracts tarball. -file and -glob limit the extraction to files which exactly match
              or pattern match the given argument. No error is thrown if no files match.  Returns
              a  list  of  filenames  extracted  and the file size. The size will be null for non
              regular files. Leading path  seperators  are  stripped  so  paths  will  always  be
              relative.

              -dir dirName
                     Directory to extract to. Uses pwd if none is specified

              -file fileName
                     Only  extract  the  file  with  this  name.  The name is matched against the
                     complete path stored in the archive including directories.

              -glob pattern
                     Only extract files patching this glob style pattern. The pattern is  matched
                     against the complete path stored in the archive.

              -nooverwrite
                     Dont overwrite files that already exist

              -nomtime
                     Leave  the  file modification time as the current time instead of setting it
                     to the value in the archive.

              -noperms
                     In Unix, leave the file permissions as the current umask instead of  setting
                     them to the values in the archive.

              -chan  If  this option is present tarball is interpreted as an open channel.  It is
                     assumed that the channel was opened for reading, and configured  for  binary
                     input.  The command will not close the channel.

              % foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
              puts "Extracted $file ($size bytes)"
              }

       ::tar::get tarball fileName ?-chan?
              Returns the contents of fileName from the tarball

              % set readme [::tar::get tarball.tar doc/README] {
              % puts $readme
              }

       If  the  option -chan is present tarball is interpreted as an open channel.  It is assumed
       that the channel was opened for reading, and configured for  binary  input.   The  command
       will not close the channel.

       ::tar::create tarball files args
              Creates  a  new  tar file containing the files. files must be specified as a single
              argument which is a proper list of filenames.

              -dereference
                     Normally create will store links as an actual link pointing at a  file  that
                     may  or  may not exist in the archive. Specifying this option will cause the
                     actual file point to by the link to be stored instead.

              -chan  If this option is present tarball is interpreted as an open channel.  It  is
                     assumed  that  the channel was opened for writing, and configured for binary
                     output.  The command will not close the channel.

              % ::tar::create new.tar [glob -nocomplain file*]
              % ::tar::contents new.tar
              file1 file2 file3

       ::tar::add tarball files args
              Appends files to the end of the existing tarball. files  must  be  specified  as  a
              single argument which is a proper list of filenames.

              -dereference
                     Normally  add will store links as an actual link pointing at a file that may
                     or may not exist in the archive.  Specifying  this  option  will  cause  the
                     actual file point to by the link to be stored instead.

              -prefix string
                     Normally  add will store files under exactly the name specified as argument.
                     Specifying a ?-prefix? causes the string to be prepended to every name.

              -quick The only sure way to find the position in the tarball where new files can be
                     added  is  to  read  it  from  start,  but  if  tarball  was  written with a
                     "blocksize" of 1 (as this package does) then one can alternatively find this
                     position  by  seeking  from the end. The ?-quick? option tells add to do the
                     latter.

       ::tar::remove tarball files
              Removes files from the tarball. No error will result if the file does not exist  in
              the  tarball. Directory write permission and free disk space equivalent to at least
              the size of the tarball will be needed.
              % ::tar::remove new.tar {file2 file3}
              % ::tar::contents new.tar
              file3

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report   such  in  the  category  tar  of  the  Tcllib  SF  Trackers
       [http://sourceforge.net/tracker/?group_id=12883].   Please  also  report  any  ideas   for
       enhancements you may have for either package and/or documentation.

KEYWORDS

       archive, tape archive, tar

CATEGORY

       File formats