tar(3tcl)							 Tar file handling							 tar(3tcl)

__________________________________________________________________________________________________________________________________________________

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 con-
       figured 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  directo-
		     ries.

	      -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  con-
       figured 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

tar									0.7								 tar(3tcl)