Ubuntu Manpage: tar - Tar file creation, extraction & manipulation

NAME

       tar - Tar file creation, extraction & manipulation

SYNOPSIS

       package require Tcl  8.4

       package require tar  ?0.11?

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

       Note:  Starting  with  version  0.8  the tar reader commands (contents, stats, get, untar)
       support the GNU LongName extension (header type ´L') for large paths.

BEWARE

       For all commands, when using -chan ...

       [1]    It is assumed that the channel was opened for reading, and  configured  for  binary
              input.

       [2]    It is assumed that the channel position is at the beginning of a legal tar file.

       [3]    The commands will modify the channel position as they perform their task.

       [4]    The commands will not close the channel.

       [5]    In  other  words,  the commands leave the channel in a state very likely unsuitable
              for use by further tar commands. Still doing so will very likely results in errors,
              bad data, etc. pp.

       [6]    It  is  the  responsibility  of  the  user  to  seek the channel back to a suitable
              position.

       [7]    When using a channel transformation which is not generally  seekable,  for  example
              gunzip, then it is the responsibility of the user to (a) unstack the transformation
              before seeking the channel back to a suitable position, and (b) for  restacking  it
              after.

COMMANDS

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

An error is thrown when fileName is not found in the tar archive.

::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  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       archive, tape archive, tar