1tar(n) Tar file handling tar(n)
2______________________________________________________________________________
6
8 tar - Tar file creation, extraction & manipulation
9
11 package require Tcl 8.4
12 package require tar ?0.11?
14 ::tar::contents tarball ?-chan?
16 ::tar::stat tarball ?file? ?-chan?
18 ::tar::untar tarball args
20 ::tar::get tarball fileName ?-chan?
22 ::tar::create tarball files args
24 ::tar::add tarball files args
26 ::tar::remove tarball files
28______________________________________________________________________________
30
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
37 For all commands, when using -chan ...
38 [1] It is assumed that the channel was opened for reading, and con‐
40 figured for binary input.
41 [2] It is assumed that the channel position is at the beginning of a
43 legal tar file.
44 [3] The commands will modify the channel position as they perform
46 their task.
47 [4] The commands will not close the channel.
49 [5] In other words, the commands leave the channel in a state very
51 likely unsuitable for use by further tar commands. Still doing
52 so will very likely results in errors, bad data, etc. pp.
53 [6] It is the responsibility of the user to seek the channel back to
55 a suitable position.
56 [7] When using a channel transformation which is not generally seek‐
58 able, for example gunzip, then it is the responsibility of the
59 user to (a) unstack the transformation before seeking the chan‐
60 nel back to a suitable position, and (b) for restacking it af‐
61 ter.
62
64 ::tar::contents tarball ?-chan?
65 Returns a list of the files contained in tarball. The order is
66 not sorted and depends on the order files were stored in the ar‐
67 chive.
68 If the option -chan is present tarball is interpreted as an open
70 channel. It is assumed that the channel was opened for reading,
71 and configured for binary input. The command will not close the
72 channel.
73 ::tar::stat tarball ?file? ?-chan?
75 Returns a nested dict containing information on the named ?file?
76 in tarball, or all files if none is specified. The top level are
77 pairs of filename and info. The info is a dict with the keys
78 "mode uid gid size mtime type linkname uname gname devmajor de‐
79 vminor"
80 % ::tar::stat tarball.tar
83 foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
84 If the option -chan is present tarball is interpreted as an open chan‐
87 nel. It is assumed that the channel was opened for reading, and con‐
88 figured for binary input. The command will not close the channel.
89 ::tar::untar tarball args
91 Extracts tarball. -file and -glob limit the extraction to files
92 which exactly match or pattern match the given argument. No er‐
93 ror is thrown if no files match. Returns a list of filenames ex‐
94 tracted and the file size. The size will be null for non regular
95 files. Leading path seperators are stripped so paths will always
96 be relative.
97 -dir dirName
99 Directory to extract to. Uses pwd if none is specified
100 -file fileName
102 Only extract the file with this name. The name is matched
103 against the complete path stored in the archive including
104 directories.
105 -glob pattern
107 Only extract files patching this glob style pattern. The
108 pattern is matched against the complete path stored in
109 the archive.
110 -nooverwrite
112 Dont overwrite files that already exist
113 -nomtime
115 Leave the file modification time as the current time in‐
116 stead of setting it to the value in the archive.
117 -noperms
119 In Unix, leave the file permissions as the current umask
120 instead of setting them to the values in the archive.
121 -chan If this option is present tarball is interpreted as an
123 open channel. It is assumed that the channel was opened
124 for reading, and configured for binary input. The com‐
125 mand will not close the channel.
126 % foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
130 puts "Extracted $file ($size bytes)"
131 }
132 ::tar::get tarball fileName ?-chan?
135 Returns the contents of fileName from the tarball.
136 % set readme [::tar::get tarball.tar doc/README] {
140 % puts $readme
141 }
142 If the option -chan is present tarball is interpreted as an open chan‐
145 nel. It is assumed that the channel was opened for reading, and con‐
146 figured for binary input. The command will not close the channel.
147 An error is thrown when fileName is not found in the tar archive.
149 ::tar::create tarball files args
151 Creates a new tar file containing the files. files must be spec‐
152 ified as a single argument which is a proper list of filenames.
153 -dereference
155 Normally create will store links as an actual link point‐
156 ing at a file that may or may not exist in the archive.
157 Specifying this option will cause the actual file point
158 to by the link to be stored instead.
159 -chan If this option is present tarball is interpreted as an
161 open channel. It is assumed that the channel was opened
162 for writing, and configured for binary output. The com‐
163 mand will not close the channel.
164 % ::tar::create new.tar [glob -nocomplain file*]
168 % ::tar::contents new.tar
169 file1 file2 file3
170 ::tar::add tarball files args
173 Appends files to the end of the existing tarball. files must be
174 specified as a single argument which is a proper list of file‐
175 names.
176 -dereference
178 Normally add will store links as an actual link pointing
179 at a file that may or may not exist in the archive. Spec‐
180 ifying this option will cause the actual file point to by
181 the link to be stored instead.
182 -prefix string
184 Normally add will store files under exactly the name
185 specified as argument. Specifying a ?-prefix? causes the
186 string to be prepended to every name.
187 -quick The only sure way to find the position in the tarball
189 where new files can be added is to read it from start,
190 but if tarball was written with a "blocksize" of 1 (as
191 this package does) then one can alternatively find this
192 position by seeking from the end. The ?-quick? option
193 tells add to do the latter.
194 ::tar::remove tarball files
197 Removes files from the tarball. No error will result if the file
198 does not exist in the tarball. Directory write permission and
199 free disk space equivalent to at least the size of the tarball
200 will be needed.
201 % ::tar::remove new.tar {file2 file3}
204 % ::tar::contents new.tar
205 file3
206
209 This document, and the package it describes, will undoubtedly contain
210 bugs and other problems. Please report such in the category tar of the
211 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
212 report any ideas for enhancements you may have for either package
213 and/or documentation.
214 When proposing code changes, please provide unified diffs, i.e the out‐
216 put of diff -u.
217 Note further that attachments are strongly preferred over inlined
219 patches. Attachments can be made by going to the Edit form of the
220 ticket immediately after its creation, and then using the left-most
221 button in the secondary navigation bar.
222
224 archive, tape archive, tar
225
227 File formats
228tcllib 0.11 tar(n)