Scroll to navigation

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





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.







  

  
Directory to extract to. Uses pwd if none is specified

  

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

  

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

  

  
Dont overwrite files that already exist

  

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

  

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

  

  
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.







  

  
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.

  

  
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.







  

  
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.

  

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

  

  
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






CATEGORY


File formats







  

    0.11
    tcllib