


tar(n)                  Tar file handling                  tar(n)


______________________________________________________________________________

NAME
       tar - Tar file creation, extraction & manipulation

SYNOPSIS
       package require Tcl  8.4

       package require tar  ?0.6?

       ::tar::contents tarball

       ::tar::stat tarball ?file?

       ::tar::untar tarball args

       ::tar::get tarball fileName

       ::tar::create tarball files args

       ::tar::add tarball files args

       ::tar::remove tarball files

_________________________________________________________________

DESCRIPTION
       ::tar::contents tarball
              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.


       ::tar::stat tarball ?file?
              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}


       ::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 regu-
              lar  files.  Leading  path seperators are stripped so paths will
              always be relative.

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



tar                            0.6                              1





tar(n)                  Tar file handling                  tar(n)


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


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


       ::tar::get tarball fileName
              Returns the contents of fileName from the tarball


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


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

              -dereference
                     Normally create will store links as an actual link point-
                     ing  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.


       % ::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



tar                            0.6                              2





tar(n)                  Tar file handling                  tar(n)


              specified as a single argument which is a proper list  of  file-
              names.

              -dereference
                     Normally  add will store links as an actual link pointing
                     at a file that may or may not exist in the archive. Spec-
                     ifying 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











tar                            0.6                              3


