1[vset PACKAGE_VERSION 0.11]
2[comment {-*- tcl -*- doctools manpage}]
3[manpage_begin tar n [vset PACKAGE_VERSION]]
4[keywords archive]
5[keywords {tape archive}]
6[keywords tar]
7[moddesc   {Tar file handling}]
8[titledesc {Tar file creation, extraction & manipulation}]
9[category  {File formats}]
10[require Tcl 8.4]
11[require tar [opt [vset PACKAGE_VERSION]]]
12[description]
13
14[para] Note: Starting with version 0.8 the tar reader commands
15(contents, stats, get, untar) support the GNU LongName extension
16(header type 'L') for large paths.
17
18[para]
19
20[list_begin definitions]
21
22[call [cmd ::tar::contents] [arg tarball] [opt [option -chan]]]
23
24Returns a list of the files contained in [arg tarball]. The order is not sorted and depends on the order
25files were stored in the archive.
26[para]
27
28If the option [option -chan] is present [arg tarball] is interpreted as an open channel.
29It is assumed that the channel was opened for reading, and configured for binary input.
30The command will [emph not] close the channel.
31
32[call [cmd ::tar::stat] [arg tarball] [opt file] [opt [option -chan]]]
33
34Returns a nested dict containing information on the named [opt file] in [arg tarball],
35or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys
36"[const mode] [const uid] [const gid] [const size] [const mtime] [const type] [const linkname] [const uname] [const gname]
37 [const devmajor] [const devminor]"
38
39[example {
40% ::tar::stat tarball.tar
41foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0}
42}]
43
44[para]
45If the option [option -chan] is present [arg tarball] is interpreted as an open channel.
46It is assumed that the channel was opened for reading, and configured for binary input.
47The command will [emph not] close the channel.
48
49[call [cmd ::tar::untar] [arg tarball] [arg args]]
50
51Extracts [arg tarball]. [arg -file] and [arg -glob] limit the extraction
52to files which exactly match or pattern match the given argument. No error is
53thrown if no files match. Returns a list of filenames extracted and the file
54size. The size will be null for non regular files. Leading path seperators are
55stripped so paths will always be relative.
56
57[list_begin options]
58[opt_def -dir dirName]
59Directory to extract to. Uses [cmd pwd] if none is specified
60[opt_def -file fileName]
61Only extract the file with this name. The name is matched against the complete path
62stored in the archive including directories.
63[opt_def -glob pattern]
64Only extract files patching this glob style pattern. The pattern is matched against the complete path
65stored in the archive.
66[opt_def -nooverwrite]
67Dont overwrite files that already exist
68[opt_def -nomtime]
69Leave the file modification time as the current time instead of setting it to the value in the archive.
70[opt_def -noperms]
71In Unix, leave the file permissions as the current umask instead of setting them to the values in the archive.
72
73[opt_def -chan]
74If this option is present [arg tarball] is interpreted as an open channel.
75It is assumed that the channel was opened for reading, and configured for binary input.
76The command will [emph not] close the channel.
77
78[list_end]
79[para]
80
81[example {
82% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] {
83puts "Extracted $file ($size bytes)"
84}
85}]
86
87[call [cmd ::tar::get] [arg tarball] [arg fileName] [opt [option -chan]]]
88
89Returns the contents of [arg fileName] from the [arg tarball].
90
91[para][example {
92% set readme [::tar::get tarball.tar doc/README] {
93% puts $readme
94}
95}]
96
97[para] If the option [option -chan] is present [arg tarball] is
98interpreted as an open channel.  It is assumed that the channel was
99opened for reading, and configured for binary input.  The command will
100[emph not] close the channel.
101
102[para] An error is thrown when [arg fileName] is not found in the tar
103archive.
104
105[call [cmd ::tar::create] [arg tarball] [arg files] [arg args]]
106
107Creates a new tar file containing the [arg files]. [arg files] must be specified
108as a single argument which is a proper list of filenames.
109
110[list_begin options]
111[opt_def -dereference]
112Normally [cmd create] will store links as an actual link pointing at a file that may
113or may not exist in the archive. Specifying this option will cause the actual file point to
114 by the link to be stored instead.
115
116[opt_def -chan]
117If this option is present [arg tarball] is interpreted as an open channel.
118It is assumed that the channel was opened for writing, and configured for binary output.
119The command will [emph not] close the channel.
120
121[list_end]
122[para]
123
124[example {
125% ::tar::create new.tar [glob -nocomplain file*]
126% ::tar::contents new.tar
127file1 file2 file3
128}]
129
130[call [cmd ::tar::add] [arg tarball] [arg files] [arg args]]
131
132Appends [arg files] to the end of the existing [arg tarball]. [arg files] must be specified
133as a single argument which is a proper list of filenames.
134
135[list_begin options]
136[opt_def -dereference]
137Normally [cmd add] will store links as an actual link pointing at a file that may
138or may not exist in the archive. Specifying this option will cause the actual file point to
139 by the link to be stored instead.
140[opt_def -prefix string]
141Normally [cmd add] will store files under exactly the name specified as
142argument. Specifying a [opt -prefix] causes the [arg string] to be
143prepended to every name.
144[opt_def -quick]
145The only sure way to find the position in the [arg tarball] where new
146files can be added is to read it from start, but if [arg tarball] was
147written with a "blocksize" of 1 (as this package does) then one can
148alternatively find this position by seeking from the end. The
149[opt -quick] option tells [cmd add] to do the latter.
150[list_end]
151[para]
152
153[call [cmd ::tar::remove] [arg tarball] [arg files]]
154
155Removes [arg files] from the [arg tarball]. No error will result if the file does not exist in the
156tarball. Directory write permission and free disk space equivalent to at least the size of the tarball
157will be needed.
158
159[example {
160% ::tar::remove new.tar {file2 file3}
161% ::tar::contents new.tar
162file3
163}]
164
165[list_end]
166
167[vset CATEGORY tar]
168[include ../common-text/feedback.inc]
169[manpage_end]
170