1tar(n)                         Tar file handling                        tar(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tar - Tar file creation, extraction & manipulation
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require tar  ?0.11?
14
15       ::tar::contents tarball ?-chan?
16
17       ::tar::stat tarball ?file? ?-chan?
18
19       ::tar::untar tarball args
20
21       ::tar::get tarball fileName ?-chan?
22
23       ::tar::create tarball files args
24
25       ::tar::add tarball files args
26
27       ::tar::remove tarball files
28
29______________________________________________________________________________
30

DESCRIPTION

32       Note:  Starting  with  version  0.8  the tar reader commands (contents,
33       stats, get, untar) support the GNU LongName extension (header type 'L')
34       for large paths.
35
36       ::tar::contents tarball ?-chan?
37              Returns  a  list of the files contained in tarball. The order is
38              not sorted and depends on the order files were stored in the ar‐
39              chive.
40
41              If the option -chan is present tarball is interpreted as an open
42              channel.  It is assumed that the channel was opened for reading,
43              and configured for binary input.  The command will not close the
44              channel.
45
46       ::tar::stat tarball ?file? ?-chan?
47              Returns a nested dict containing information on the named ?file?
48              in tarball, or all files if none is specified. The top level are
49              pairs of filename and info. The info is a  dict  with  the  keys
50              "mode  uid  gid  size  mtime  type linkname uname gname devmajor
51              devminor"
52
53
54              % ::tar::stat tarball.tar
55              foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
56
57
58       If the option -chan is present tarball is interpreted as an open  chan‐
59       nel.   It  is assumed that the channel was opened for reading, and con‐
60       figured for binary input.  The command will not close the channel.
61
62       ::tar::untar tarball args
63              Extracts tarball. -file and -glob limit the extraction to  files
64              which  exactly  match  or  pattern  match the given argument. No
65              error is thrown if no files match. Returns a list  of  filenames
66              extracted and the file size. The size will be null for non regu‐
67              lar files. Leading path seperators are stripped  so  paths  will
68              always be relative.
69
70              -dir dirName
71                     Directory to extract to. Uses pwd if none is specified
72
73              -file fileName
74                     Only extract the file with this name. The name is matched
75                     against the complete path stored in the archive including
76                     directories.
77
78              -glob pattern
79                     Only  extract files patching this glob style pattern. The
80                     pattern is matched against the complete  path  stored  in
81                     the archive.
82
83              -nooverwrite
84                     Dont overwrite files that already exist
85
86              -nomtime
87                     Leave  the  file  modification  time  as the current time
88                     instead of setting it to the value in the archive.
89
90              -noperms
91                     In Unix, leave the file permissions as the current  umask
92                     instead of setting them to the values in the archive.
93
94              -chan  If  this  option  is present tarball is interpreted as an
95                     open channel.  It is assumed that the channel was  opened
96                     for  reading,  and configured for binary input.  The com‐
97                     mand will not close the channel.
98
99
100
101              % foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
102              puts "Extracted $file ($size bytes)"
103              }
104
105
106       ::tar::get tarball fileName ?-chan?
107              Returns the contents of fileName from the tarball.
108
109
110
111              % set readme [::tar::get tarball.tar doc/README] {
112              % puts $readme
113              }
114
115
116       If the option -chan is present tarball is interpreted as an open  chan‐
117       nel.   It  is assumed that the channel was opened for reading, and con‐
118       figured for binary input.  The command will not close the channel.
119
120       An error is thrown when fileName is not found in the tar archive.
121
122       ::tar::create tarball files args
123              Creates a new tar file containing the files. files must be spec‐
124              ified as a single argument which is a proper list of filenames.
125
126              -dereference
127                     Normally create will store links as an actual link point‐
128                     ing at a file that may or may not exist in  the  archive.
129                     Specifying  this  option will cause the actual file point
130                     to by the link to be stored instead.
131
132              -chan  If this option is present tarball is  interpreted  as  an
133                     open  channel.  It is assumed that the channel was opened
134                     for writing, and configured for binary output.  The  com‐
135                     mand will not close the channel.
136
137
138
139              % ::tar::create new.tar [glob -nocomplain file*]
140              % ::tar::contents new.tar
141              file1 file2 file3
142
143
144       ::tar::add tarball files args
145              Appends  files to the end of the existing tarball. files must be
146              specified as a single argument which is a proper list  of  file‐
147              names.
148
149              -dereference
150                     Normally  add will store links as an actual link pointing
151                     at a file that may or may not exist in the archive. Spec‐
152                     ifying this option will cause the actual file point to by
153                     the link to be stored instead.
154
155              -prefix string
156                     Normally add will store  files  under  exactly  the  name
157                     specified  as argument. Specifying a ?-prefix? causes the
158                     string to be prepended to every name.
159
160              -quick The only sure way to find the  position  in  the  tarball
161                     where  new  files  can be added is to read it from start,
162                     but if tarball was written with a "blocksize"  of  1  (as
163                     this  package  does) then one can alternatively find this
164                     position by seeking from the  end.  The  ?-quick?  option
165                     tells add to do the latter.
166
167
168       ::tar::remove tarball files
169              Removes files from the tarball. No error will result if the file
170              does not exist in the tarball. Directory  write  permission  and
171              free  disk  space equivalent to at least the size of the tarball
172              will be needed.
173
174
175              % ::tar::remove new.tar {file2 file3}
176              % ::tar::contents new.tar
177              file3
178
179

BUGS, IDEAS, FEEDBACK

181       This document, and the package it describes, will  undoubtedly  contain
182       bugs and other problems.  Please report such in the category tar of the
183       Tcllib Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please  also
184       report  any  ideas  for  enhancements  you  may have for either package
185       and/or documentation.
186
187       When proposing code changes, please provide unified diffs, i.e the out‐
188       put of diff -u.
189
190       Note  further  that  attachments  are  strongly  preferred over inlined
191       patches. Attachments can be made by going  to  the  Edit  form  of  the
192       ticket  immediately  after  its  creation, and then using the left-most
193       button in the secondary navigation bar.
194

KEYWORDS

196       archive, tape archive, tar
197

CATEGORY

199       File formats
200
201
202
203tcllib                               0.11                               tar(n)
Impressum